---
title: "XMLTOJSONTRANSLATOR activity"
slug: "bc-xmltojsontranslator-activity-setup"
tags: ["BC", "BIS", "Business Central", "Business Integration Solutions", "Concept", "Task"]
updated: 2026-06-25T09:59:07Z
published: 2026-06-25T09:59:07Z
canonical: "docs.staedean.com/bc-xmltojsontranslator-activity-setup"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staedean.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XMLTOJSONTRANSLATOR activity

In Business Integration Solutions, use the **XMLTOJSONTRANSLATOR** activity to translate an XML document into a JSON document.

## Usage

Use this activity to translate an XML document into a JSON document.

## Concept

Internal processing in Microsoft Dynamics 365 Business Central happens on documents in XML format. If your publishing partner requires data in JSON format, use the **XML to JSON Translator** activity to translate the document from XML into JSON.

To use this activity, define an internal or external document on which the incoming data translates.

## Setup

![XmlToJsonSetup](images/XMLTOJSON_Setup_1.png)

Setup for this activity splits into three sections: General setup, Policies setup, and Node policies setup.

### General Setup

| Field | Description |
| --- | --- |
| Source Document Type | The document type of the document representing the XML to translate. |
| Source Document No | The document number of the document representing the XML to translate. |
| Json Translator | The translator to use. Translators define in enum `BISJsonTranslator`. Currently `Business Integration Solutions` and `Business Integration Solutions Legacy` exist. `Business Integration Solutions` represents the latest version and is the default for new activities of this type. |
| Text Encoding | The encoding applied to the resulting document. Default: UTF-8. |

> [!NOTE]
> **Note**
> 
> The `Business Integration Solutions Legacy` translator is the old translator. It does not use all the policies and options shown below. Switch to the `Business Integration Solutions` translator.

### Policies setup

Policies represent settings for the translation.

![Policies](images/XMLTOJSON_Setup_Policies.png)

The following policies are available for XML to JSON: **ParseDataTypes**, **ParseNull**, **NullValue**, **AttributeBlockName**, **AttributePrefix**, **StripLevels**, **TextAlwaysAsProperty**, and **TextNodeName**.

#### ParseDataTypes

Accepts `True` or `False`.

Determines whether to convert data types into primitive JSON types. To determine whether a field translates into a primitive JSON type, the field data type in the document must not have type text.

Example:

Input:

```xml
100099.55true
```

ParseDataTypes `True`: `UnitPrice` outputs as `99.55` (number), `AllowInvoiceDisc` as `true` (boolean).

ParseDataTypes `False`: all values output as strings; `"99.55"`, `"true"`.

#### ParseNull and NullValue

ParseNull accepts `True` or `False`. NullValue accepts a text value; it is ignored if ParseNull is `False`.

Determines how an empty element value translates to JSON.

Example:

Input: `1000`

ParseNull `False` → `"CustomField": {}`

ParseNull `True`, NullValue `''` → `"CustomField": null`

ParseNull `True`, NullValue `-NULL-` → `"CustomField": "-NULL-"`

#### AttributeBlockName and AttributePrefix

AttributeBlockName and AttributePrefix accept a text value or an empty string.

If AttributeBlockName has a value, an additional object adds to the parent object to list the attributes.

If AttributePrefix has a value, attribute names add with that prefix.

Example:

Input: `Bicycle`

AttributeBlockName `''`, AttributePrefix `_` → `"_No": "1000"` alongside `"Description"`

AttributeBlockName `Attributes`, AttributePrefix `_` → attributes nest under `"Attributes": {"_No": "1000"}`

AttributeBlockName `Attributes`, AttributePrefix `''` → `"Attributes": {"No": "1000"}`

#### StripLevels

Accepts a number.

Determines the starting point of the object. Useful when the XML document needs stripping of opening elements.

Example:

Input:

```xml
1000Bicycle
```

StripLevels `0` → includes `"document"` wrapper

StripLevels `1` → starts at `"Item"` level

StripLevels `2` → starts at field level (`"No"`, `"Description"`)

> [!NOTE]
> **Note**
> 
> Levels cannot strip further if the element contains more than one child element.

You can also get an array as the root item in JSON output. With two `` nodes and StripLevels `2`, the output is a JSON array of item objects.

#### TextAlwaysAsProperty and TextNodeName

TextAlwaysAsProperty accepts `True` or `False`. TextNodeName accepts a text string and must have a value.

If `TextAlwaysAsProperty` is `True`, a text node wraps with a field named by `TextNodeName`. Mixed nodes (text node alongside other nodes) always wrap with the field specified in `TextNodeName`.

Example:

TextAlwaysAsProperty `False` → `"No": "1000"` (plain string)

TextAlwaysAsProperty `True`, TextNodeName `TEXT` → `"No": {"TEXT": "1000"}`

### Node policies setup

Node policies tie to specific nodes in the document. Only block nodes can have policies at this time.

#### TreatAsArray

Ensures that a JSON array outputs for a specific node, even if there is only one item.

Example:

Input: `1000`

TreatAsArray unchecked → `"Item": {"No": "1000"}` (object)

TreatAsArray checked → `"Item": [{"No": "1000"}]` (array)

#### WrapArray

Allows unwrapping of a list for a simpler JSON structure. Only applies when TreatAsArray is enabled for the node.

Example with two `` children:

WrapArray checked → `"Comments": {"Comment": ["Comment1","Comment2"]}`

WrapArray unchecked → `"Comments": ["Comment1","Comment2"]`

#### Promoted node

The **XMLTOJSONTRANSLATOR** supports promoting a node's value as a JSON object header. This lets JSON files have object keys that are not valid XML. Set this property at the linked document level; only available for non-block nodes. Only one promoted line is supported per document block.

![](https://cdn.document360.io/da662430-6a41-47b1-8c7e-7e4ac37a9756/Images/Documentation/image(530).png)

The behavior depends on the node policies set at the block level on the translator:

Promoted on `Item/No`, TreatAsArray and WrapArray unchecked → the value of `No` becomes the JSON object key, and `No` removes from the object body.

Promoted on `Item/No`, TreatAsArray checked, WrapArray unchecked → the array contains objects keyed by the `No` value.

Promoted on `Item/No`, TreatAsArray and WrapArray checked → similar to above but wrapped.

No property checked → standard output with all fields including `No` as normal properties.

## Related

- [Setting up activities](/bc-setting-up-activities.md)