DOMToDoc functinality in IBM Sterling Integrator

You can move data from the Process Data area into a document in IBM Sterling B2B Integrator (ISBI) by using the DOMToDoc xPath function.
This function will execute an XPath query against the process data DOM and save the node into a workflow document.

This blog aims to clarify the usage of the DOMToDoc XPath function in ISBI and provide clear examples of its usage.

For the official ISBI Documentation about this function, please see links below:

XPath and Process Data in ISBI and DOMToDoc function in ISBI


DOMToDoc parameters:

DOMToDoc(xpath expression , document_name, standalone, root_name, encoding, systemURL, dtdName, publicURL)
Wrap each parameter with single quotes, except from the first, XPath expression.

XPath expression (Required): This is the xpath query to execute against the process data to identify the node you want
to place in your new document.

documentName (Optional): This is the name to be assigned to the new workflow document. The default value is 'Document'

standAlone (Optional): The default value is 'no'.

rootName (Optional): This is the name of the document element where the result from the xpath query will reside under.
This entire node will then be written to the workflow document.
If a name is not provided then the document element will be the root node returning from the xpath query.

encoding (Optional): This string value will be used to build the encoding section of the XML header and to specify
the encoding type of the workflow document. This parameter will default to UTF-8 if an encoding is not provided.

*The next set of parameters is used to rebuild the DOCTYPE element that was lost when the xpath query was executed.

systemURL (Optional): This is the value of the system URL.

dtdName (Optional): This is the value of the DTD name. If a value for this parameter is specified then the publicURL parameter will be ignored.

publicURL (Optional): This is the value of the public URL. If a value for this parameter is specified then the DtdName parameter will be ignored.


Example usages of DOMToDoc function:

Unless stated otherwise, the examples below will assume the usage of the following info in Process Data area:

<ProcessData>
<PartnerInfo>
<Partner>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Partner>
<DocType>ORDERS</DocType>
<OrderNumber>12345</OrderNumber>
</PartnerInfo>
</ProcessData>


---------------Move the full contents of ProcessData to a document---------------

This example will create a new document with the full contents of ProcessData, note that the ProcessData
element will not be included, only the contents of ProcessData.

Note as well that that I am not assigning a document name, so by default it will be called "Document".

<assign to="." from="DOMToDoc(/ProcessData)"></assign>

Contents of ProcessData:

<ProcessData>
<PartnerInfo>
<Partner>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Partner>
<DocType>ORDERS</DocType>
<OrderNumber>12345</OrderNumber>
</PartnerInfo>
<Document SCIObjectID="rhel65_templ:node1:14f6fb36f06:8998760"/>
</ProcessData>

Contents of the document generated:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<PartnerInfo>
<Partner>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Partner>
<DocType>ORDERS</DocType>
<OrderNumber>12345</OrderNumber>
</PartnerInfo>


---------------Move the full contents of ProcessData to a named document---------------

This example will create a new document with the full contents of ProcessData and use the documentName parameter to name the new document MyDoc.

<assign to="." from="DOMToDoc(/ProcessData,'MyDoc')"></assign>

Contents of ProcessData:

<ProcessData>
<PartnerInfo>
<Partner>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Partner>
<DocType>ORDERS</DocType>
<OrderNumber>12345</OrderNumber>
</PartnerInfo>
<MyDoc SCIObjectID="rhel65_templ:node1:14f6fb36f06:9121107"/>
</ProcessData>

Contents of the document generated:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<PartnerInfo>
<Partner>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Partner>
<DocType>ORDERS</DocType>
<OrderNumber>12345</OrderNumber>
</PartnerInfo>


---------------Move the full Contents of ProcessData to the PrimaryDocument---------------

This example will move the full contents of Process data to a new document and assign it as Primary Document.

<assign to="." from="DOMToDoc(/ProcessData,'PrimaryDocument')"></assign>

Contents of ProcessData:

<ProcessData>
<PartnerInfo>
<Partner>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Partner>
<DocType>ORDERS</DocType>
<OrderNumber>12345</OrderNumber>
</PartnerInfo>
<PrimaryDocument SCIObjectID="rhel65_templ:node1:14f6fb36f06:9151630"/>
</ProcessData>

Contents of the document generated:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<PartnerInfo>
<Partner>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Partner>
<DocType>ORDERS</DocType>
<OrderNumber>12345</OrderNumber>
</PartnerInfo>


---------------Move the contents of Partner node only to a new document----------------

In this example we will be moving the contents of the node "Partner" only in ProcessData and move it to a new document called
MyDoc; I also want that the root element in my new document to be called "Customer", so I use the rootName parameter to assign the new root element in my document.

<assign to="." from="DOMToDoc(/ProcessData/PartnerInfo/Partner,'MyDoc','','Customer')"></assign>

Contents of ProcessData:

<ProcessData>
<PartnerInfo>
<Partner>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Partner>
<DocType>ORDERS</DocType>
<OrderNumber>12345</OrderNumber>
</PartnerInfo>
<MyDoc SCIObjectID="rhel65_templ:node1:14f6fb36f06:9121107"/>
</ProcessData>

Contents of the document generated:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Customer>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Customer>

---------------Adjusting the XML preamble---------------

By default SI will use the XML preamble below for any new document created:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

There might be a need to adjust this preamble, so in this example we are going to set the encoding to "UTF-16", the standalone to "yes"
and specify a system URL.

<assign to="." from="DOMToDoc(/ProcessData/PartnerInfo/Partner,'MyDoc','yes','Customer','UTF-16','http://hostaname:5000/test')"></assign>

Contents of ProcessData:

<ProcessData>
<PartnerInfo>
<Partner>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Partner>
<DocType>ORDERS</DocType>
<OrderNumber>12345</OrderNumber>
</PartnerInfo>
<MyDoc SCIObjectID="rhel65_templ:node1:14f6fb36f06:9121107"/>
</ProcessData>

Contents of the document generated:

<?xml version="1.0" encoding="UTF-16" standalone="yes"?><!DOCTYPE Customer SYSTEM "http://hostaname:5000/test">
<Customer>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Customer>

---------------Retrieve a specific Value from ProcessData---------------

In this example, I just want to retrieve the value of elements "Name" and "Contact" in ProcessData and create a
new flat file document correctly formatted with that info.

First, you will need to create a node in ProcessData with the info required using the format you need,
for example you can use the assign below:

<assign to="MyFlatFile" from="concat('Customer Name: ',PartnerInfo/Partner/Name/text(),string('&#x0d;&#x0a;'),'Customer Contact: ',PartnerInfo/Partner/Contact/text())"></assign>

This will create a ProcessData node called MyFlatFile like below:

<ProcessData>
<PartnerInfo>
<Partner>
<Name>CompanyA</Name>
<Contact>PersonA</Contact>
</Partner>
<DocType>ORDERS</DocType>
<OrderNumber>12345</OrderNumber>
</PartnerInfo>
<MyFlatFile>Customer Name: CompanyA
Customer Contact: PersonA</MyFlatFile>
</ProcessData>

Then use the DOMToDoc to insert the MyFlatFile node value into a new document:

<assign to="." from="DOMToDoc(MyFlatFile/text(),'PrimaryDocument')"></assign>

This will create a new document with the following contents:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>Customer Name: CompanyA
Customer Contact: PersonA

You can then use the Document Keyword Replace service to remove the XML preamble from your flat file
so that your new document contents looks like:

Customer Name: CompanyA
Customer Contact: PersonA

See link below for a blog on the document keyword replace service usage that contains an example of how to remove an XML preamble:

Document keyword Replace Service

Note: An alternative to this would be to use the StringToDoc function instead of the DOMToDoc.
The function StringToDoc will achieve the same results but without inserting the XML preamble in your new document.

<assign to="." from="StringToDoc(MyFlatFile/text(),'PrimaryDocument')"></assign>

---------------Avoid Trimming of leading or trailing spaces---------------

Sometimes some of your ProcessData values might contain trailing or leading spaces, for example:

<ProcessData>
<param1>param1</param1>
<param2>param2 </param2>
<param3> param3</param3>
</ProcessData>

When using a regular DOMToDoc function to move the contents into a new document; the document will look like the following (note the missing spaces):

<ProcessData>
<param1>param1</param1>
<param2>param2</param2>
<param3>param3</param3>
</ProcessData>

To avoid this, you can set a property to change the behavior of DOMToDoc and keep the leading and trailing spaces,if required.
You need to change the parameter trimTextNodeOutput of the translator.properties and set it to false.

You can achieve that by adding the line below to the customer_overrides.properties of your system:

translator.trimTextNodeOutput=false

Note that you will need to restart the system for the change to take effect.