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:
- Microsoft MSDN - http://msdn.microsoft.com/en-us/library/ms256086.aspx
- W3Schools - http://www.w3schools.com/xpath/
Transform > Options¶
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.
Important
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.
Rewrite Response Transaction¶
Allows you write the response back to the IMan dataset.
See Rewrite (HTTP) Write Response
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:
Example
Or to declare a namespace with no prefix use:
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:
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:
In a CDATA section the value is represented as:
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:
- 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.
- 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.