Group	Integration Units
Class name	com.ebd.hub.datawizard.iu.XMLTemplateParserUnit
Function	Creates an XML file from the destination tree using a template file.

Description

Important note: Please use the XMLNoTemplateUnit for newly developed profiles.

Introduction: Integration Units.

The XMLTemplateParserUnit creates an XML file from the destination tree using a template file.

Parameter Description

Parameter Name	Allowed Values	Default Value	Description
Insert this DOCTYPE declaration			The DOCTYPE declaration to be added after the generation of the XML. The DOCTYPE cannot be part of the template since the underlying XML generator would abort the generation in that case.
Replace orig. string by			Text to replace the text specified in parameter Search for orig. string after the creation of the XML file.
Search for orig. string			Text to be replaced by the text specified in parameter Replace orig. string by after the creation of the XML file.
Text mode (…)	normalize, preserve, trim, trim-full-white	trim	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).
Write xml in a single line	true, false	false	If true, the entire XML will be written in a single line.
expand empty nodes	true, false	false	true if empty values should be written as <tag></tag>. false if empty values should be written as <tag/>.
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).
template-file			The name of the template file to be used. See following section.
with empty fields	true, false	false	If true, empty fields will remain in the XML file.

Creation of an XML Template File

Suppose the following destination structure is given.

images/download/attachments/36575870/XMLTemplateParser-version-1-modificationdate-1561703902000-api-v2.png

Every order has exactly one order header and any number of order positions, contain the position itself and any number of position texts. Every run can create an order list with one, or several orders.

A template file can be created in a regular text editor, as long as certain rules are met, to make sure the unit is able to correctly fill the template with data. Usually, the template can be created automatically from the destination structure. In more complicated cases it might be necessary to manually adjust it afterwards.

To automatically create the template file, simply select Create XML template for IU in the destination structur menu.

Note: After every modification of the destination structure, the XML template file has to be either generated again or modified manually. For our example destination structure, the automatically generated template file would look as follows.

template.xml

<?xml version="1.0" encoding="UTF-8"?>
<DataWizardDummyRoot>
<!--This root element is used to ensure a valid XML file.
Valid means in this context: The file has one single root element.
Remove the dummy root element after you made sure that the generated data XML file will also have only one single root element.
That means, the top element of the XML tree will not be repeated while filling the template with data.-->
  <DataWizardSection node="Order">
    <Order>
      <DataWizardSection node="OrderHeader">
        <OrderHeader>
          <OrderNo>@OrderNo@</OrderNo>
          <CustomerNo>@CustomerNo@</CustomerNo>
        </OrderHeader>
      </DataWizardSection>
      <DataWizardSection node="OrderPosition">
        <OrderPosition>
          <DataWizardSection node="Position">
            <Position>
              <PosNo>@PosNo@</PosNo>
              <ArticleNo>@ArticleNo@</ArticleNo>
              <Quantity>@Quantity@</Quantity>
              <DataWizardSection node="PosText">
                <PosText>
                  <PosTextNo>@PosTextNo@</PosTextNo>
                  <Text>@Text@</Text>
                </PosText>
              </DataWizardSection>
            </Position>
          </DataWizardSection>
        </OrderPosition>
      </DataWizardSection>
    </Order>
  </DataWizardSection>
</DataWizardDummyRoot>

Explanation of the Template

Root Element

Every XML document must have a root that completely encloses the content. In our example, that is the automatically created tag <DataWizardDummyRoot>, which we will manually modify to <OrderList>.

Note: The XML declaration in the created XML file is not taken from the XML template.

DataWizardSection Tags

Every node of the destination structure has to be assigned to a DataWizardSection in the template file, using the same hierarchy. For each occurrence of a node, everything contained in the corresponding DataWizardSection is output once. So for each node Order in our example, the content of the corresponding tag <DataWizardSection node='Order'></DataWizardSection> is output once. The attribute node is used to assign a DataWizardSection to a node. Inside this DataWizardSection, the same mechanism is used for the nodes OrderHeader and OrderPosition, and so on. In the end, the whole destination structure is mapped into the XML template file with the use of the DataWizardSection tags.

Data Fields

The content of destination fields can either be used to fill XML elements or attributes. One example in the XML template is the line <PosNo>@PosNo@</PosNo>. The character @ surrounds the name of the field.

Usage of Variables

Outside of DataWizardSections, particularly in the root element, variables in the notation @VAR_NAME@ (the variable name has to start with _VAR in either uppercase, or lowercase, and it has to be defined in the profile) can be used to fill XML elements or attributes. It is always the last value of the variable at the end of phase 3 that is used. If the profile's extended settings (phase 2) Call response for each record and Includes call of IU are active, the last value of the variable in the respective record is used.

Resulting XML File of the Example

With some simple test data and the (slightly modified) XML template above, the destination structure of the example generated the following XML file.

order_list.xml

<?xml version="1.0" encoding="UTF-8"?>
<OrderList>
    <Order>
        <OrderHeader>
          <OrderNo>0815</OrderNo>
          <CustomerNo>11223344</CustomerNo>
        </OrderHeader>
        <OrderPosition>
            <Position>
              <PosNo>1</PosNo>
              <ArticleNo>4711</ArticleNo>
              <Quantity>10</Quantity>
            </Position>
        </OrderPosition>	
		 <OrderPosition>
            <Position>
              <PosNo>2</PosNo>
              <ArticleNo>4712</ArticleNo>
              <Quantity>7</Quantity>
            </Position>
        </OrderPosition>		
		<OrderPosition>
            <Position>
              <PosNo>3</PosNo>
              <ArticleNo>4713</ArticleNo>
              <Quantity>15</Quantity>
            </Position>
            <PosText>
              <PosNoText>1</PosNoText>
              <Text>just any text</Text>
            </PosText>
            <PosText>
              <PosNoText>2</PosNoText>
              <Text>and another text</Text>
            </PosText>
        </OrderPosition>
    </Order>
</OrderList>