ExtendedJsonCreationUnit
|
Class name |
com.ebd.hub.datawizard.iu.ExtendedJsonCreationUnit |
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.
Parameters
|
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. |
|
Decode unicode values |
true, false |
false |
If false, certain characters (e.g. ", <, >) are replaced by Unicode escape sequences. If true, this is not done, except for the " character, which is replaced by \u0022. |
|
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 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"]