XML Output2

Overview

The XML Output2 tool reads a relationally-linked set of records from multiple inputs, and writes XML-formatted documents as one or more fields or files. Each input record type has an ID field and (except for the root record type) a parent ID field. The tool links together records at every level in the hierarchy by joining the ID fields of parent records to the “parent ID” field of child records, producing an XML document for each input “root” record. Thus, the input records must meet the following requirements:

Each ID is unique
Each parent ID refers to a valid parent record

As a side-effect of these joins, the output documents are ordered by root ID.

XML Output2 configuration parameters

The XML Output2 tool has two sets of configuration parameters in addition to the standard execution options.

Configuration

Parameter	Description
Output to	The target of the data: File: write to the specified data file. This is the default. Field: write to the field on the input connection, treating the stream of binary data as wildcarded files.
Output file	If Output to is File, the output file name.
Open file time	If Output to is File, specifies when the output file will be opened: Default Uses the site/execution server setting When project is started When first record is read When last record is read
Write empty file if no records are read	If Output to is File, write an output file even when no records are read. This is unavailable if Open file time is When project is started.
Output field	If Output to is Field, the field to which the data will be written.
Include input fields	If Input from is Field, optionally passes through the "extra" input fields to the root record. This can be useful in certain kinds of processing where it is desirable to carry through identifying information that is not represented in the XML documents.
Use repository schema	If selected, configure the field layout using the specified Schema instead of configuring fields directly.
Schema	If Use repository schema is selected, a schema must be specified.
Record	Record specification defining the input of the tool. This is difficult to configure manually. See Configuring the XMLOutput2 tool.
Path	Sequence of XML tags separated by `/` defining the nested tag where data for the current level starts. It will be prepended to all XML paths in the `FIELDS` list that do not start with `/`. See About XML paths.
Replication factor	Number of copies of each block that will be stored (on different nodes) in the distributed file system. The default is 1.
Block size (MB)	The minimum size of a file division. The default is 128 MB.

Options

Parameter	Description
Unmapped element treatment	Specifies how to handle fields that are mapped in the Record section, but do not exist on the input connector at configuration time. (This can occur in macros, for example.) Choose: Use template: to obtain the value from the template (if defined) Error: to generate a configuration error Null: to output the field with an empty value Omit: to skip the field on output (no element or attribute is generated)
Missing field treatment	Specifies how missing fields are handled. Choose: Error: to generate a configuration error Null: to output the field with an empty value Omit: to skip the field on output (no element or attribute is generated)
Omit empty attributes	If selected, suppresses blank attributes.
Omit empty elements	If selected, suppresses blank elements.
Set NIL attributes	If selected, empty elements have the attribute `xsi:nil="true"` added. This is used in some formats such as data files targeted at Crystal Reports.
Readability	If selected, formats XML output with newlines and spaces are added to make readable indentation.
Namespace maps	Optionally, you can define mapping between Prefix and URI values.

Configure the XML Output2 tool

The procedure for configuring an XML Output2 tool depends on the data target.

If the data target is...	Do this
A file or files	Configure the XML Output2 tool to write files
A field or datastream	Configure the XML Output2 tool to write fields

...to write files

To configure the XML Output2 tool to write files:

Select the XML Output2 tool.
Go to the Configuration tab on the Properties pane.
Select Output to and choose File, and then specify the output file and format.

If you have...	Do this
An XML schema for this file already defined in the repository.	Specify the name of the output file. Select Use repository schema, and select the schema from the drop-down list.
No predefined repository schema.	Select the Analyze tab and enter formatted XML with the schema you want to use on output, then select Analyze and analyze the data. This parses the XML sample and extracts an array of output specifications.

Optionally, specify Open file time.

Option	Description
Default	Use the site/execution server setting. If you select this, you can optionally select Write empty file if no records are read. A warning will be issued if the tool setting conflicts with the site/execution server setting.
When project is started	Open output file when the project is run.
When the first record is read	Open output file when the first record is read. If you select this, you can optionally select Write empty file if no records are read.
After the last record is read	Output records are cached and not written to the output file until the tool receives the final record. If you select this, you can optionally select Write empty file if no records are read.

Select Commit to display the input connector(s).
Select each cell in the Record column, and examine the Fields grid to verify that the schema is correct and the data is accurately described. See About XML paths for details.
Select the Options tab to tune the XML output format.

Option	Description
Unmapped element treatment	Specifies how to handle fields that are mapped in the Record section, but do not exist on the input connector at configuration time. Options are: Use template: (default) obtain the value from the sample you entered on the Analyze tab. Error: generate a configuration error. Null: output the field with an empty value. Omit: skip the field on output (no element or attribute is generated).
Missing field treatment	Specifies how missing fields are handled. Options are: Use template: obtain the value from the sample you entered on the Analyze tab. Error: (default) generate a configuration error. Null: output the field with an empty value. Omit: skip the field on output (no element or attribute is generated).
Omit empty attributes	If selected, suppresses blank attributes.
Omit empty elements	If selected, suppresses blank elements.
Set NIL attributes	If selected, adds the attribute `xsi:nil="true"` to empty elements.
Readability	Specifies how the XML output is formatted.
Namespace maps	Optionally, you can define mapping between Prefix and URI values.

Optionally, go to the Execution tab and Enable trigger output, configure reporting options, or set Web service options.

...to write fields

To configure the XML Output2 tool to write fields:

Select the XML Output2 tool.
Go to the Configuration tab on the Properties pane.
Select Output to and choose Field.
Enter an Output field name.
Define the output format.

If you have...	Do this
An XML schema for this file already defined in the repository.	Select Use repository schema, and select the schema from the drop-down list.
No schema defined for this file.	Select the Analyze tab and enter formatted XML with the schema you want to use on output, then select Analyze and analyze the data. This parses the XML sample and extracts an array of output specifications.

Select Commit to display the input connector(s).
Select each cell in the Record column, and examine the fields grid below to verify that the schema is correct and the data is accurately described. See About XML paths for details.
Select the Options tab to tune the XML output format.

Option	Meaning
Unmapped element treatment	Specifies how to handle fields that are mapped in the Record section, but do not exist on the input connector at configuration time. Options are: Error: (default) generate a configuration error. Null: output the field with an empty value. Omit: skip the field on output (no element or attribute is generated). Use template: obtain the value from the sample you entered on the Analyze tab.
Missing field treatment	Specifies how missing fields are handled. Options are: Error: (default) generate a configuration error. Null: output the field with an empty value. Omit: skip the field on output (no element or attribute is generated). Use template: obtain the value from the sample you entered on the Analyze tab.
Omit empty attributes	If selected, suppresses blank attributes.
Omit empty elements	If selected, suppresses blank elements.
Set NIL attributes	If selected, adds the attribute xsi:nil="true" to empty elements.
Readability	Specifies how the XML output is formatted.
Namespace maps	Optionally, you can define mapping between Prefix and URI values.

If you specified the Use template option in the previous step, select the Analyze tab and enter an XML example of the output document format which contains default values for the unmapped or missing elements.
Optionally, go to the Execution tab and Enable trigger output, configure reporting options, or set Web service options.