XML Writer

The XML Writer transform writes a dataset to an XML file.

The XML Writer uses the same XPath expression technique as the XML Reader to generate an XML document.

Therefore, it is necessary to be familiar with XPath and XML Document structure before setting up an XML Writer transform. 

Two good starting places for learning XPath are:

Transform > File Layout

The file layout tab is where the target, encoding, file name and other details are configured.

Transform Id

The unique user-defined name for the transform.

Target

The controller type is defined here. This is the destination to where the XML file will be written, which can be File or Http.
See Input/Output Controllers (IO Controller) for more information.

Controller Options

This is the expandable options section beneath the Target drop-down. These options change according to the data destination selected.

See Input/Output Controllers (IO Controller) for more information.

Template document

Use if any standardised format is required for the final document.

For example, currency labels on sales price.

Create File When No Data

When set to true will create a file irrespective of whether there is data available.

Generate File Per Transaction

When a transaction Id is selected here, a file will be generated for each instance of that transaction, e.g. if an invoice transaction is selected, a file will be created for every invoice generated.

When the field is left blank a single file containing the whole dataset will be created.

When this field is in use, it is important to input a field reference(s) in the File Name field to create unique file names.

Omit XML Header

When selected will omit the XML declaration.

Namespace

XML namespaces are a unique identifier that can be associated with a set of XML elements and attributes.

Namespaces have hierarchical behaviour. Where a namespace is declared at the top level, it can be applied to each level underneath.

Each namespace control allows the user to specify which namespace to use at different levels within the document.

Namespaces used within the source document(s) are maintained using the Add, Edit, Delete controls.

Namespaces follow the format:

xmlns:<prefix>="<uri>"

Example

xmlns:xhtml="http://www.w3.org/1999/xhtml"

Or to declare a namespace with no prefix use:

xmlns="http://www.w3.org/1999/xhtml"

Building the XML Writer Transform

XML is by nature a nested data format. This means that the data is intrinsically structured with parent-child relationships already within it. As a result, it is necessary to specify the parents and any children through the Transaction XPath in this setup. Otherwise, the IMan dataset could be exported with far more, or far less, relationships than required.

The example below is an output data file from a purchasing system containing order details:

As seen here, the data is very much a structured format. The top parent is the initial XPath: OrderConfirmation, while its child is Orders. The child of Orders is OrderDetails, and within OrderDetails are the items. This structure is built up with the transaction XPaths, and is absolutely vital for exporting this data correctly.

Transform > Field Mapping

Initial XPath

The Entry Point XPath expression. Only simple XPath statements in the form of paths separated by forward slashes are allowed in the statement:

path/subpath/subsubpath

Namespace

The namespace in which to create the node(s).

Current Transaction Id

The Transaction Type being edited.

Transaction XPath

The XPath expression for the selected Transaction Type. See Attribute Paths.

Namespace

The namespace for the selected Transaction Type.

Transform > Field Mapping > Edit Field Mapping

Field Name

The field name within IMan.

Export Field

When selected, includes the field in the generated file.

Is Relative XPath

When selected, the XPath and Attribute expressions are appended to the Record XPath value.

When unselected, the expression is an absolute path.

XPath

If the 'Is Relative XPath' box is selected, the XPath expression specified here is appended to the Transaction Type XPath.

When unselected, the XPath expression field is an absolute path. This allows fields that are outside of the hierarchical relationship to be inserted.

Attribute

The name of the attribute to which the value of the field is set.

The name specified here is used with the XPath field to create a combined XPath expression.

This field is disregarded when no value is specified. That is, when this field is left blank, the attribute is automatically set as the inner name of the XPath expression.

Namespace

The namespace for the field.

Enclose Value in CDATA

When selected the value of the field will be enclosed in an XML CDATA expression.

Example

A field with the value “Tree Lights & Assorted Decorations” would typically be represented in Xml as:

“Tree Lights &amp; Assorted Decorations”

In a CDATA section the value is represented as:

<![CDATA[Tree Lights & Assorted Decorations]]>

Xml Writer > Audit

Action On Transform Error

Abort

If an error occurs the transform will stop.

Reject Record and Continue

If the Commit Transaction is not set (i.e. it is empty) the transform will stop.

If an error occurs and the Commit Transaction is set (i.e. it is not empty) the following actions are taken:

  1. The next transaction in the IMan dataset will be attempted if transaction type on which the error occurred is equal to or lower than the value specified on the Commit Transaction drop down.
  2. The transform will stop if transaction type on which the error occurred is above the value specified on the Commit Transaction drop down.

Supported Counters

  • PROCESSED
    • Incremented for each record processed.
  • INSERTED
    • Incremented for each record inserted.