XML File Definitions

XML files differ from Flat data files because they contain information scattered within the file that relates to the file structure, interspersed with the actual data values. This format tends to make XML files larger in size, but can also make them easier to read.

For example, an order number in an XML file might appear as:

<OrderNumber>12345</OrderNumber>

XML also has the advantage of using what are known as Schema files.

These Schema files are separate from the XML data files, and describe the structure of the incoming XML data file, along with any validation rules that each data file must comply with. They are more difficult to read.

Schema files can be created via a simple text editor - either created from scratch, or by modifying an existing Schema so that it meets your current requirements.

The format of these Schema files determine how the incoming data is translated, and typically have a file name ending with .xsd, - whereas XML data files have an .xml file extension.

When working with XML files, Statelake will always require these Schema files, not only to define the structure of the file, but also for validation purposes when reading from, or writing to, an XML file.

The following examples show the content of a simple XSD Schema file, and also the content of the corresponding XML data file.

Simple XML Schema Definition (.XSD) For An Order

<?xml version="1.0"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="OrderHeader" type="OrderHeaderType"/>
<xs:complexType name="OrderHeaderType">
  <xs:sequence>
    <xs:element name="OrderNumber" type="xs:string"    minOccurs="1" maxOccurs="1" />
    <xs:element name="OrderDate"   type="xs:date"      minOccurs="1" maxOccurs="1" />
    <xs:element name="OrderLine"  type="OrderLineType" minOccurs="1" maxOccurs="unbounded" />
  </xs:sequence>
</xs:complexType>
<xs:complexType name="OrderLineType">
  <xs:sequence>
    <xs:element name="LineNumber"    type="xs:int"    minOccurs="1" maxOccurs="1" />
    <xs:element name="ProductCode"   type="xs:string" minOccurs="1" maxOccurs="1" />
    <xs:element name="OrderQuantity" type="xs:int"    minOccurs="1" maxOccurs="1" />
  </xs:sequence>
</xs:complexType>
</xs:schema>

Simple XML Data File (.XML) For The Same Order

<OrderHeader>
  <OrderNumber>12345</OrderNumber>
  <OrderDate>26-10-2011</OrderDate>
  <OrderLine>
    <LineNumber>1</LineNumber>
    <ProductCode>ABC</ProductCode>
    <OrderQuantity>10</OrderQuantity>
  </OrderLine>
  <OrderLine>
    <LineNumber>2</LineNumber>
    <ProductCode>XYZ</ProductCode>
    <OrderQuantity>3</OrderQuantity>
  </OrderLine>
</OrderHeader>

When selecting the XML File type in your File Definition, a number of fields become available on the main screen that need populating.

An XML File type File Definition can be used to interact with any XML File that can be described using an XML Schema (XSD).

If you do not have an XSD schema file available for the XML you wish to process, you can infer one from an instance of the XML file.

Type Specific Fields

Field Name	Description
XSD Schema	Select the XSD Schema file that defines the structure of the XML you are processing. This must exist before the definition can be designed. Either click the 3-dot ellipse to navigate to the directory where the schema file is located, or enter the appropriate path name if known. If the <DefaultDir> tag is used in this XSD Schema field, be aware that it has its own unique interpretation in the XML Definition. It is advised that you enter the full path if known, or use the ellipses to identify the path and Schema file.
Resolve imported/included schemas	Select to allow the inclusion of imported or included schemas. The default is that this box is ticked.
Schema Root Node	Specify the element that is to be considered the root element. This only applies if the system detects multiple root node options in the XSD Schema.
Target NS Prefix	Enter the prefix to use for the target namespace when creating XML Files.
Schema Location	Enter the location of the schema that will become the schema Location attribute when creating XML Files. This should normally be left blank.
Include "XMLSchema-instance (XSI)" namespace	Include the XSI namespace when creating XML files.
Add namespaces as needed	Add namespaces only as they are used when creating XML Files. Otherwise namespaces are specified as attributes of the root node.
Include "XMLSchema (XSD)" namespace	Include the XSD namespace when creating XML Files.
Show schema annotations in design view	Show any annotation (documentation) information from the XSD Schema when working in the Designer.
Include XML Prolog	Include the XML prolog when creating XML Files.
Write out files using UTF-16 encoding	Create XML files using UTF-16 encoding.
Use xsi:nil for null fields	This option will result in xsi:nil being written to elements that have null values from the mapping. Otherwise, fields with null values will be excluded from the output.
Output XML in readable format	Create XML files that are nicely formatted when viewed in a text editor. Not recommended as this is slow, and formatting is normally applied by the application reading the file.
Force namespace prefix on attributes	Where an attribute has been defined with a namespace, setting this tick box will force the namespace to be included in the XML payloads.
Validate XML document against Schema	Validate any read or written XML files against the XSD Schema. This is recommended.
Allow DTD references in XML instance	Allow XML instances that are read into the File Definition to have DTD references. This is disabled by default due to security concerns.
Ignore XML validation errors	By default this is unticked. Tick to transfer control from the Action manager to allow imperfect XML payloads in or out. In some circumstances you may be able to use Statelake scripting to handle any differences.
XSLT Transforms Before reading	Select an XSLT (Transform file) to be applied to the XML payload before it is processed by the definition.
After writing	Select an XSLT (Transform file) to be applied to the XML payload after it has been processed by the definition.

Buttons

Button Name	Description
Create Blank XML File	Click to create an empty XML File. The XSD Schema field must hold the name of a valid schema file.