Versions Compared

Old Version 26

changes.mady.by.user Sandhya Sriram

Saved on

compared with

New Version Current

changes.mady.by.user Kalpana Malladi

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

In this article

Table of Contents
maxLevel2
excludeOlder Versions|Additional Resources|Related Links|Related Information

Overview

You can use this Snap to format the incoming document objects into XML data format. 

Note
titleBreaking 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 Could not convert the document to an XML error. 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.

Snap Type

This Snap is a FORMAT-type Snap that formats incoming data objects into XML data format.

Prerequisites

None.

Support for Ultra Pipelines

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

Limitations and Known Issues

None.

Snap Views

TypeFormatNumber of ViewsExamples of Upstream and Downstream SnapsDescription

Input 

Document



  • Min:1

  • Max:1

  • Mapper

  • Copy

JSON document.

Output

Binary


  • Min:1

  • Max:1

  • File Writer

  • XML Parser

XML document

Error

Error handling is a generic way to handle errors without losing data or failing the Snap execution. You can handle the errors that the Snap might encounter while running the Pipeline by choosing one of the following options from the When errors occur list under the Views tab. The available options are:

  • Stop Pipeline Execution: Stops the current pipeline execution when the Snap encounters an error.

  • Discard Error Data and Continue: Ignores the error, discards that record, and continues with the rest of the records.

  • Route Error Data to Error View: Routes the error data to an error view without stopping the Snap execution.

Learn more about Error handling in Pipelines.

Snap Settings

Info

  • Asterisk (*): Indicates a mandatory field.

  • Suggestion icon (Image Added): Indicates a list that is dynamically populated based on the configuration.

  • Expression icon (Image Added): Indicates whether the value is an expression (if enabled) or a static value (if disabled). Learn more about Using Expressions in SnapLogic.

  • Add icon (Image Added ): Indicates that you can add fields in the field set.

  • Remove icon (Image Added): Indicates that you can remove fields from the field set.


Field Name

Field Type

Description


Label*

Default Value: XML Formatter
Example: XML Formatter

StringSpecify 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
 

Default value: N/A 
Example: sldb:///foo/bar/customer.xsd


String/Expression

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

The Schema language supported is W3C XML Schema 1.0.

Output Character Set*


Default Value: UTF-8
Example: ISO860

String/Expression/Suggestion

Specify or select the character set encoding for the output.

Validate output
 

Default value: Deselected
Example: Selected

Checkbox

Select this checkbox to validate the output against the provided XSD schema definition in Outbound Schema field.


Note

If you enter an Outbound schema, then you must select Validate XML and Match data types checkboxes to get the output as per the defined schema. 


Root element


Default value: None
Example: DocumentRoot 

String

Specify the name of the XML element under which all the incoming documents are added. If left blank, no wrapping is done and each document is written out as a separate binary.



Ignore empty stream


Default value: Not selected 

Checkbox

Select this checkbox to enable the Snap to ignore when no document is received in the input view.
Deselect this checkbox to enable the Snap to write an empty XML data with a header at the output view when no document has been received in the input view.


Map input to first repeating element in XSD


Default value: Not selected

Checkbox

Select this checkbox if you want the Snap to ignore the root element from the XSD file. See 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 does not appear at the output. If this property is not selected, the Snap writes the XML data and the input document data is always wrapped in <Data>  ... </Data>. If there is no root element, map the input to the root element.



Format as Canonical XML


Default value: Not selected 

Checkbox

Select this checkbox to transform the XML output to canonical XML.

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. Learn more about Canonical XML Version 1.0 specifications: https://www.w3.org/TR/xml-c14n. 

Max schema levels


Default value: 10
Example: 20

String

Specify the max levels for schema to be processed by the Snap.

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. 

Snap Execution


Default Value: Validate & Execute
Example: Execute only

Dropdown list

Select one of the three modes in which the Snap executes. Available options are:

  • Validate & Execute: Performs limited execution of the Snap, and generates a data preview during Pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during Pipeline runtime.

  • Execute only: Performs full execution of the Snap during Pipeline execution without generating preview data.

  • Disabled: Disables the Snap and all Snaps that are downstream from it.


Additional Information

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 processed 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 is as follows.

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 want to generate a file without the wrapper elements, you can remove the "Root Element" property and the Snap produces a single binary document for every input document. The Snap also validates documents against a provided schema to ensure that the output is well-formed. Any invalid documents will be written to the error output view. 

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 selected. 

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>


Suppose the following are the two input documents:

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 following is the default XML output:

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 following is the canonical XML output:

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
nopaneltrue

...