Group	Integration Units
Function	This Integration Unit creates a JSON file from the target tree.

Description

Introduction: Integration Units. Set the Content in the Content settings of a Response Route in phase 6 to Output of IU.

This Integration Unit creates a JSON file from the target tree. We assume the knowledge about the structure of JSON files as a given.

The encoding of the file is always UTF-8.

The following shows how the structure of the profile's target tree, together with the Integration Unit, determines the structure of the generated JSON file.

Parameter Description

Parameter name	Allowed values	Default value	Description
Add JSON data at end	<Text>		Inserts text at the end of the generated JSON document (after the cutting).
Chars to cut off at the beginning	<Integer value>	0	Number of characters to be cut off at the beginning of the created JSON file. Note: If the JSON lines format is generated, the cutting is done per line. Note: The parameter is used to correct an invalid JSON file in order to obtain a valid one.
Chars to cut off at the end	<Integer value>	0	Number of characters to be cut off at the end of the created JSON file. Note: If the JSON lines format is generated, the cutting is done per line. Note: The parameter is used to correct an invalid JSON file in order to obtain a valid one.
Enable '_name' field handling	true, false	false	See parameter Use description as field/node name.
Escape < and >	true, false	false	The characters < and > are escaped by this Integration Unit. The result is < und > This option should be set to true if the Integration Unit is used for Forms. This can prevent JavaScript injection.
Insert JSON data at beginning	<Text>		Inserts text at the beginning of the generated JSON document (after the cutting).
Pretty print	true, false	true	If true, the JSON file is formatted. Note: If you set this parameter to true , please do not use the parameters Chars to cut off at the beginning and Chars to cut off at the end , as this can lead to errors in the generated file.
Resolve OData names	true, false	false	A name like @company.com would be allowed in JSON but is escaped in this Integration Unit. The result would be __at__company__dot__com If you do not want those characters to be escaped, set the option to true.
Start at node	<Node name>		If a node name is set, the creation of the JSON file starts with this node. If no value is specified or the value root, the (invisible) top-level node is used as the transparent node.
Use description as field/node name	true, false	false	If true, the value of attribute Description is used as node/field name. Note: If you want to rename a node during runtime, you can use a field with suffix _name to rename its parent node. The name of the JSON object is no longer determined by the name of the parent node but the value of the field (not name). The field name needs a prefix that is equal to the name of the parent node that shall be renamed. So if you want to rename parent node POS, you have to use field name POS_name. Important note: Parameter Enable '_name' field handling must have the value true for this. Note: You cannot use this method to rename the top level node (root node). Note: If a node is used to create an array (see node MyArray in the examples below), the field value of MyArray_name of the last iteration is used.
Write as JSON Lines Format	true, false	false	If true, the file is created in the JSON Lines format. See section Creating JSON Lines Format below.
Write empty '_val' arrays	true, false	false	When creating arrays with a node and _val field (see below), empty arrays are written if the parameter is set to true. If false, then not.
Write empty fields not as null	true, false	false	If true and parameter Write empty/null field values is also true, value "" will be used instead of value null.
Write empty/null field values	true, false	false	If true, fields with set Empty Flag will be included in the JSON document with value null. See also parameter Write empty fields not as null.
Write nodes without children	true, false	false	If true, nodes without fields, or if the fields have no values, are also output.
Write top level node as anonymous element	true, false	false	If true, the top-level node creates an anonymous element in the JSON file (i.e. without a name) . See sections Records and Creating Anonymous Top-level Element below . Important note: Parameter Start at node must be filled and parameter Write as JSON Lines Format must not have the value true.
Write values type safe	true, false	true	If true, fields of type Integer, Float, Double, BigInteger, BigDecimal and Boolean will not be written in quotes. Important note: This setting has no effect if a template is used.

Records

For one record, the structure {target tree} is created if the top level node creates an object.

For one record, the structure [target tree] is created if the top level node creates an array.

For multiple records, the structure [{target tree record 1},{target tree record 2}, ...] is created if the top level node creates an object.

For multiple records, the structure [target tree record 1, target tree record 2, ...] is created if the top level node creates an array.

Which JSON structure is created for the target tree is described in the sections below.

Note: See also section Creating Anonymous Top-level Element below.

Nodes - Creating Objects

...

Maximum = 1

A node of the target structure becomes an object in the JSON file, for node attributes Maximum = 1 and XML/JSON handling = Normal.

{
    "node": {
        "field1": "1",
        "field2": "4711",
        "field3": "C-100"
    }
}

Maximum > 1

A node of the target structure becomes an array of objects in the JSON file, for node attributes Maximum > 1 (so can occur multiple times) and XML/JSON handling = Normal.

{
    "node": [
        {
            "field1": "1",
            "field2": "4711",
            "field3": "C-100"
        },
        {
            "field1": "2",
            "field2": "0815",
            "field3": "C-200"
        }
    ]
}

Transparent

If you give attribute XML/JSON handling of a child node (here transparent_node) the value Transparent, the contents of the node will be resolved into the parent node when it creates an object. If the parent node is not an object, the transparent node becomes a normal object.

(Node node has the attributes Maximum > 1 and XML/JSON handling= Normal)

{
    "node": [
        {
            "field1": "1",
            "field2": "4711",
            "field3": "C-100",
            "field4": "something"
        }
    ]
}

The same transparent node (here transparent_node) must not be created more than once in the target tree, i.e. there must not be multiple instances of the same transparent node. If this happens, the Integration Unit terminates with an error.

However, it is possible to use additional transparent nodes in the target structure (i.e. with a different name) (i.e. transparent_node_2 or transparent_node#2, for example).

Nodes - Creating Arrays

...

Array

A node of the target structure becomes an array in the JSON file, for the node attribute XML/JSON handling = Array.

[
    [
        "1",
        "4711",
        "C-100"
    ]
]

Nodes that occur more than once are combined in one array.

[
    [
        "1",
        "4711",
        "C-100",
        "2",
        "0815",
        "C-200"
    ]
]

Array Grouped

If you set node attribute XML/JSON handling to Array Grouped here, a multidimensional array is created, i.e. arrays in an array.

[
	[
		"1",
		"4711",
		"C-100"
	],
	[
		"2",
		"0815",
		"C-200"
	]
]

Array Transparent

If you give the attribute XML/JSON handling of a child node (here node2) the value Array Transparent, the contents of the child node are resolved into the parent node if the parent node creates an array. If the parent node is not an array, an error occurs.

[
    [
        "1",
        "4711",
        "C-100",
        "something"
    ]
]

If the child node (here node2) has the value Array in attribute XML/JSON handling, the result is simply an array in the array.

[
    [
        "1",
        "4711",
        "C-100",
        [
            "something"
        ]
    ]
]

Further option

There is another outdated option that should be mentioned for the sake of completeness.

If you create a node (node attribute XML/JSON handling = Normal) that has exactly one field whose name corresponds to the node name and has the suffix _val appended, then an array is created from it. Note: See also parameter Write empty '_val' arrays.

[
    [
        "value_1",
        "value_2"
    ]
]

Nodes with the same name

Nodes with the same name (i.e. the name before the suffix #suffix) at the same hierarchy level are also combined into one array, but only if the parent node creates an object.

Node node has the attribute XML/JSON handling = Normal.

The nodes node2#1 and node2#2 have attribute XML/JSON handling = Normal and become:

...
        "node2": [
            {
                "field4": "something"
            },
            {
                "field5": "something_else"
            }
        ]
...

The nodes node2#1 and node2#2 have attribute XML/JSON handling = Array and become:

...
            "node2": [
                "something",
                "something_else"
            ]
...

The nodes node2#1 and node2#2 have attribute XML/JSON handling = Array Grouped and become:

...
            "node2": [
                [
                    "something"
                ],
                [
                    "something_else"
                ]
            ]
...

Excluding Nodes

...

If you give attribute XML/JSON handling of a node (here exluded_node) the value Exclude, this node will be ignored when creating the JSON file.

(Node node has the attribute Maximum > 1)

{
    "node": [
        {
            "field1": "1",
            "field2": "4711",
            "field3": "C-100"
        }
    ]
}

Fields - Creating Primitive Data Types

...

Fields of the target structure become primitive data types (i.e. string, number, etc. but not objects and arrays) in the JSON file.

Fields with the same name (i.e. the name before the suffix #suffix) are combined into an array of primitive data types in the JSON file if node attribute XML/JSON handling has the value Normal (i.e. an object is created).

(Node node has the attribute Maximum > 1)

{
    "node": [
        {
            "field1": "1",
            "field2": "4711",
            "field3": "C-100",
            "field4": [
                "something",
                "something_else"
            ]
        }
    ]
}

If the node attribute XML/JSON handling has the value Array, an array of all values is created.

{
    "node": [
        "1",
        "4711",
        "C-100",
        "something",
        "something_else"
    ]
}

Creating JSON Lines Format

...

Parameter Write as JSON Lines Format must have the value true.

To write object lines, the top-level node in the target structure (here node) must have the value Normal in node attribute XML/JSON handling.

{"field1":"1","field2":"4711","field3":"C-100"}
{"field1":"2","field2":"0815","field3":"C-200"}
{"field1":"3","field2":"0000","field3":"C-300"}

To write array lines, the top-level node in the target structure (here node) must have the value Array Grouped in node attribute XML/JSON handling.

["1","4711","C-100"]
["2","0815","C-200"]
["3","0000","C-300"]

If multiple records are created, each line is surrounded by square brackets [ ]. Note: See also parameters Chars to cut off at the beginning a nd Chars to cut off at the end .

Creating Anonymous Top-level Element

...

Node attributes Maximum = 1 and XML/JSON handling = Normal.

If the node node creates an object, you will receive the following JSON file with Write top level node as anonymous element=false.

{
    "node": {
        "field1": "1",
        "field2": "4711",
        "field3": "C-100"
    }
}

Here is the JSON file for Write top level node as anonymous element=true. Note: If there are multiple records, the parameter has no effect here.

{
	"field1": "1",
	"field2": "4711",
	"field3": "C-100"
}

If the node node creates an array (XML/JSON handling = Array), you will receive the following JSON file with Write top level node as anonymous element=false.

[
    [
        "1",
        "4711",
        "C-100"
    ]
]

Here is the JSON file for Write top level node as anonymous element=true. Note: If there are multiple records, only one array is created, so not an array of arrays.

[
	"1",
	"4711",
	"C-100"
]

ExtendedJsonCreationUnit