Using the XML Merge Component

The XML Merge Component is a transformation component used to merge input data into XML. Define the relationship of inputs in the Design Page, configure column properties in the Columns Page, and refine formatting in the Advanced Page.

Design Page

Define the relationship of the Inputs in the Design Page.

XML Merge Editor

To define relationships simply click and drag from a child field to a parent field. In the above example, there is a relationship from the Item.PurchaseOrderId field to PurchaseOrder.Id field. What this means when merging is PurchaseOrder nodes will contain Item nodes whose PurchaseOrderId field match the PurchaseOrder's Id field. If you need to remove a relationship on the design page, simply select the connecting arrow and press the 'Delete' key.

You cannot continue to the Columns Page until the relationship structure is valid. The most common cause for an invalid relationship is invalid root count. The root input is defined be an input who does not have a parent Input. There must be one and only one root input. To fix this, delete any unused inputs and adjust the relationships so that there is only one root.

Columns Page

Configure column/node specific merge settings.

XML Merge Editor - Columns Page

Check and uncheck nodes in the data grid to specify if they should be in the merged XML. A good use for this is to hide the parent Id field in the child. This field is required to merge but not in the XML because XML uses hierarchy to define relationships.

NOTE: Checking and unchecking nodes are recursive so you can check and uncheck an entire input of nodes at a time. That being said if you do not want an input to go into the XML simply disconnect the input altogether. This is better for performance and will make the design and Columns page easier to work with.


To configure node properties, select nodes in the data grid on the left to populate the property grid on the right. In the property grid you can adjust the following:

Is Attribute

This property can only be specified for column nodes and by default is set to False. When Is Attribute is set to True then the value for the node will be inside of an attribute in the parent node with the name of the value of the XML Name property.

Prefix

This property is a drop down list which contains all of the prefixes defined in the Namespaces data grid in the Advanced Page along with two special prefix properties: 

  • <<Inherit>> - The current node will use the same prefix used by its parent. If the current node is the root node, then no prefix is used.
  • <<None>> - The current node will use no prefix, even if its parent does.
XML Name

Specifies the name of the element or attribute of the current node.

Advanced Page

Configure XML and merge related settings here.

XML Merge Editor - Advanced Page

Encoding

A drop-down list to select the encoding of the XML document

Null Mode

This property specifies how to handle NULL values. There are three options:

  • Don't Show - This option will hide nodes whose values are NULL.
  • Empty String - This will convert NULL values to empty string.
  • xsi:nil - This option will add xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" to root of the XML and will add empty nodes with an attribute of xsi:nil set to "true" whose values are NULL.
Print Pretty

When true, the merged XML will contain line breaks and indents. When false, the merged XML will be a single line of text.

Hide Declaration

Specifies whether or not the merged XML should contain the XML Declaration line.

Is Standalone

An attribute in the XML Declaration.

Merge Mode

Specify how to merge the inputs into XML. There are three different Merge Modes:

  • Every Row - This creates an XML document for each record in the root Input. Notice when this option is selected, the columns of the root input are directed to the Default Output. Another thing to notice is the plural node for the root Input is removed.
  • Every Batch - This creates an XML document for every batch. The size of the batch is determined by the Batch Size property, and a batch item is equivalent to one record in the root input. In other words, a batch size of 10 will create XML documents that each contain 10 root input records.
  • Entire Buffer - This creates a single XML document.
Batch Size

Specifies how many root input records should be in each XML document. This option is only available if the Merge Mode is Every Batch.

Namespaces

Add and remove namespaces (by clicking the '+' and '-' buttons) and assign them prefixes to be used in the merged XML

Output & Error Handling

This page allows you to specify how errors should be handled when they happen along with the name of the output column that will contain the merged XML.

XML Merge Editor - Error Handling Page

Merged XML Column Name

The name of the output column that will contain the merged XML.

Error Handling has three options available. 

  1. Fail on error
  2. Redirect rows to error output
  3. Ignore error

When the Redirect rows to error output option is selected, rows that failed to be sent will be redirected to the 'Error Output' output of the Transformation Component. As indicated in the screenshot below, the blue output connection represents rows that were successfully sent, and the red 'Error Output' connection represents rows that were erroneous. The 'ErrorMessage' output column found in the 'Error Output' may contain the error message that was reported by the component.

XML Merge Editor - Error Output