Gruppe	Integration Units
Klassenname	com.ebd.hub.datawizard.iu.XMLNoTemplateUnit
Funktion	Erzeugt ein XML aus einem Ausgangsbaum ohne Template-Datei.

Beschreibung

Einleitung: Integration Units.

Die XMLNoTemplateUnit erzeugt aus dem angegebenen Zielbaum ein XML, wobei hier kein Template benötigt wird, wie bei der XMLTemplateParserUnit und der XMLMemSaveTemplateParserUnit, verwenden Sie deshalb bevorzugt diese Integration Unit hier. Zu beachten ist jedoch, dass die Zielstruktur entsprechend einiger Regeln aufgebaut werden muss. Dazu mehr weiter unten.

Beschreibung der Parameter

Parametername	Erlaubte Werte	Default-Wert	Beschreibung
Certificate-ID for signing			Wird der Parameter mit einer gültigen (eigenen) Zertifikats-ID gefüllt (also privater Schlüssel vorhanden), wird die XML-Datei signiert. Die ID kann man einfach aus der Zertifikats-Detail-Ansicht kopieren (Seriennummer).
Force Carriage Return (\r -> \r\n)	true, false	false	\n bleibt \n, aber ein \r wird zu \r\n und damit zu #&xD\n; (gilt nur für den Daten-Teil). Beispiel: <Text1\r\nText2> wird zu <Text1 Text2>
Insert this DOCTYPE declaration			Die DOCTYPE-Deklaration, die nach der Generierung des XML eingesetzt werden soll. Hinweis: Möchten Sie einen anderen als den Default-XML-Header <?xml version="1.0" encoding="UTF-8"?> verwenden, dann können Sie diesen hier angeben. Verwenden Sie dann zusätzlich den Parameter Without XML-Header=true, um den Default-XML-Header zu entfernen.
Mem save swap threshold		1000	Bei Verwendung der speichersicheren Variante (Use mem save method = true) wird hier der Schwellwert angegeben, ab wie vielen Elementen in das Dateisystem ausgelagert wird.
Pretty format	true, false	true	true erzeugt eine Formatierung mit Einrückungen (2 Leerzeichen). Bei false erfolgen keine Einrückungen. Hinweis: Ist der Parameter Write xml in a single line auf true gesetzt, dann hat die Einstellung hier keine Wirkung.
Remove given prefix from field or node name			Schneidet jedes benutzerdefinierte Präfix ab. Hinweis: Bitte beachten Sie, dass diese Aktion vor der im folgenden Parameter beschriebenen ausgeführt wird.
Replace D-_... and F-_... to _...		false	Feldnamen D-_... und F-_... werden ersetzen durch _... (also "D-" und "F-" werden weggeschnitten).
Root node name			Knoten der Zielstruktur, ab welchem das XML erzeugt wird (Pflichtwert).
Text mode (…)	normalize, preserve, trim, trim-full-white	trim-full-white	Regelt die Art, wie Werte in das XML aufgenommen werden sollen. preserve - Der Text wird unverändert übernommen. Alle Leerzeichen (führend, nachfolgend, …) verbleiben im XML. trim-full-white - Siehe preserve mit der Ausnahme, dass ein Text, der nur aus Leerzeichen besteht, durch einen leeren Text ersetzt wird. trim - Alle führenden und nachfolgenden Leerzeichen werden entfernt. normalize - Siehe trim mit der zusätzlichen Funktion, dass aufeinander folgende, innere Leerzeichen zu einem einzelnen zusammengefasst werden (..1..2.. → 1.2, ein Punkt repräsentiert ein Leerzeichen).
Use XML short form for empty fields	true, false	false	Gibt an, ob bei leeren XML-Elementen die Kurzschreibweise verwendet wird, also <element/> anstatt <element></element>.
Use mem save method	true, false	true	Wird die speichersichere Methode verwendet, werden Elemente bei der Erzeugung ins Dateisystem ausgelagert. Dies ist die bevorzugte Variante bei größeren Datenmengen.
Use namespace Inheritance	true, false	false	Gibt an, ob Namespaces vererbt werden sollen oder nicht.
With empty fields	true, false	false	true, wenn leere Elemente (_attr und _val leer) im resultierenden XML verbleiben sollen. Hinweis: Ist diese Option auf true gesetzt, dann werden auch "versteckte Werte" (siehe entsprechenden Abschnitt in den Erklärungen zum Empty Flag) in die Ausgangsdatei geschrieben (z. B. Default-Datumswerte bei erfolglos geparsten Werten für Quellstruktur-Datumsfelder).
Without XML-Header	true, false	false	true, falls der XML-Header (z. B. <?xml version="1.0" encoding="UTF-8i"?>) nicht erzeugt werden soll.
Write mandatory empty fields	true, false	false	true, falls leere Pflichtfelder im XML erzeugt werden sollen.
Write values containing white spaces only	true, false	false	Bei true werden Elementinhalte, welche nur aus Leerzeichen bestehen, nicht als "leer" behandelt.
Write xml in a single line	true, false	false	true, wenn das resultierende XML nur in einer Zeile stehen soll.
end of line		\n	Zeichen welches am Ende einer Zeile eingefügt werden soll.
file encoding		UTF-8	Des Name des Zeichensatzes, der in den XML-Header aufgenommen werden soll. Achtung: Der gleiche Zeichensatz muss beim entsprechenden Ausgangsweg in Phase 6 des Profils angegeben werden, damit die Datei auch tatsächlich damit ausgegeben wird. Ansonsten ist mit Fehlern auf Leseseite zu rechnen (Pflichtwert).

Kontrollelemente im Zielbaum für die XML-Erzeugung

Um den Aufbau von XML-Elementen im Zielbaum steuern zu können, werden Eigenschaften in Zielknoten/Feldern, sowie spezielle Felder, mit reservierten Namensendungen verwendet.

Eigenschaften im Zielknoten

XML Namespace: Über diese Eigenschaft kann dem Element, welches aus dem Knoten erzeugt wird, ein XML-Namespace zugeordnet werden, z. B: soapenv. Alle im Knoten enthaltenen Elemente bekommen so automatisch den selben Namespace, insofern dort kein anderer gesetzt ist. Zusätzlich kann über diese Eigenschaft auch ein Namespace definiert werden. Beispiel: soapenv=http://schemas.xmlsoap.org/soap/envelope/. Soll kein Namespace angegeben werden obwohl die Eigenschaft Use namespace Inheritance gesetzt ist, muss DEFAULT eingetragen werden. Um einen Default-Namespace zu definieren(z. B. <element xmlns="http://tempuri.org/"> ) muss die Eigenschaft wie folgt gesetzt werden: DEFAULT=http://tempuri.org/

XML/JSON Behandlung: Diese Eigenschaft steuert, in welcher Form der Knoten in das XML aufgenommen wird. Folgende Einstellungen sind möglich:

- Normal: Der Knoten wird als Element im XML erzeugt.
- Exkludieren: Der Knoten wird bei der Erzeugung ignoriert und somit gar nicht betreten.
- Transparent: Der Knoten selbst erzeugt kein XML Element, aber der Inhalt im Knoten wird berücksichtigt.
- Array: (Dieser Wert ist nicht relevant für diese Funktion.)
- Array Transparent: (Dieser Wert ist nicht relevant für diese Funktion.)
Maximum: Erzeugt ein Mapping mehrere Datenblätter, dann wird ein Knoten über diese Datenblätter hinweg betrachtet mehrfach erzeugt. Hat nun der Knoten den Wert 1 bei der Knoten-Eigenschaft Maximum, dann wird das dem Knoten entsprechende Element im XML nur einmal erzeugt, die Felder des mehrfach vorhandenen Knoten werden im einfach vorhandenen XML-Element alle untereinander gelistet. Ist dieses Verhalten nicht erwünscht, dann z. B. einfach den Wert 99999 verwenden für Eigenschaft Maximum. Hier ein angedeutetes Beispiel:

images/download/attachments/36575000/XML_IU_Maximum-version-1-modificationdate-1560828148000-api-v2.png

Eigenschaften im Zielfeld

XML Namespace: Über diese Eigenschaft kann dem Element, welches aus dem Feld erzeugt wird, ein XML-Namespace zugeordnet werden, z. B: soapenv. Zusätzlich kann über diese Eigenschaft auch ein Namespace definiert werden. Beispiel: soapenv=http://schemas.xmlsoap.org/soap/envelope/. Soll kein Namespace angegeben werden obwohl die Eigenschaft gesetzt ist, muss DEFAULT eingetragen werden.

Reservierte Feldnamen zur Steuerung

Innerhalb eines Knotens können Felder angelegt werden, die eine weitere Steuerung ermöglichen. Dabei sind folgende Endungen in den Feldnamen reserviert.

_val: Ein Feld mit dieser Endung enthält den Wert des XML Elements.
_attr: (z. B. id_attr) Über Felder mit dieser Endung können dem XML-Element Attribute hinzugefügt werden. Im Beispiel würde hier das Attribut id dem Element hinzugefügt.
_nsdef: (z. B. xsd_nsdef) Im XML-Element wird ein weiterer Namespace (hier xsd) definiert. Der Inhalt des Feldes entspricht dem Namespace, also z. B. http://www.w3.org/2001/XMLSchema.
_name: Feld zum Umbenennen des XML-Elements, das aus dem zugehörigen Oberknoten erstellt wird. Der Name des XML-Elements 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.

Beispielstruktur:

Felder xsd_nsdef, TYPE_attr, POSNO_val und POS_name haben die Fixwerte http://www.w3.org/2001/XMLSchema, M, 1 und POSITION.

Daraus erstellte XML-Datei:

Wie Sie sehen können wurde aus dem Knoten Pos das XML-Element POSITION (wegen Fixwert POSITION von Feld POS_name).

images/download/attachments/36575000/sample_xml-version-1-modificationdate-1560826958000-api-v2.png

Numerischer Suffix zur Eindeutigkeit

In XML können Elemente mit dem gleichen Namen in verschiedenen Hierarchieebenen des XML-Dokuments auftreten. Um die Eindeutigkeit der Namen aller Knoten und Felder in einem Profil zu gewährleisten, muss man daher an jeden mehrfach verwendeten Namen einen numerischen Suffix anhängen. Die Reihenfolge der Suffix-Nummern ist dabei unwichtig.

Suffix im Zielbaum: #<Nummer>

In reservierten Feldnamen (siehe oben) muss dieser numerische Suffix noch vor den reservierten Feldnamen stehen. Beide tauchen in den Namen des erzeugten XML-Dokuments nicht mehr auf. Beispiel: TYPE#15_attr

Beispiel zum numerischen Suffix und reservierten Feldnamen

In einem XML-Dokument kann z. B. ein Element TYPE an mehreren Stellen der Hierarchie auftreten und zusätzlich noch ein Attribut TYPE zu anderen Elementen (die nicht TYPE heißen) zugeordnet werden.

<ORDER TYPE ="abc">
	<ADDR>
		<TYPE quali="17">WE</TYPE>
		...
	</ADDR>
	<POSITION TYPE="xyz">
	...
	</POSITION>
	<TYPEDEFINITIONS>
		<TYPE source="Buyer">BY</TYPE>
		<TYPE source="Seller">SE</TYPE>
		...
	</TYPEDEFINITIONS>
</ORDER>

Eine dazu passende Zielstruktur wäre zum Beispiel die folgende.

Element ORDER hat ein Attribut TYPE. Es wird durch den Knoten ORDER#14 mit dem Feld TYPE#15_attr dargestellt. Das Kennzeichen _attr steht ganz am Ende, also hinter dem Nummern-Suffix.

Element TYPE innerhalb ADDR hat ein Attribut quali und einen Wert. Es wird durch den Knoten TYPE#17, das Attribut-Feld quali#18_attr und das Wert-Feld TYPE#17_val dargestellt. Bei dem Wert-Feld steht das Kennzeichen _val ebenfalls am Ende hinter der laufenden Nummer. Davor muss der Name des Knotens einschließlich der laufenden Nummer stehen.

Innerhalb des Elements TYPEDEFINITIONS können mehrere Elemente TYPE mit Attribut source und Wert stehen. Das wird durch den Knoten TYPE#22 mit dem Wert-Feld TYPE#22_val und dem Attribut-Feld source#24_attr dargestellt. Auch wenn das Attribut fehlen würde, könnte das Element TYPE mit verschiedenen Werten mehrfach innerhalb TYPEDEFINITIONS auftreten.

Beispiel zur Zielknoten-Eigenschaft XML Behandung

Gegeben ist folgende Zielstruktur.

Der Knoten root#1 ist bei der XML Behandlung als Root definiert. Anhand der Änderung der Behandlung im Knoten user#3 wird gezeigt, welche Auswirkungen die unterschiedlichen Parameter haben. Folgende XML-Datei wird beim gegebenen Mapping ausgegeben, mit folgender Behandlung im user#3-Knoten.

Normal

Es wird jeder Wert und Knoten ausgegeben.

xml_no_template_normal.xml

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <record art="root" type="map">
    <scm:user xmlns:scm="http://scm.de" scm:type="object">
      <scm:name scm:type="String">name</scm:name>
      <scm:givenName scm:type="String">given</scm:givenName>
    </scm:user>
    <items type="array">
      <arrayItem type="object">
        <item type="String">abc</item>
        <itemType type="String">ALL</itemType>
      </arrayItem>
      <arrayItem type="object">
        <item type="String">cde</item>
        <itemType type="String">ALL</itemType>
      </arrayItem>
    </items>
    <persons test="fix">
      <name>20131018</name>
      <ignore test="fix"/>
    </persons>
  </record>
</root>

Transparent

Der Knoten wird nicht mehr ausgegeben, aber die Felder im Knoten.

xml_no_template_transparent.xml

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <record art="root" type="object">
    <name type="String">name</name>
    <givenName type="String">given</givenName>
    <items type="array">
      <arrayItem type="object">
        <item type="String">abc</item>
        <itemType type="String">ALL</itemType>
      </arrayItem>
      <arrayItem type="object">
        <item type="String">cde</item>
        <itemType type="String">ALL</itemType>
      </arrayItem>
    </items>
    <persons test="fix">
      <name>20131018</name>
      <ignore test="fix"/>
    </persons>
  </record>
</root>

Exkludieren

Der Knoten user#3, sowie seine dazugehörigen Feldwerte, werden nicht ausgegeben.

xml_no_template_exkludieren.xml

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <record art="root" type="map">
    <items type="array">
      <arrayItem type="object">
        <item type="String">abc</item>
        <itemType type="String">ALL</itemType>
      </arrayItem>
      <arrayItem type="object">
        <item type="String">cde</item>
        <itemType type="String">ALL</itemType>
      </arrayItem>
    </items>
    <persons test="fix">
      <name>20131018</name>
      <ignore test="fix"/>
    </persons>
  </record>
</root>