XMLNoTemplateUnit

Group

Integration Units

Class Name

com.ebd.hub.datawizard.iu.XMLNoTemplateUnit

Function

Creates an XML file from the destination tree, without using a template file.

Description


Introduction: Integration Units.


The XMLNoTemplateUnit creates an XML file from the destination tree, without using a template file, as the XMLTemplateParserUnit and the XMLMemSaveTemplateParserUnit do, so you should preferably use this Integration Unit here. The destination structure must be constructed according to some rules, though, that are mentioned below.

Parameter Description


Parameter Name

Allowed Values

Default Value

Description

Certificate-ID for signing



If this parameter is filled with a valid ID of a local certificate (i.e. private key available), the XML file will be signed. The ID can simply be copied from the detail view of a certificate (Serial number).

Force Carriage Return (\r -> \r\n)

true, false

false

\n stays \n, but a \r becomes \r\n and therefore #&xD\n; (only for data part).

Example: <Text1\r\nText2> becomes

&lt;Text1&#xD;

Text2&gt;

Insert this DOCTYPE declaration



The DOCTYPE declaration to be added after the generation of the XML file. The DOCTYPE cannot be part of the template since the underlying XML generator would abort the generation in that case. Note: If you want to use an XML header other than the default header <?xml version="1.0" encoding="UTF-8"?>, you can specify it here. If you do, also use parameter Without XML-Header=true to remove the default XML header.

Mem save swap threshold


1000

If Use mem save method = true the threshold is set here. It specifies the number of elements after which data is swapped to the file system.

Pretty format

true, false

true

true creates a formatting with indentations (2 spaces). With false there are no indentations. Note: If parameter Write xml in a single line is set to true , the setting here has no effect.

Remove given prefix from field or node name



Cuts off any custom-defined prefix. Note: This action is performed before the one described in the following parameter.

Replace D-_... and F_-... to _...


false

Replace field names D-_... and F-_... with _... (cuts off D- and F- from field name).

Root node name



The node of the destination structure that becomes the root node of the XML (mandatory).

Text mode (…)

normalize, preserve, trim, trim-full-white

trim-full-white

Configures the way, values are written into the XML file.

  • preserve - No changes will be made to the text. All whitespaces (leading, trailing, …) will remain in the XML file.

  • trim-full-white - Same as preserve with the exception that a text, containing only whitespaces, will be replaced by an empty text.

  • trim - All leading and trailing whitespaces of a text will be removed.

  • normalize - Same as trim with the addition, that 'inner' whitespaces are reduced to a single space (..1..2.. → 1.2, a dot represents a whitespace).

Use XML short form for empty fields

true, false

false

If true, use XML short form for empty fields (<element/> instead of <element></element>).

Use mem save method

true, false

true

If true, elements will be swapped to the file system if a certain threshold is reached. This is the preferred method for large volumes of data.

Use namespace Inheritance

true, false

false

If true, namespaces will be inherited.

With empty fields

true, false

false

If true, empty elements (_attr and _val empty) will be created in the XML file. Note: If this option is set to true, 'hidden values' (see the corresponding section in the explanations for the Empty Flag) are also written into the output file (e.g. default date values for unsuccessfully parsed values for source structure date fields).

Without XML-Header

true, false

false

If true, no XML header (e.g. <?xml version="1.0" encoding="UTF-8"?>) will be created.

Write mandatory empty fields

true, false

false

If true, elements for mandatory empty fields will be created in the XML file.

Write values containing white spaces only

true, false

false

If true, fields which only contain whitespaces will not be treated as 'empty'.

Write xml in a single line

true, false

false

If true, the entire XML will be written in a single line.

end of line


\n

Defines the line delimiter.

file encoding


UTF-8

The name of the character set to be written into the header of the XML file. Note: The encoding in the response route (phase 6) of the profile must be set to the same value to actually save the data with this character set. Otherwise parsing errors on the reading side will most likely occur (mandatory).

Control Elements in the Destination Tree for the XML Creation


There are several attributes in destination nodes, attributes in destination fields, and destination field names that can be used to control the creation of the XML file.

Attributes of destination nodes


  • XML Namespace: This attribute allows to assign an XML namespace to the element created from the node, e.g. soapenv. Additionally, the attribute allows defining this namespace, e.g. soapenv=http://schemas.xmlsoap.org/soap/envelope/. If no namespace is used, the value DEFAULT has to bet set.

  • XML/JSON handling: This attribute controls how a node is included in the XML document. The following settings are possible.

    • Normal: The node will be fully output.

    • Exclude: The node will be ignored.

    • Transparent: The node itself will not create an element, but its content will.

    • Array: (This value is not relevant for this function.)

    • Array Transparent: (This value is not relevant for this function.)

  • Maximum: If a mapping creates several records, a node is generated multiple times over these records. If the node has the value 1 for the node attribute Maximum, the XML element corresponding to the node is only generated once. The fields of the multiple existing nodes are all listed below each other in the XML element. If this behaviour is not desired, simply use value 99999 instead of 1. Here is a hinted example:

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

Attributes of destination fields


  • XML Namespace: This attribute allows to assign an XML namespace to the element created from the field, e.g. soapenv. Additionally, the attribute allows defining this namespace, e.g. soapenv=http://schemas.xmlsoap.org/soap/envelope/. If no namespace is used, the value DEFAULT has to bet set.

Reserved field names


You can create fields with a special functionality within a node by using certain reserved suffixes.

  • _val: A field with this suffix contains the value of the XML element.

  • _attr: Fields with this suffix can be used to add attributes to an XML element. As an example, id_attr would add the attribute id to the element.

  • _nsdef: (e.g. xsd_nsdef) This suffix defines an additional namespace in the XML element (XSD). The content of this field is the namespace itself, e.g. http://www.w3.org/2001/XMLSchema.

  • _name: Field to rename the XML element that is created out of the corresponding parent node. The name of the XML element 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.


Example destination structure:


images/download/thumbnails/36575000/XMLNoTemplate_1-version-1-modificationdate-1560826958000-api-v2.png


Fields xsd_nsdef, TYPE_attr, POSNO_val, and POS_name have fixed values http://www.w3.org/2001/XMLSchema, M, 1, and POSITION.


XML file created out of destination structure:


As you can see, the Integration Unit built XML element POSITION out of the node POS (because of fixed value POSITION of field POS_name).


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

Numerical suffix for unambiguity


In XML, elements with the same name may occur on different levels of the hierarchy of the XML document. To ensure the unambiguity of names of all nodes and fields in a profile, you have to append a numerical suffix if a previously used name occurs. The sequence of the suffix numbers is irrelevant.

Suffix in destination tree: #<number>

In reserved field names (see above), the numerical suffix has to be placed in front of the suffix for the reserved field name. Both will not appear in the names of the generated XML. Example: TYPE#15_attr

Example for Numerical Suffixes and Reserved Field Names


In an XML document, the element TYPE can occur on several hierarchy levels and, in addition to that, there can be an attribute TYPE assigned to other elements (not named TYPE).


<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>


A corresponding destination structure, for example, would be the following.


images/download/thumbnails/36575000/xml_no_template_unit_1-version-1-modificationdate-1560826958000-api-v2.png


The element ORDER has an attribute TYPE. It is represented by the node ORDER#14, with the field TYPE#15_attr. The suffix _attr is placed after the numerical suffix.

The element TYPE in node ADDR has an attribute quali and a value. It is represented by the node TYPE#17, the attribute field quali#18_attr, and the value field TYPE#17_val. The suffix _val in the value field is also placed after the node name and the numerical suffix.

There can be several elements TYPE, with attribute source and a value inside the element TYPEDEFINITIONS. That is represented by the node TYPE#22, with value field TYPE#22_val and the attribute field source#24_attr. Even if the attribute were missing, there could be several elements TYPE with various values within the node TYPEDEFINITIONS.

Example for the destination node setting XML handling


Suppose you have the following destination structure.


images/download/thumbnails/36575000/xml_no_template_unit_2-version-1-modificationdate-1560826958000-api-v2.png


The node root#1 is set in attribute Root node name. We will see the effects of several different settings for the XML handling attribute of the node user#3. The following XML files are the corresponding outputs to the given XML handling setting.

Normal

The node user#3 and all of its fields are output.


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


The node user#3 will not be output, but its fields.


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>

Exclude


The node user#3 and all of its fields are not output.


xml_no_template_exclude.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>