ExtendedJsonCreationUnit

Gruppe

Integration Units

Funktion

Diese Integration Unit erzeugt aus dem Zielbaum eine JSON-Datei.

Beschreibung


Diese Integration Unit erzeugt aus dem Zielbaum eine JSON-Datei. Wir setzen hier das Wissen über den Aufbau von JSON-Dateien voraus.

Die Kodierung der Datei ist immer UTF-8.

Im Folgenden wird gezeigt, wie der Aufbau des Zielbaums des Profils, zusammen mit der Integration Unit, die Struktur der erzeugten JSON-Datei bestimmt.

Beschreibung der Parameter


Parametername

Erlaubte Werte

Default-Wert

Beschreibung

Add JSON data at end

<Text>

Fügt Text am Ende des erzeugten JSON-Dokuments ein (nach dem Cutting).

Chars to cut off at the beginning

<Ganzzahl>

0

Anzahl der Zeichen, die am Anfang der fertig erstellten JSON-Datei abgeschnitten werden sollen. Hinweis: Wird das JSON-Lines-Format erzeugt, dann wird pro Zeile abgeschnitten. Hinweis: Der Parameter dient dazu eine invalide JSON-Datei zu korrigieren, um eine valide zu erhalten.

Chars to cut off at the end

<Ganzzahl>

0

Anzahl der Zeichen, die am Ende der fertig erstellten JSON-Datei abgeschnitten werden sollen. Hinweis: Wird das JSON-Lines-Format erzeugt, dann wird pro Zeile abgeschnitten. Hinweis: Der Parameter dient dazu eine invalide JSON-Datei zu korrigieren, um eine valide zu erhalten.

Enable '_name' field handling

true, false

false

Siehe Parameter Use description as field/node name.

Decode unicode values

true, false

false

Wenn false, dann werden bestimmte Zeichen (z. B. ", <, >) durch Unicode-Escape-Sequences ersetzt. Bei true wird das nicht gemacht, außer beim Zeichen ", welches ersetzt wird durch \u0022.

Escape < and >

true, false

false

Die beiden Zeichen < und > werden von der Integration Unit maskiert (escaped). Das Ergebnis ist &lt; und &gt;

Diese Option sollte auf true gestellt werden, falls die Integration Unit für Formulare benutzt wird. Damit kann man JavaScript Injection unterbinden.

Insert JSON data at beginning

<Text>

Fügt Text am Anfang des erzeugten JSON-Dokuments ein (nach dem Cutting).

Pretty print

true, false

true

Falls true, wird die JSON-Datei formatiert erzeugt. Hinweis: Wenn Sie diesen Parameter auf true setzen, dann verwenden Sie bitte nicht die Parameter Chars to cut off at the beginning und Chars to cut off at the end , da dies zu Fehlern in der erzeugten Datei führen kann.

Resolve OData names

true, false

false

Ein Name wie @company.com wäre in JSON erlaubt, wird aber von dieser Integration Unit maskiert (escaped). Das Ergebnis wäre __at__company__dot__com

Soll diese Maskierung nicht vorgenommen werden, dann setzen Sie diese Option auf true.

Start at node

<Knotenname>


Ist ein Knotenname gesetzt, beginnt die Erzeugung der JSON-Datei erst bei diesem Knoten. Ist kein Wert angegeben oder der Wert root, dann wird der (nicht sichtbare) Top-Level-Knoten als transparenter Knoten verwendet.

Use description as field/node name

true, false

false

Bei true wird der Knoten-/Feld-Name aus dem Wert des Attributs Beschreibung erzeugt.

Hinweis: Will man den Namen eines Knotens zur Laufzeit generieren, kann ein Feld mit Suffix _name zur Umbenennen des zugehörigen Oberknoten verwendet werden. Der Name des JSON-Objekts wird dann nicht mehr aus dem Knotennamen erzeugt, sondern aus dem Wert (nicht Namen) des Feldes. Als Präfix des Feldnamens muss der Name des umzubenennenden Knotens verwendet werden. Soll also Oberknoten POS umbenannt werden, muss das Umbenennungsfeld POS_name heißen. Wichtiger Hinweis: Der Parameter Enable '_name' field handling muss dazu den Wert true haben. Hinweis: Mit dieser Methode kann nicht der Top-Level-Knoten (Root-Knoten) umbenannt werden. Hinweis: Wird über einen Knoten ein Array erzeugt (siehe Knoten MyArray in den Beispielen unten), dann wird der Feldwert von MyArray_name der letzten Iteration verwendet.

Write as JSON Lines Format

true, false

false

Falls true, wird die Datei im JSON-Lines-Format erzeugt. Siehe Abschnitt JSON-Lines-Format erzeugen unten.

Write empty '_val' arrays

true, false

false

Falls true, dann wird bei der Erzeugung von Arrays über Knoten und _val-Feld (siehe unten) auch ein leeres Array geschrieben. Bei false nicht.

Write empty fields not as null

true, false

false

Falls true und Parameter Write empty/null field values ist auch true, dann wird statt dem Wert null der Wert "" geschrieben.

Write empty/null field values

true, false

false

Falls true, werden Felder mit gesetztem Empty Flag in das JSON-Dokument übernommen mit Wert null. Siehe auch Parameter Write empty fields not as null.

Write nodes without children

true, false

false

Falls true, werden auch Knoten ohne Felder ausgegeben.

Write top level node as anonymous element

true, false

false

Bei true wird aus dem Top-Level-Knoten ein anonymes Element in der JSON-Datei erzeugt (also ohne Namen). Siehe dazu die Abschnitte Datenblätter und Anonymes Top-Level-Element erzeugen unten. Wichtiger Hinweis: Der Parameter Start at node muss gefüllt sein und der Parameter Write as JSON Lines Format darf nicht den Wert true haben.

Write values type safe

true, false

true

Falls true, werden bei Feldern vom Typ Integer, Float, Double, BigInteger, BigDecimal und Boolean keine Hochkommas gesetzt. Wichtiger Hinweis: Diese Einstellung greift nicht, wenn eine Vorlage verwendet wird.

Datenblätter


Bei einem Datenblatt wird die Struktur {Zielbaum} erzeugt, wenn der Top-Level-Knoten ein Objekt erzeugt.

Bei einem Datenblatt wird die Struktur [Zielbaum] erzeugt, wenn der Top-Level-Knoten ein Array erzeugt.

Bei mehreren Datenblättern wird die Struktur [{Zielbaum Datenblatt 1},{Zielbaum Datenblatt 2}, ...] erzeugt, wenn der Top-Level-Knoten ein Objekt erzeugt.

Bei mehreren Datenblättern wird die Struktur [Zielbaum Datenblatt 1, Zielbaum Datenblatt 2, ...] erzeugt, wenn der Top-Level-Knoten ein Array erzeugt.

Welche JSON-Struktur für den Zielbaum erzeugt wird, ist in den Abschnitten unten beschrieben.

Hinweis: Siehe auch Abschnitt Anonymes Top-Level-Element erzeugen unten.

Knoten - Objekte erzeugen


Maximum = 1

Aus einem Knoten der Zielstruktur wird in der JSON-Datei ein Objekt, für die Knoten-Eigenschaften Maximum = 1 und XML/JSON Behandlung = Normal.


images/download/attachments/137299735/1681-version-1-modificationdate-1692002049647-api-v2.png


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

Maximum > 1

Aus einem Knoten der Zielstruktur wird in der JSON-Datei ein Array von Objekten, für die Knoten-Eigenschaften Maximum > 1 (kann also mehrfach auftreten) und XML/JSON Behandlung = Normal.


images/download/attachments/137299735/1683-version-1-modificationdate-1692002049670-api-v2.png


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

Transparent

Gibt man der Eigenschaft XML/JSON Behandlung eines Unterknotens (hier transparent_node) den Wert Transparent, dann löst sich der Inhalt des Knotens im darüberliegenden Knoten auf, wenn dieser ein Objekt erzeugt. Ist der darüberliegenden Knoten kein Objekt, wird aus dem transparenten Knoten ein normales Objekt.

(Der Knoten node hat hier die Eigenschaften Maximum > 1 und XML/JSON Behandlung = Normal)


images/download/attachments/137299735/1677-version-1-modificationdate-1692002049704-api-v2.png


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


Derselbe transparente Knoten (hier transparent_node) darf dabei aber im Zielbaum nicht mehrfach erzeugt werden, d. h. es darf nicht mehrere Instanzen des selben transparenten Knotens geben. Falls das passiert, bricht die Integration Unit mit einem Fehler ab.

Es ist allerdings möglich weitere transparente Knoten in der Zielstruktur (also mit anderem Namen) zu verwenden (also z. B. transparent_node_2 oder transparent_node#2).

Knoten - Arrays erzeugen


Array

Aus einem Knoten der Zielstruktur wird in der JSON-Datei ein Array, für die Knoten-Eigenschaft XML/JSON Behandlung = Array.



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

Mehrfach auftretende Knoten werden in einem Array zusammengefasst.


images/download/attachments/137299735/1686-version-1-modificationdate-1692002049735-api-v2.png


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

Array Grouped

Stellt man hier die Knoten-Eigenschaft XML/JSON Behandlung auf Array Grouped, dann wird ein mehrdimensionales Array erzeugt, also Arrays in einem Array.


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

Array Transparent

Gibt man der Eigenschaft XML/JSON Behandlung eines Unterknotens (hier node2) den Wert Array Transparent, dann löst sich der Inhalt des Unterknotens im darüberliegenden Knoten auf, wenn dieser ein Array erzeugt. Ist der darüberliegenden Knoten kein Array, entsteht ein Fehler.


images/download/attachments/137299735/1688-version-1-modificationdate-1692002049750-api-v2.png


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


Hat der Unterknoten (hier node2) in der Eigenschaft XML/JSON Behandlung den Wert Array, dann entsteht einfach nur ein Array im Array.


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

Weitere Möglichkeit

Es gibt eine weitere Möglichkeit, die an sich veraltet ist, aber der Vollständigkeit halber dennoch erwähnt werden soll.

Wenn Sie einen Knoten anlegen (Knoten-Eigenschaft XML/JSON Behandlung = Normal), der genau ein Feld hat, dessen Name dem Knotennamen entspricht und das Suffix _val angehängt hat, dann entsteht daraus ein Array. Hinweis: Siehe auch Parameter Write empty '_val' arrays.


images/download/attachments/137299735/1689-version-1-modificationdate-1692243757643-api-v2.png


[
[
"value_1",
"value_2"
]
]

Knoten mit gleichen Namen

Knoten mit gleichen Namen (also der Name vor dem Suffix #suffix) auf der selben Hierarchie-Ebene werden ebenfalls in einem Array zusammengefasst, aber nur wenn der Oberknoten ein Objekt erzeugt.

Der Knoten "node" hat hier die Eigenschaften "XML/JSON Behandlung = Normal".


images/download/attachments/137299735/1679-version-1-modificationdate-1692002049688-api-v2.png


Die Knoten "node2#1" und "node2#2" haben die Eigenschaften "XML/JSON Behandlung = Normal" und werden zu:

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


Die Knoten "node2#1" und "node2#2" haben die Eigenschaften "XML/JSON Behandlung = Array" und werden zu:

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


Die Knoten "node2#1" und "node2#2" haben die Eigenschaften "XML/JSON Behandlung = Array Grouped" und werden zu:

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

Knoten exkludieren


images/download/attachments/137299735/1676-version-1-modificationdate-1692002049763-api-v2.png

Gibt man der Eigenschaft XML/JSON Behandlung eines Knotens (hier exluded_node) den Wert Exkludieren, dann wird dieser Knoten beim Erzeugen der JSON-Datei ignoriert.

(Der Knoten node hat hier die Eigenschaft Maximum > 1)


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

Felder - Primitive Datentypen erzeugen


Aus Feldern der Zielstruktur werden in der JSON-Datei primitive Datentypen (also String, Number, usw. aber keine Objekte und Arrays).

Gleichnamige Felder (also der Name vor dem Suffix #suffix) werden in der JSON-Datei zu einem Array von primitiven Datentypen zusammengefasst, wenn die Knoten-Eigenschaft XML/JSON Behandlung den Wert Normal hat (also ein Objekt erzeugt wird).

(Der Knoten node hat die Eigenschaft Maximum > 1)


images/download/attachments/137299735/1678-version-1-modificationdate-1692002049777-api-v2.png


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


Hat die Knoten-Eigenschaft XML/JSON Behandlung den Wert Array, dann entsteht einfach nur ein Array aus allen Werten.


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

JSON-Lines-Format erzeugen


Der Parameter Write as JSON Lines Format muss hier den Wert true haben.


images/download/attachments/137299735/1684-version-1-modificationdate-1692002049792-api-v2.png


Um Objekt-Zeilen zu schreiben, muss der oberste Knoten in der Zielstruktur (hier node) den Wert Normal in der Knoten-Eigenschaft XML/JSON Behandlung haben.


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


Um Array-Zeilen zu schreiben, muss der oberste Knoten in der Zielstruktur (hier node) den Wert Array Grouped in der Knoten-Eigenschaft XML/JSON Behandlung haben.

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


Wenn mehrere Datenblätter entstehen, wird jede Zeile von eckigen Klammern [ ] umgeben. Hinweis: Siehe auch Parameter Chars to cut off at the beginning und Chars to cut off at the end.

Anonymes Top-Level-Element erzeugen


images/download/attachments/137299735/1681-version-1-modificationdate-1692002049647-api-v2.png


Knoten-Eigenschaften Maximum = 1 und XML/JSON Behandlung = Normal.

Erzeugt der Knoten node ein Objekt, bekommen Sie bei Write top level node as anonymous element=false folgende JSON-Datei.


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


Hier die JSON-Datei bei Write top level node as anonymous element=true. Hinweis: Bei mehreren Datenblättern hat der Parameter hier keinen Effekt.


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


Erzeugt der Knoten node ein Array (XML/JSON Behandlung = Array), bekommen Sie bei Write top level node as anonymous element=false folgende JSON-Datei.


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

Hier die JSON-Datei bei Write top level node as anonymous element=true. Hinweis: Bei mehreren Datenblättern wird hier zu einem Array zusammengefasst, es entsteht also kein Array von Arrays.

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