On this Page

Info

title	Breaking change for Pipelines using the XML Formatter Snap

After upgrading to 425patches10152, the snap might fail when you select Map input to first repeating element in XSD checkbox with an error Could not convert the document to an XML. In such cases, ensure that you provide a complete path from the root element for an object and map the input properly to the root element.

Table of Contents

maxLevel	2
exclude	Older Versions\|Additional Resources\|Related Links\|Related Information

Snap type:

Format

Description:

This Snap formats the incoming SnapLogic document objects into XML data format. The conversion from the internal JSON structure to XML follows the StAXON mapping convention. This mapping uses naming conventions to turn JSON object fields into XML nodes and attributes. For example, using the default Snap settings, the following two documents will be collected and written out as a single chunk of XML:

Code Block
{ "msg" : { "@attr1" : "0", "$" : "Hello, World!" } } { "msg" : "Goodbye, World!" }

The output of the formatter for these two documents will look something like the following. Note that the "msg" fields are turned into nodes in the XML structure, fields that start with "@" are turned into attributes on those nodes and "$" fields are turned into text nodes. The "DocumentRoot", "Document", and related fields are part of the wrappers added by the formatter when it collects multiple documents into a single file.

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<DocumentRoot>
  <Document>
    <Metadata>
      <asMap>
        <global>
          <doc_id>307db138-0ec4-11e4-a996-49c25019fb1e</doc_id>
        </global>
      </asMap>
      <id>307db138-0ec4-11e4-a996-49c25019fb1e</id>
    </Metadata>
    <Data>
      <msg attr1="0">Hello, World!</msg>
    </Data>
  </Document>
  <Document>
    <Metadata>
      <asMap>
        <global>
          <doc_id>307dff59-0ec4-11e4-a996-49c25019fb1e</doc_id>
        </global>
      </asMap>
      <id>307dff59-0ec4-11e4-a996-49c25019fb1e</id>
    </Metadata>
    <Data>
      <msg>Goodbye, World!</msg>
    </Data>
  </Document>
</DocumentRoot>

Note

If the value associated with a key is null (a valid JSON value), then an empty string will be placed as the text in between XML elements. For example,

Code Block
{ "msg" : { "@attr1": "0", "$": null } }

will be transformed into <msg attr1="0"/>.

Code Block
<?xml version="1.0" encoding="UTF-8"?> <msg attr1="0">Hello, World!</msg> <?xml version="1.0" encoding="UTF-8"?> <msg>Goodbye, World!</msg>

If you would like generate a file without the wrapper elements, you can clear the "Root Element" property and the Snap will produce a single binary document for every input document, like so:

The Snap can also validate documents against a provided schema to ensure that the output is well-formed. Any invalid documents will be written to the error output view.

The Snap by default produces XML that is not canonical. You can transform the XML output to canonical XML by selecting the Format as Canonical XML checkbox. The canonical form of an XML output from XML Formatter Snap is an XML representation that excludes the XML prolog and includes the start and end tag for all the XML elements. For more information about Canonical XML Version 1.0 specifications, see https://www.w3.org/TR/xml-c14n.

Prerequisites:

[None]

Support and limitations:

Works in Ultra Task Pipelines if Root Element is not selected.

Account:

Accounts are not used with this Snap.

Views:

Input	This Snap has exactly one document input view.
Output	This Snap has exactly one document output view.
Error	This Snap has at most one document error view and produces zero or more documents in the view.

Settings

Label

Required. The name for the Snap. You can modify this to be more specific, especially if you have more than one of the same Snap in your pipeline.

Outbound schema

XSD schema definition file URL for the outgoing data. The currently supported url protocols are SLDB, HDFS, S3.

Example: sldb:///foo/bar/customer.xsd

Default value: [None]

Validate output

Required. Specifies the incoming data to be validated against the provided XSD schema definition in Inbound Schema property.

Note
If you enter an Inbound schema, then you must select Validate XML and Match data types properties to derive the output as per the defined schema.

Example: False

Default value: False

Root element

The name of the XML element under which all the incoming documents will be added. If empty, no wrapping will be done and each document will be written out as a separate binary.

Example: DocumentRoot

Default value: DocumentRoot

Ignore empty stream

If selected, the Snap will do nothing when no document has been received in the input view. If not selected, the Snap will write an empty XML data with a header at the output view when no document has been received in the input view.

Default value: Not selected

Map input to first repeating element in XSD

If selected, the Snap

will ignore the

ignores the root element from the XSD file. See

the Example for Map input to first repeating element in XSD= True

the example below for more information.

Note

This is applicable only when the Snap has the repeated element such as Array in the XSD.

If this property is selected, the root element property is ignored and the <Metadata> ... </Metadata> element

will

does not appear at the output. If this property is not selected, the Snap

will write an XML data as mentioned in the description above, that is,

writes the XML data and the input document data is always wrapped in <Data> ... </Data>. If there is no root element, the user has to map the input to the root element.

Default value: Not selected

Format as Canonical XML

If selected, the Snap produces a canonical XML output.

The canonical form of an XML output (from XML Formatter Snap) is an XML representation that excludes the XML prolog and includes the start and end tag for all the XML elements. For more information about Canonical XML Version 1.0 specifications, see https://www.w3.org/TR/xml-c14n.

Default value: Not selected

Max schema levels

This configuration limits the number of schema levels provided by the outbound schema on the SnapLogic input view to a maximum of 10 levels. This configuration does not effect the validation capability. It serves to prevent outbound schemas from consuming too much memory and processing time.

Default value: 10

Multiexcerpt include macro

name	Snap Execution
page	Anaplan Read

Multiexcerpt include macro

name	Snap_Execution_Introduced
page	Anaplan Read

Schema language supported : W3C XML Schema 1.0

Troubleshooting

XML Formatter and XML Generator Output Differs for the Same XSD File Input

The XML Formatter and XML Generator Snaps work differently for an XSD file as the input document. To generate the same output from both the Snaps, append the following to the required schema in the Target path property of the preceding Mapper Snap:

XML Formatter: .$
XML Generator: .value

Examples

In the following example, the Map input to first repeating element in XSD field is set to True.

Assume the given XSD file is:

Code Block

<xsd:schema  xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:books" xmlns:bks="urn:books">
    <xsd:element name="books" type="bks:BooksForm"/>
    <xsd:complexType name="BooksForm">
        <xsd:sequence>
            <xsd:element name="book" type="bks:BookForm" minOccurs="0" maxOccurs="unbounded"/>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:complexType name="BookForm">
        <xsd:sequence>
            <xsd:element name="author" type="xsd:string" maxOccurs="unbounded"/>
            <xsd:element name="title" type="xsd:string"/>
            <xsd:element name="genre" type="xsd:string"/>
            <xsd:element name="price" type="xsd:float" />
            <xsd:element name="pub_date" type="xsd:date" />
            <xsd:element name="review" type="xsd:string"/>
        </xsd:sequence>
        <xsd:attribute name="id" type="xsd:string"/>
    </xsd:complexType>
</xsd:schema>

Assume two input documents are:

Code Block

[
  {
    "@id": "bk001",
    "title": "The First Book",
    "author": "John Smith",
    "genre": "Fiction",
    "price": "44.95",
    "pub_date": "2000-10-01",
    "review": "An amazing story of nothing." },
  {
    "@id": "bk002",
    "title": "The Poet's First Poem",
    "author": "Mary Parker",
    "genre": "Poem",
    "price": "24.95",
    "pub_date": "2000-10-01",
    "review": "Least poetic poems." }
]

The Snap extracts "books" as the root element name and "book" as the wrapper name from the XSD file.

The default XML output will be:

Code Block

<?xml version='1.0' encoding='UTF-8'?>
<books>
    <book id="bk001">
        <title>The First Book</title>
        <author>John Smith</author>
        <genre>Fiction</genre>
        <price>44.95</price>
        <pub_date>2000-10-01</pub_date>
        <review>An amazing story of nothing.</review>
    </book>
    <book id="bk002">
        <title>The Poet's First Poem</title>
        <author>Mary Parker</author>
        <genre>Poem</genre>
        <price>24.95</price>
        <pub_date>2000-10-01</pub_date>
        <review>Least poetic poems.</review>
    </book>
</books>

The canonical XML output will be:

Code Block

<books>
    <book id="bk001">
        <title>The First Book</title>
        <author>John Smith</author>
        <genre>Fiction</genre>
        <price>44.95</price>
        <pub_date>2000-10-01</pub_date>
        <review>An amazing story of nothing.</review>
    </book>
    <book id="bk002">
        <title>The Poet's First Poem</title>
        <author>Mary Parker</author>
        <genre>Poem</genre>
        <price>24.95</price>
        <pub_date>2000-10-01</pub_date>
        <review>Least poetic poems.</review>
    </book>
</books>

Insert excerpt

	Transform Snap Pack
	Transform Snap Pack
nopanel	true

Versions Compared

Old Version 21

New Version 22

Key

Settings

Troubleshooting

XML Formatter and XML Generator Output Differs for the Same XSD File Input

Examples

Page Comparison

Versions Compared

Old Version 21

New Version 22

Key

Settings

Troubleshooting

XML Formatter and XML Generator Output Differs for the Same XSD File Input

Examples