On this Page
Table of Contents | ||||
---|---|---|---|---|
|
Snap type: | Read | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description: | This Snap generates a new XML document for the next Snap in the pipeline. The Snap will pass-through the input data if an input view is provided. The output of the Snap will provide an XML attribute in the document which provides the serialized XML content as a string.
| |||||||||||||
Prerequisites: | [None] | |||||||||||||
Support and limitations: | Works in Ultra Task Pipelines. | |||||||||||||
Account: | Accounts are not used with this Snap. | |||||||||||||
Views: |
| |||||||||||||
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. | |||||||||||||
Inbound schema | XML schema definition of the incoming data. | |||||||||||||
Schema XPath | The path for the schema object in the provided schema file, which must be used for validating the XML data. This is required if the schema object is nested within a wrapper object or within an object further in the schema file. See example Validating XML Data Using the Schema XPath for more information on using the Schema XPath field. | |||||||||||||
XML root element | Root element for the XML generation. | |||||||||||||
Validate XML | Required. Appears when you specify an XSD schema definition in the Inbound schema field. Select this checkbox to validate the incoming data against the specified XSD schema definition.
Default Value: Deselected | |||||||||||||
Escape special characters | Select this checkbox to escape XML special characters in XML template variable values when you insert the values into the Apache Velocity template. For example, the Snap replaces < with &It;. The special characters that the Snap escapes are:
XML Generator normalizes all attributes to use double quotes for the delimiters, even if the source content uses single quotes. Therefore, if there are double quotes that appear inside the attributes, then they have to be escaped. Learn more about how special characters are handled in XML. Default value: Not selected
| |||||||||||||
Default value for substitution | This value will be used for substitution for the leaf elements which are not objects and/or not enclosed in an array. If nothing is specified and Use default value for substitution is selected, an empty string will be used for substitution. | |||||||||||||
Use default value for substitution | If you select this check box, the value provided for the Default value for substitution is used for substitution if the elements do not exist in the incoming documents. Otherwise, the elements for which the incoming documents do not have any values will be deleted from the XML. | |||||||||||||
Namespace Context | Namespace context for schema element. | |||||||||||||
Prefix | Prefix of schema element in the provided schema file. | |||||||||||||
Namespace URI | Namespace of schema element in the provided schema file. | |||||||||||||
Edit XML | Required. This property lets you edit the XML contents. The elements to be generated in the output must be specified in the XML template. If your output does not display the required elements, click Edit XML and specify the applicable elements in the Generate Template tab. You can use the Apache Velocity template to pass dynamic values from upstream Snaps.
| |||||||||||||
|
|
Handling Special Characters
The following are the basic rules when the special characters are to be escaped:
If the special characters are inside the element text, then they are not to be escaped.
If the special characters are inside the attribute values that are delimited by single or double quotes, then they are to be escaped.
If the special characters and the delimiter being used for that attribute are the same, then they are to be escaped.
The following table lists few examples on how to escape special characters:
He said "OK" | attributeName="He said "OK"" | The double quotes must be escaped. |
He said "OK" | attributeName='He said "OK"' | The double quotes need not be escaped as they are contained within a single quoted attribute. |
She said "You're right" | attributeName="She said "You're right"" | The ' (apostrophe) in You’re need not be escaped as it is contained within double quotes. |
She said "You're right" | attributeName='She said "You're right"' | The double quotes need not be escaped as they are contained within a single quoted attribute. However, you must escape the apostrophe in You’re. |
She said "You're right" | attributeName="She said "You're right"" | To escape all the data. |
Smith&Sons | attributeName="Smith&Sons" | The & must always be escaped within attribute data. |
a>b a<b | attributeName="a>b" attributeName="a<b" | It is good practice to escape > or < characters, though not mandatory if they used in an attribute. |
if (age < 5) if (age > 5) if (age > 3 && age < 8) | <MyElement>if (age < 5)</MyElement> <MyElement>if (age > 5)</MyElement> <MyElement>if (age > 3 && age < 8)</MyElement> | It is good practice to escape >, <, or & characters if they are used within an element though not mandatory. |
She said "You're right" | <MyElement>She said "You're right"</MyElement> | The single and double quotes need not be escaped if they are within an Element |
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
Expand | ||
---|---|---|
| ||
XML Generation via XSDThe first example depicts a simple pipeline to generate order data XML directly with the XML Generator Snap.
We provide the sample XSD as defined below:
We then suggest the XML root element, which returns {}shiporder. Now we could replace the variables with our own values to generate the XML on the output view or move on to the next example. |
Expand | ||
---|---|---|
| ||
Mapping to XML Generator via XSDLet us use a JSON Generator to provide the input order data, such as defined below:
We then map the data using the Mapper Snap which has access to the XSD of the downstream XML Generator Snap of the previous example (now with an added input view). Here we map the items to the item list on the target. Further we map the city, address, country and name to the shipTo object on the target and then finally we map the name against orderperson and orderId against @orderId on the target. The @ indicates we map against an XML attribute Let us see the output of the XML Snap. Here we see that each incoming order document was translated into an xml string. We include the original data from the input view, in case it is further needed downstream. |
Expand | ||
---|---|---|
| ||
Writing the Generated Content to FileSometimes one wants to write the generated XML to a file. For that use case we provide a DocumentToBinary Snap which can take the content and convert it to binary data object, which then can be written to a file, such as using a File Writer Snap.
Above we map XML to the content field of the DocumentToBinary Snap, and set the Encode or Decode option on the DocumentToBinary Snap to NONE.
|
Expand | ||
---|---|---|
| ||
POSTing the Generated ContentIn the last example we will be POSTing the generated content to some REST endpoint using the REST POST Snap.
The POST will be executed for every document on the input view. There are a total of two documents, hence we will execute two post requests. |
Expand | ||
---|---|---|
| ||
Validating XML Data Using the Schema XPath and Validate XML SettingsThis example demonstrates how to use the Schema XPath field to successfully validate XML data. Download the Sample Pipeline. In this Pipeline, custom XML data is provided using the Edit XML field in the XML Generator Snap, a snapshot of which is provided here. The Inbound schema, Schema XPath, and the schema Root element, are specified in the Snap settings. See the screenshot below. In addition, the Validate XML check box is selected to indicate that the XML data must be validated against the schema. The file specified as the inbound schema, In the above file, the root element of the schema is nested within the On validating the Pipeline, the Snap output appears as follows. Note the If the Note that if the Validate XML check box is deselected, the Snap does not validate the data against the schema, and an output with the missing field is generated without errors: Similarly, if the Schema XPath value is not provided, the Snap is unable to locate the root element and fails with the following error: This explains the scenarios in which you need to provide the schema XPath and how you can validate XML data using schema from within any XML or XSD file with the help of the Schema XPath and Validate XML properties. |
Expand | ||
---|---|---|
| ||
Custom XML Output Generation using Inbound Schema and Root ElementThis example illustrates the corrected behavior of the XML Generator Snap as of Patch transform8760, whereby the Snap does not ignore any custom XML data that is provided through its XML editor. Download the Sample Pipeline. Scenario 1: When used with upstream Snaps The sample Pipeline provided here generates XML for an Add operation. The XML output should contain two integer values: intA and intB.
In the Customized XML Snap, custom XML data is provided using the Edit XML field in the Snap Settings as follows:
The Generated XML Snap contains the XML that is generated through the Generate Template button in the XML editor: In this case, the values of Both Snaps are fed an input document that specifies Old behavior: Current behavior: The output of the Generated XML Snap is based on upstream data: Scenario 2: When used as a standalone Snap The sample Pipeline provided below generates XML for an Add operation. Custom XML is provided using the Edit XML field, as follows: Old behavior: Pipeline execution would result in a Current behavior: Pipeline execution is successful and custom XML output is generated: This example illustrates how you can generate custom XML output through the XML Generator Snap. |
Downloads
Multiexcerpt include macro | ||||
---|---|---|---|---|
|
Attachments | ||
---|---|---|
|
Insert excerpt | ||||||
---|---|---|---|---|---|---|
|