Importing XML and JSON Files

BCCL can import data into Business Central from both XML and JSON files using the PUTDATA task. Each format has slightly different configuration requirements, but both support the same mapping and validation features.

Importing XML Files

Basic XML Import

To import XML data, you need to specify the record element path using the -r parameter. This tells BCCL where to find the repeated record elements within the XML structure.

BCCL -t putdata -i customers.xml -m mapping.json -s table=18 -r /Customer/Record

The Record Path Parameter

The -r parameter defines the XPath-like path to the repeating record elements. BCCL reads all elements matching this path and imports each one as a record.

Example XML file (customers.xml):

<Customer>
  <Record>
    <Number>1000</Number>
    <Name>Erik Hougaard</Name>
    <City>Vancouver</City>
  </Record>
  <Record>
    <Number>2000</Number>
    <Name>Peter Hansson</Name>
    <City>Stockholm</City>
  </Record>
  <Record>
    <Number>3000</Number>
    <Name>Mads Mathiesen</Name>
    <City>Copenhagen</City>
  </Record>
</Customer>

For this structure, the record path is /Customer/Record.

XML Mapping

The MappedName in your mapping file must match the XML element names:

{
  "Customer": [
    {
      "FieldNo": 1,
      "FieldName": "No.",
      "MappedName": "Number",
      "Validate": "true"
    },
    {
      "FieldNo": 2,
      "FieldName": "Name",
      "MappedName": "Name",
      "Validate": "true"
    },
    {
      "FieldNo": 7,
      "FieldName": "City",
      "MappedName": "City",
      "Validate": "true"
    }
  ],
  "ValidateOnInsert": "true",
  "ValidateOnModify": "true"
}

Nested XML Structures

BCCL supports reading from nested XML structures. Adjust the -r path to match your document layout:

<data>
  <customers>
    <item>
      <Number>1000</Number>
      <Name>Customer A</Name>
    </item>
  </customers>
</data>

For this structure: -r /data/customers/item

XML-Safe Names

When exporting data, BCCL replaces special characters in field names with underscores to create XML-safe element names. When importing, the MappedName must match the actual XML element names in your input file.

Complete XML Import Example

# Step 1: Generate a mapping template
BCCL -t mapping -s table=18 -o customer-mapping.json

# Step 2: Edit the mapping file
# Set MappedName values to match your XML element names
# Set Validate to "true" for fields that need validation

# Step 3: Import the data
BCCL -t putdata -i customers.xml -m customer-mapping.json -s table=18 -r /Customer/Record

Expected result:

{
  "Table": 18,
  "Inserted": 3,
  "Modified": 0
}

Importing JSON Files

Basic JSON Import

JSON is the simplest format to import because it requires no record path specification. The input must be a JSON array of objects.

BCCL -t putdata -i customers.json -m mapping.json -s table=18

JSON File Structure

The input file must be a JSON array where each object represents one record:

[
  {
    "Number": "1000",
    "Name": "Erik Hougaard",
    "City": "Vancouver"
  },
  {
    "Number": "2000",
    "Name": "Peter Hansson",
    "City": "Stockholm"
  },
  {
    "Number": "3000",
    "Name": "Mads Mathiesen",
    "City": "Copenhagen"
  }
]

JSON Mapping

The MappedName in your mapping file must match the JSON property names:

{
  "Customer": [
    {
      "FieldNo": 1,
      "FieldName": "No.",
      "MappedName": "Number",
      "Validate": "true"
    },
    {
      "FieldNo": 2,
      "FieldName": "Name",
      "MappedName": "Name",
      "Validate": "true"
    },
    {
      "FieldNo": 7,
      "FieldName": "City",
      "MappedName": "City",
      "Validate": "true"
    }
  ],
  "ValidateOnInsert": "true",
  "ValidateOnModify": "true"
}

JSON Without a Mapping File

If the JSON property names exactly match the Business Central field names, you can omit the mapping file. However, this is rarely the case since BC field names often contain special characters (periods, parentheses, spaces) that are not typical in JSON.

Complete JSON Import Example

# Step 1: Generate a mapping template
BCCL -t mapping -s table=18 -o customer-mapping.json

# Step 2: Edit the mapping
# Match MappedName to your JSON property names

# Step 3: Import
BCCL -t putdata -i customers.json -m customer-mapping.json -s table=18

Common Features for Both Formats

Insert vs. Modify Behavior

BCCL uses upsert logic for both XML and JSON imports:

If a record with matching primary key does not exist, it is inserted
If a record with matching primary key already exists, it is modified

The result JSON reports both counts:

{
  "Table": 18,
  "Inserted": 2,
  "Modified": 1
}

Validation Settings

Both formats support the same validation options in the mapping file:

Setting	Description
`Validate`	Validate this specific field on insert/modify
`ValidateOnInsert`	Trigger the table's OnInsert event
`ValidateOnModify`	Trigger the table's OnModify event

Format Auto-Detection

BCCL auto-detects the format from the input file extension:

.xml files are treated as XML
.json files are treated as JSON

You can also explicitly specify: -f xml or -f json.

Paging for Large Files

Large import files are automatically split into batches based on the page size (-z, default 1000 records). Each batch is sent to Business Central as a separate web service call and committed independently.

Automatic Number Series

To let Business Central assign numbers automatically (using the configured number series), simply omit the primary key field from your mapping file. BCCL will insert records without specifying the primary key, and BC will assign the next number from the series.

Tips and Best Practices

Generate a mapping template first (-t mapping) and edit it to match your input structure
Use JSON when working with web APIs or JavaScript-based systems
Use XML when integrating with enterprise systems or XSLT-based workflows
Always validate your input files are well-formed before importing
Test with a small dataset first, then import the full dataset
Use -v (verbose) to see detailed progress during import