Document XPath Replace Service

The Document XPath Replace service enables you to replace the text of a text node in an XML document by specifying an XPath expression.

The following table provides an overview of the Document XPath Replace service:

System name DocXPathReplace Service
Graphical Process Modeler (GPM) categories All Services, System, Internet B2B > Transora
Description The Document XPath Replace service performs text replacements in the document using XPath expressions.
Usage example Can be used to dynamically replace static text node identifiers with run-time configurable identifiers.
Preconfigured? An instance of this service is created upon installation. There are no instance configuration variables, but you must configure the workflow variables for the service in the GPM when you are creating a business process.
Requires third-party files? No
Platform availability All supported platforms
Related services None
Application requirements No
Initiates business processes? No
Invocation Runs as part of a business process.
Business process context considerations By default, any DOCTYPE tag found in the document is removed. If you want to retain the DOCTYPE tag, see How the Document XPath Replace Service Works.
Returned status values
Returned status values:
  • Success – Completed successfully.
  • Error – Errors were encountered during text replacement. Check advanced status, status reports, or systems logs.
Restrictions Must be a well-formed XML document that can be parsed.

How the Document XPath Replace Service Works

The Document XPath Replace service parses a document into a DOM (Document Object Model) so that the specified XPath expression can be evaluated and the resulting node(s) replaced with the specified value(s). By default, the Document XPath Replace service will use the current primary document unless the documentKey parameter is specified to point to a different document. Also by default, and to maintain backward compatibility, the Document XPath Replace service removes any DOCTYPE tag found in the document.

If you need to retain the DOCTYPE tag, there are two ways to do it.
  1. The recommended way is to set the noValidate parameter to true in the BPML. Using this option simply turns off all validation except for "well formed" validation and has the additional benefit of being able to utilize document streaming.
  2. The other option is to set the keepDocType parameter to true in the BPML. Using this option will still remove the DOCTYPE tag before parsing, but will re-add it before returning the updated document.

Starting with Sterling B2B Integrator version 4.0, the Document XPath Replace service also has the ability to perform multiple (batch) replacements with just one call to the adapter instead of separate individual calls.

Implementing the Document XPath Replace Service

To implement the Document XPath Replace service, simply add the existing instance to your business process using the GPM and configure the workflow parameters appropriately.

Configuring the Document XPath Replace Service

To configure the Document XPath Replace service, you must specify the following field settings (workflow parameters) in the GPM:

Field Description
Config Name of the service configuration. Required.
debug Turns on debugging for this workflow which logs extra messages to the system log. Optional. Valid values are Yes (true) and No (false). Default is No (false).
documentKey Name of the document in the workflow context in which to replace text. Optional. If no document name is specified in this parameter, the primary document is used.
keepDocEncoding Allows you to maintain the original document encoding for your XML documents to your generated document. For example, if you use an XML document with an encoding attribute of <?xml version= ‘1.0' encoding= ‘UTF-16”?>, you can keep this encoding attribute value for your generated document by selecting Yes in the GPM for keepDocEncoding or by adding the following line if you are editing the BPML, <assign to=”keepDocEncoding”>true</assign>. After the Document XPath Replace service runs, the original header of <?xml version= ‘1.0' encoding= ‘UTF-16”?> will be the header for the generated document. If you do not provide this parameter, the document will be encoded using “UTF-8” as the default value and a header of <?xml version= ‘1.0'> will be given to the generated document. Valid values are Yes (true) and No (false). Optional.
keepDocType Maintains the DOCTYPE tag by stripping the tag before performing any XPath replacements and then re-adding it back to the document before returning. Large file support cannot be utilized with this parameter. Optional. Valid values are Yes (true) and No (false). Default is No (false).
noValidate Disables any parser validation to keep from removing any DOCTYPE tags. This field overrides any use of the 'keepDocType' parameter. Using this field has the additional benefit of using document streaming. Optional. Valid values are Yes (true) and No (false). Default is No (false).
prefix Prefix used with a unique identifier as the replacement text. If performing more than one replacement (batch), this field must be sequentially numbered to match up with the corresponding textNodeXPath field. Optional, but either prefix or replacmentText must be specified.
replacementText Text to replace in the document. If performing more than one replacement (batch), this field must be sequentially numbered to match up with the corresponding textNodeXPath field. Optional, but either prefix or replacmentText must be specified.
replaceMultiple Whether multiple occurrences of the XPath statement should be replaced or just the first it finds. If performing more than one replacement (batch), this field must be sequentially numbered to match up with the corresponding textNodeXPath field. Optional. Valid values are Yes (true) and No (false). Default is No (false).
textNodeXPath XPath identifying the text node whose value needs to be replaced. Required.

Business Process Examples

This example performs a single text replacement.

<operation name="ReplaceText">
  <participant name="DocXPathReplace"/>
  <output message="outmsg">
    <assign to="." from="*"/>
    <assign to="textNodeXPath">//some/tag/text()</assign>
    <assign to="replacementText" from="'new text'"/>
  </output>
  <input message="inmsg">
    <assign to="." from="*"/>
  </input> 
</operation>

This example performs a single text replacement, but does it for multiple occurrences:

<operation name="ReplaceText">
  <participant name="DocXPathReplace"/>
  <output message="outmsg">
    <assign to="." from="*"></assign>
    <assign to="textNodeXPath" from="//some/tag/text()" />
    <assign to="replacementText" from="'new text'"/>
    <assign to="replaceMultiple">true</assign>
  </output>
  <input message="inmsg">
    <assign to="." from="*"></assign>
  </input> 
</operation>

This example performs a single text replacement, but does it for multiple occurrences and generates a unique identifier with the supplied prefix of CMD- as the replacement text.

<operation name="ReplaceText">
  <participant name="DocXPathReplace"/>
  <output message="outmsg">
    <assign to="." from="*"></assign>
    <assign to="textNodeXPath" from="//some/tag/text()" />
    <assign to="prefix">CMD-</assign>
    <assign to="replaceMultiple">true</assign>
  </output>
  <input message="inmsg">
    <assign to="." from="*"></assign>
  </input> 
</operation>

This example performs a single text replacement and one multiple occurrence text replacement:

<operation name="ReplaceText">
  <participant name="DocXPathReplace"/>
  <output message="outmsg">
    <assign to="." from="*"></assign>
    <assign to="textNodeXPath1" from="//some/tag/text()" />
    <assign to="replacementText1" from="'new text'"/>
    <assign to="textNodeXPath2" from="//some/trans/tag/text()" />
    <assign to="prefix2">TRANS-</assign>
    <assign to="replaceMultiple2">true</assign>
  </output>
  <input message="inmsg">
    <assign to="." from="*"></assign>
  </input> 
</operation>

This example performs two different text replacements, both with multiple occurrences and both generating unique identifiers with the corresponding prefix as the replacement text:

<operation name="ReplaceText">
  <participant name="DocXPathReplace"/>
  <output message="outmsg">
    <assign to="." from="*"></assign>
    <assign to="textNodeXPath1" from="//some/cmd/tag/text()" />
    <assign to="prefix1">CMD-</assign>
    <assign to="replaceMultiple1">true</assign>
    <assign to="textNodeXPath2" from="//some/trans/tag/text()" />
    <assign to="prefix2">TRANS-</assign>
    <assign to="replaceMultiple2">true</assign>
  </output>
  <input message="inmsg">
    <assign to="." from="*"></assign>
  </input> 
</operation>

This example performs eight different text replacements and uses the noValidate parameter, which keeps the parser from validating any schema or DTD and does not remove the DOCTYPE tag (if any):

<operation name="ReplaceText">
  <participant name="DocXPathReplace"/>
  <output message="outmsg">
    <assign to="." from="*"/>
    <assign to="noValidate">true</assign>
    <!-- Update the primary document with current year -->
    <assign to="textNodeXPath1">//CNTROLAREA/DATETIME/YEAR/text()</assign>
    <assign to="replacementText1" from="substring(formattedTime, '1', '4')"/>
    <!-- Update the primary document with current month -->
    <assign to="textNodeXPath2">//CNTROLAREA/DATETIME/MONTH/text()</assign>
    <assign to="replacementText2" from="substring(formattedTime, '5', '2')"/>
    <!-- Update the primary document with current day -->
    <assign to="textNodeXPath3">//CNTROLAREA/DATETIME/DAY/text()</assign>
    <assign to="replacementText3" from="substring(formattedTime, '7', '2')"/>
    <!-- Update the primary document with current hour -->
    <assign to="textNodeXPath4">//CNTROLAREA/DATETIME/HOUR/text()</assign>
    <assign to="replacementText4" from="substring(formattedTime, '9', '2')"/>
    <!-- Update the primary document with current minute -->
    <assign to="textNodeXPath5">//CNTROLAREA/DATETIME/MINUTE/text()</assign>
    <assign to="replacementText5" from="substring(formattedTime, '11', '2')"/>
    <!-- Update the primary document with current second -->
    <assign to="textNodeXPath6">//CNTROLAREA/DATETIME/SECOND/text()</assign>
    <assign to="replacementText6" from="substring(formattedTime, '13', '2')"/>
    <!-- Update the primary document with current subsecond -->
    <assign to="textNodeXPath7">//CNTROLAREA/DATETIME/SUBSECOND/text()</assign>
    <assign to="replacementText7" from="substring(formattedTime, '15', '4')"/>
    <!-- Update the primary document with current timezone -->
    <assign to="textNodeXPath8">//CNTROLAREA/DATETIME/TIMEZONE/text()</assign>
    <assign to="replacementText8" from="timezoneOffsetFromGMT/text()"/>
  </output>
  <input message="inmsg">
    <assign to="." from="*"/>
  </input> 
</operation>