Software AG Products 10.7 | Integrating On-Premises and Cloud Applications | Integration Cloud | Built-In Services | Built-In Services | xmlNodeToDocument
 
xmlNodeToDocument
Converts an XML node to a document.
This service transforms each element and attribute in the XML node to an element in a Document. For example:
This service would convert this XML document...
<?xml version="1.0" ?>
<tns:AcctInfo>
xmlns:tns="http://localhost/DerivedAddress/schema.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<name>Midwest Extreme Sports</name>
<rep>Laura M. Sanchez</rep>
<acctNum type=platinum>G97041A</acctNum>
<phoneNum cc=011>216-741-7566</phoneNum>
<address country=USA>
<street1>10211 Brook Road</street1>
<city>Cleveland</city>
<state>OH</state>
<postalCode>22130</postalCode>
</address>
<address country=USA xsi:type="tns:DerivedAddress">
<street1>10211 Brook Road</street1>
<city>Cleveland</city>
<state>OH</state>
<postalCode>22130</postalCode>
<landMark>Besides Ohio River-Bank Square</landMark>
<telNo>001222555</telNo>
</address>
<serialNum>19970523A</serialNum>
<serialNum>20001106G</serialNum>
<serialNum>20010404K</serialNum>
</tns:AcctInfo>
To a document that looks like this...
Note that:
*The XML version attribute is converted to an element named @version.
*The resulting document is given the same name as the XML document's root element (AcctInfo in the example above) and is a child of the document variable that this service returns.
*Simple elements (such as <name> and <rep> in the example above) are converted to String elements.
*Complex elements (that is, elements with children, such as <address> in the example above) and simple elements that have attributes (such as <acctNum> and <phoneNum>) are converted to documents. Note that keys derived from attributes are prefixed with a "@" character to distinguish them from keys derived from elements. Also note that when a simple element has an attribute, its value is placed in an element named *body.
*Repeated elements (such as <serialNum>) can be collected into arrays using the makeArrays and/or arrays parameters. See makeArrays and arrays below for additional information about producing arrays.
*While creating a document, the xmlNodeToDocument service assigns a value of emptyString to the fields that are empty in the document.
Input Parameters
node
XML node that is to be converted to a document.
This parameter supports the following types of input:
*com.wm.lang.xml.Node
*org.w3c.dom.Node
attrPrefix
String Optional. Prefix that is to be used to designate keys containing attribute values. The default is "@". For example, if you set attrPrefix to ATT_ and node contained the following element:
<tx currency=dollars>
<acct>cash</acct>
<amt>120.00</amt>
</tx>
xmlNodeToDocument would convert the currency attribute as follows:
arrays[]
String List Optional. Names of elements that are to be generated as arrays, regardless of whether they appear multiple times in node. For example, if arrays contained the following values for the XML document shown in the example in the description for this service:
rep
address
xmlNodeToDocument would generate element rep as a String List and element address as a Document List.
Important:
If you include namespace prefixes in the element names that you specify in arrays, you must define the namespaces associated with those prefixes in nsDecls.
makeArrays
String Optional. Flag indicating whether you want xmlNodeToDocument to automatically create an array for every element that appears in node more than once. Set to:
*true to automatically create arrays for every element that appears more than once in node. This is the default.
*false to create arrays for only those elements specified in arrays.
collect
Document Optional. Elements that are to be placed into a new, named array (that is, a "collection"). Within collect, use key names to specify the names of the elements that are to be included in the collection. Then set the value of each key to specify the name of the collection in which you want that element placed. For example, if you wanted to place the <name> and <rep> elements in an array called originator, you would set collect as follows:
Key
Value
name
originator
rep
originator
If the set of elements in a collection are all simple elements, a String List is produced. However, if the set is made up of complex elements, or a combination of simple and complex elements, a Document List is produced. When this is the case, each member of the array will include a child element called *name that contains the name of the element from which that member was derived.
You may optionally include namespace prefixes in the element names that you specify in collect; however, if you do, you must define the namespaces associated with those prefixes in nsDecls.
Important:
You cannot include an element in more than one collection.
nsDecls
Document Optional. Namespace prefixes to use for the conversion. This parameter specifies the prefixes that will be used when namespace-qualified elements are converted to key names in the resulting Document. For example, if you want elements belonging to a particular namespace to have the prefix GSX in the resulting Document (for example, GSX:acctNum), you would associate the prefix GSX with that namespace in nsDecls. (This is important because incoming XML documents can use any prefix for a given namespace, but the key names expected by a target service will have a fixed prefix.)
Namespace prefixes in nsDecls also define the prefixes used by the arrays, documents, and collect parameters.
Each entry in nsDecls represents a namespace prefix/URI pair, where a key name represents a prefix and the value of the key specifies the namespace URI.
For example, to define the URIs associated with two prefixes called GSX and TxMon, you would set nsDecls as follows:
documents[]
String List Optional. Names of any simple elements that are to be generated as documents instead of Strings. The document produced for each element specified in documents[] will have the same name as the source element from which it is derived. It will contain a String element named *body that holds the element's value.
For example, if documents[] contained the Strings name and rep and the source document contained the following:
.
.
.
<name>Midwest Extreme Sports</name>
<rep>Laura M. Sanchez</rep>
.
.
.
xmlNodeToDocument would produce the following:
Note:
If you include namespace prefixes in the element names that you specify, you must define the namespaces associated with those prefixes in nsDecls.
mixedModel
String Optional. Flag specifying how mixed-content elements (elements containing both text values and child elements) are to be converted. The following is an example of a mixed-content element:
<comment>
This job is <status>pending</status>. Estimated
completion date is <edc>Feb 14, 2000</edc>.
</comment>
Set to:
*true to place top-level text in an element named *body. This setting would produce the following Document for the <comment> element shown above:
*false to omit top-level text and include only the child elements from mixed-content elements. This setting would produce the following Document for the <comment> element shown above:
preserveUndeclaredNS
String Optional. Flag indicating whether or not Integration Cloud keeps undeclared namespaces in the resulting document. An undeclared namespace is one that is not specified as part of the nsDecls input parameter.
Set to:
*True to preserve undeclared namespaces in the resulting document. For each namespace declaration in the XML document that is not specified in the nsDecls parameter, Integration Cloud adds the xmlns attribute as a String variable to the document. Integration Cloud gives the variable a name that begins with "@xmlns" and assigns the variable the namespace value specified in the XML document. Integration Cloud preserves the position of the undeclared namespace in the resulting document.
*False to ignore namespace declarations in the XML document that are not specified in the nsDecls parameter. This is the default.
preserveNSPositions
String Optional. Flag indicating whether or not Integration Cloud maintains the position of namespaces declared in the nsDecls parameter in the resulting document.
Set to:
*True to preserve the position of namespaces declared in nsDecls in the resulting document. For each namespace specified in the nsDecls parameter, Integration Cloud adds the xmlns attribute to the document (IData) as a String variable named "@xmlns:NSprefix" where "NSprefix" is the prefix name specified in nsDecls. Integration Cloud assigns the variable the namespace value specified in the XML document. This variable maintains the position of the xmlns attribute declaration within the XML document.
*False to not maintain the position of the namespace declarations specified in nsDecls in the resulting document. This is the default.
Output Parameters
document
Document Document representation of the nodes and attributes in node.
Examples
Following are examples of XML documents and the documents that xmlNodeToDocument would produce.
XML Document
Output from xmlNodeToDocument
<myDoc>
<e1>e1Value</e1>
</myDoc>
<?xml version="1.0" encoding="UTF-8"
standalone="no"?>
<myDoc>
<e1>e1Value</e1>
</myDoc>
<?xml version="1.0" encoding="UTF-8"
standalone="no"?>
<myDoc>
<e1 e1Attr="attrValue">e1Value</e1>
</myDoc>
<?xml version="1.0" encoding="UTF-8"
standalone="no"?>
<myDoc>
<e1>e1Value</e1>
<e2>e2Value</e2>
</myDoc>
<?xml version="1.0" encoding="UTF-8"
standalone="no"?>
<myDoc>
<e1>e1Value1</e1>
<e2>e2Value</e2>
<e1>e1Value2</e1>
</myDoc>
<?xml version="1.0"
encoding="UTF-8"?>
<myDoc>
<e1 e1Attr="attrValue1">e1Value1</e1>
<e2>e2Value</e2>
<e1 e1Attr="attrValue2">e1Value2</e1>
</myDoc>
Note:
This example assumes that makeArrays is set to true. Note that e1 was created as a document list, which holds both <e1> elements from the XML document.
<?xml version="1.0"
encoding="UTF-8"?>
<myDoc>
<e1 e1Attr="attrValue1">e1Value1</e1>
<e2>e2Value</e2>
<e1 e1Attr="attrValue2">e1Value2</e1>
</myDoc>
<?xml version="1.0"
encoding="UTF-8"?>
<myDoc>
<e1 e1Attr="attrValue1">e1Value1</e1>
<e2>e2Value</e2>
<e1 e1Attr="attrValue2">e1Value2</e1>
</myDoc>
<?xml version="1.0"
encoding="UTF-8"?>
<myDoc>
<e1 e1Attr="attrValue1">e1Value1</e1>
<e2>
<e3>e3Value</e3>
<e4 e4Attr="attrValue4"
e4Attrb="attrValue4b">e4Value
</e4>
</e2>
</myDoc>
<?xml version="1.0" encoding="UTF-8"
standalone="no"?>
<tns:AcctInfo>
xmlns:tns="http://localhost/Derived
Address/schema.xsd"
xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance" >
<myDoc> <e1>e1Value</e1>
</myDoc>
<myDoc xsi:type="tns:DerivedDoc">
<e1>e1Value</e1>
<e2>e1Value</e2>
</myDoc>
</tns:AcctInfo>