Document Keyword Replace Service

The Document Keyword Replace service enables you to find and replace text within a document.

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

System name Document Keyword Replace Service
Graphical Process Modeler (GPM) category All Services
Description The Document Keyword Replace Service allows you to replace user-defined keywords in a document. This can be used to manipulate hexadecimal or string values in a document. A keyword can be replaced with either a replacement string or the contents of a document.
Preconfigured? No
Business usage Because of disparities between how different trading partners' enterprise systems process data, the format of the data that is exchanged between trading partners often needs to be manipulated before sending or after receiving or in some cases, on both sides of the transmission.
Usage example Assume that the VAN used by your trading partner expects each line of data to be terminated with a Carriage Return and Line Feed, and the data from your enterprise system is terminated by tilde (~) characters. You would use the DocKeywordReplace service to convert the tildes into Carriage Return / Line Feed characters, before transmitting the data to your trading partner.
Requires third-party files? No
Platform availability All supported Sterling B2B Integrator platforms
Related services None
Application requirements None
Initiates business processes? No
Invocation Runs as part of a business process.
Business process context considerations This service uses the primary document.
Returned status values
Returned status values:
  • Success – Document Keyword Replace service was successful.
  • Error – Document Keyword Replace service was unsuccessful.
Restrictions None

Implementing the Document Keyword Replace Service

To implement the Document Keyword Replace service, complete the following tasks:
  1. Create a Document Keyword Replace service configuration. See Creating a Service Configuration.
  2. Configure the Document Keyword Replace service. See Configuring the Document Keyword Replace Service.
  3. Use the Document Keyword Replace service in a business process.

Configuring the Document Keyword Replace Service

To configure the Document Keyword Replace service, use the following BPML parameters in your business process:

BPML Description
keyword<x> Keyword that the service should look for. Required. <x> refers to a sequential number starting with 1. This allows you to make multiple replacements. For example: keyword1, keyword2, keyword3, etc.
Note: Each keyword must have a corresponding replace. Otherwise, it will be ignored and you may receive an error message. All subsequent keyword<x>/replace<x> pairs will also be ignored.
Note: Always define each keyword<x>/replace<x> pair sequentially. For example, do not specify a keyword2/replace2 pair and a keyword4/replace4 pair without a keyword3/replace3 pair between them.
keywordtype<x> Type of keyword. Optional. Valid values are hex, string, and encoding type for the parameter keyword<x>. Encoding type is any supported encoding format such as UTF-8 and UTF-16. Default is string.
Note: Encoding is supported only when literal_mode is set to TRUE.
The following example demonstrates the use of UTF-8 as the encoding type for the parameter keyword<x>:
<output message="DocKeywordReplaceInputMessage">
    <assign to="literal_mode">true</assign>
    <assign to="keyword1" from "'&amp;#x6E;'"></assign>
    <assign to="keywordype1">UTF-8</assign>
    <assign to="replace1" from="'&amp;#x7F;'"></assign>
    <assign to="replacetype1">UTF-8</assign> 
</output>
<x> refers to a sequential number starting with 1. This allows you to make multiple replacements. For example: keywordtype1, keywordtype2, keywordtype3, etc.
Note: This parameter is optional in either mode.
Note: If double byte characters are specified in the keyword<x> parameter, this parameter must be set. Additionally, if double byte characters are specified in the keyword<x> or replace<x> parameters, this parameter must be set to string.
replace<x> Replacement text that the service should use to replace the keyword. Required. Valid values are hex and string. Default is string.<x> refers to a sequential number starting with 1. This allows you to make multiple replacements. For example: replace1, replace2, replace3, etc.
Note: Each replace must have a corresponding keyword. Otherwise, it will be ignored and you will receive an error message.
Note: Always define each keyword<x>/replace<x> pair sequentially. For example, do not specify a keyword2/replace2 pair and a keyword4/replace4 pair without a keyword3/replace3 pair between them.
replacetype<x> Type of replacement text. Optional. Valid values are hex, string, and encoding type for the parameter replace<x>. Encoding type is any supported encoding format such as UTF-8 and UTF-16. Default is string.
Note: Encoding is supported only when literal_mode is set to TRUE.
The following example demonstrates the use of UTF-8 as the encoding type for the parameter replace<x>:
<output message="DocKeywordReplaceInputMessage"> 
   <assign to="literal_mode">true</assign>
    <assign to="keyword1" from "'&amp;#x6E;'"></assign>
    <assign to="keywordype1">UTF-8</assign>
    <assign to="replace1" from="'&amp;#x7F;'"></assign>
    <assign to="replacetype1">UTF-8</assign>
</output><x> refers to a sequential number starting with 1. This allows you to make multiple replacements. For example: replacetype1, replacetype2, replacetype3, etc.
Note: This parameter is optional in either mode.
Note: If double byte characters are specified in the replace<x> parameter, this parameter must be set. Additionally, if double byte characters are specified in the keyword<x> or replace<x> parameters, this parameter must be set to string.
keystart Characters to add to the beginning of the keyword when the service looks for the string to replace. Optional. Default is ${.
Note: Do not specify a value for this parameter if useKeywordDefaults is set to true and you are using String mode.
Note: This parameter can also be specified in Sterling B2B Integrator or in the GPM. However, special characters (for example, characters such as parentheses and brackets) must be specified using BPML.
Note: This parameter is not used if literal_mode is set to true.
keyend Characters to add to the end of the keyword when the service looks for the string to replace. Optional. Default is }.
Note: Do not specify a value for this parameter if useKeywordDefaults is set to true and you are using String mode.
Note: This parameter can also be specified in Sterling B2B Integrator or in the GPM. However, special characters (for example, characters such as parentheses and brackets) must be specified using BPML.
Note: This parameter is not used if literal_mode is set to true.
mode Specifies the mode to use. Optional. Valid values:
  • Document – streams in a complete document in place of a keyword
  • String – does a simple string replacement
Default is String.
Note: This parameter is not used if literal_mode is set to true.
useKeywordDefaults Whether to add the characters specified in keystart and keyend, or their default values, to the start and end of the keyword you are looking for. Optional. Valid values:
  • true – Add the characters specified in keystart and keyend, or the default values, to the start and end of the keyword. This is the default setting.
  • false – Do not add any characters to the start and end of the keyword.
Note: This parameter is not used if literal_mode is set to true.
literal_bufferSize Specifies the size of the buffer used for literal replacements. Optional. Default is 10240 bytes (10 KB).
Note: This parameter can also be specified in the Graphical Process Modeler (GPM).
literal_mode Whether to use high speed literal replacements (literal mode). Valid values: true, false.
Note: Literal mode provides high speed performance by limiting processing overhead. You should use this mode unless you specifically need the capabilities of the other modes. The following parameters are not used if literal_mode is set to true:
  • keystart
  • keyend
  • mode
  • useKeywordDefaults
Note: This parameter can also be specified in the GPM.
literal_readAheadSize Specifies the size of the read-ahead buffer used for literal replacements. Optional. Default is 8192 bytes (8 KB). To ensure proper operation, the value specified for this parameter must be smaller than the value specified for the literal_bufferSize parameter.
Note: This parameter can also be specified in the GPM.

Choosing a Mode

There are three modes available in the Document Keyword Replace service.

Literal Mode

Because Literal mode operation limits processing overhead and performs the search and replace functions only once, this mode is ideal for high-speed replacement operations. You should always use the Document Keyword Replace service in Literal mode, unless you:
  • need to replace a keyword with the contents of a document (use Document mode).
  • need recursive replacement capability (use String mode).
  • are working with the Synchronization Engine adapters (see Synchronization Engine Adapters).
  • need parameters not available in Literal mode (use String mode).
    Note: Because Literal mode limits processing overhead, some parameters are not available in Literal mode. Use String mode if you need these parameters. See literal_mode for a list of these parameters.

Place the service in Literal mode by setting the literal_mode parameter to true. For more information on setting this parameter, see Configuring the Document Keyword Replace Service.

In literal mode, you can also support character deletion.

String Mode

The String mode offers more options and the ability to do recursive replacements. This is the default mode. Place the Document Keyword Replace service in String mode by setting the mode parameter to String, or by not specifying a mode. Ensure the literal_mode parameter is set to false. For more information on setting this parameter, see Configuring the Document Keyword Replace Service.

String mode allows the use of the following parameters:
  • keywordtype
  • replacetype
  • keystart
  • keyend
  • mode
  • useKeywordDefaults
Some situations where you should use String mode include:
  • You need the optional parameters available in String mode
  • You are working with the Synchronization Engine adapters (see Synchronization Engine Adapters)
  • You need to do recursive replacements
    Note: Because String mode operates recursively, the service contains a mechanism to prevent endless loops when using String mode. You should always test your configuration. If you find that any expected replacements were not made, check your keyword and replace parameter settings. For example, if you set up the Document Keyword Replace service to replace the string “ABC” with the string “ABCD”, while in String mode, the service will not allow it. Because the replace parameter value (ABCD) contains the keyword parameter value (ABC), if the service was allowed to run, the result would be an endless series of replacement iterations as shown below:
    • Iteration 1 – ABC
    • Iteration 2 – ABCD
    • Iteration 3 – ABCDD
    • Iteration 4 – ABCDDD
    • Iteration 5 – ABCDDDD
    • This would continue in the same manner endlessly

Document Mode

If you need to replace a string with a complete document, use the Document mode. Place the Document Keyword Replace service in Document mode by setting the mode parameter to Document. For more information on setting this parameter, see Configuring the Document Keyword Replace Service.

Business Process Examples

In the following examples, a notation of #x?? is the hexadecimal equivalent of an unprintable character (?? represents a hexadecimal number).

Note: You cannot just cut and paste (and then run) these examples; you must insert the process name at the beginning of the BPML (such as the following example in which you would replace “somename” with the actual name of the process) and ensure you defined a valid service instance:
<process name="somename">
  <!-- within a process, you can have sequences, assigns, and operations--> 
  </process>

Literal Mode

This sample Business Process searches for all line feed characters and replaces them with a carriage return and tilde:

Note: In the example below, &#x0a; is a hex notation of a “character entity reference” that is defined by html (see http://www.w3.org/TR/REC-html40/sgml/entities.html for more information). 
<process name="test"> 
<sequence>  
<operation name="DocKeywordReplaceImpl"> 
<participant name="myDocKeywordReplaceImplService"/> 
<output message="outmsg"> 
<assign to="." from="*" /> 
<assign to="literal_mode">true</assign> 
<assign to="literal_bufferSize">102400</assign> 
<assign to="literal_readAheadSize">8192</assign> 
<assign to="keyword1">~</assign> 
<assign to="replace1" from="string('&#x0a;')"/> 
<assign to="keyword2" from=”string('&#x0d;&#x7e;')”/> 
<assign to="replace2">Ninety</assign> 
</output> 
<input message="inmsg"> 
<assign to="." from="*" /> 
</input> 
</operation> 
</sequence> 
</process>

For the sample business process above, this is the Primary Document before it is run through the Document Keyword Replace service:

ISA*00*          *00*          *08*9262390000     *14*9252050234*020129*0525*U*00400*000010006*0*P*: 
GS*PD*345345345*9252050234*20020129*0525*10006*T*004010 
ST*852*000010874 
XQ*G*20020128*20020202 
XPO*L774211-01 
N9*VR*0103103*MEASLES ANIMAL HAVEN 
N1*ST*CHART WHSE - LKLD - (942)*9*0069220090942 
LIN**UA*003500005221 
ZA*QA*594*CA*007*20020128 
LIN**UA*003500048553 
ZA*QA*594*CA*007*20020128 
LIN**UA*003500005537 
ZA*QA*576*CA*007*20020128 
LIN**UA*003500048571 
ZA*QA*800*CA*007*20020128 
LIN**UA*003500048501 
ZA*QA*600*CA*007*20020128 
CTT*5 
SE*1*000010874 
GE*1*10006 
IEA*1*000010006

For the sample business process above, this is the Primary Document after it is run through the Document Keyword Replace service:

ISA*00*          *00*          *08*9262390000     *14*9252050234*020129*0525*U*00400*000010006*0*P*:~
  ß----- Note a Tilde was added to the end of each line 
GS*PD*345345345*9252050234*20020129*0525*10006*T*004010~ 
ST*852*000010874~ 
XQ*G*20020128*20020202~ 
XPO*L774211-01~ 
N9*VR*0103103*MEASLES ANIMAL HAVEN~ 
N1*ST*CHART WHSE - LKLD - (942)*9*0069220090942~ 
LIN**UA*003500005221~ 
ZA*QA*594*CA*007*20020128~ 
LIN**UA*003500048553~ 
ZA*QA*594*CA*007*20020128~ 
LIN**UA*003500005537~ 
ZA*QA*576*CA*007*20020128~ 
LIN**UA*003500048571~ 
ZA*QA*800*CA*007*20020128~ 
LIN**UA*003500048501~ 
ZA*QA*600*CA*007*20020128~ 
CTT*5~ 
SE*1*000010874~ 
GE*1*10006~ 
IEA*1*000010006~

Document Mode

Note: The path of the replaceX parameter must include a document name from ProcessData. In the following example, replacementDocument is the name of the document in ProcessData.
<process name="test"> 
 <sequence>  
  <operation name="DocKeywordReplace">
  <participant name="myDocKeywordReplaceService"/>
  <output message="toService">
    <assign to="." from="*"/>
    <assign to="mode">Document</assign>
    <assign to="keyword1">someKeywordToReplace</assign> 
    <assign to="replace1">/ProcessData/replacementDocument</assign>
    <assign to="keyword2">anotherKeywordToReplace</assign>
  <assign to="replace2">/ProcessData/PrimaryDocument</assign>
  </output>
  <input message="fromService">
    <assign to="." from="*"/>
  </input>
 </operation> 
</sequence> 
</process>

String Mode

<process name="test"> 
  <sequence>  
    <operation name="DocKeywordReplaceImpl">
     <participant name="myDocKeywordReplaceImplService"/>
     <output message="outmsg">
       <assign to="." from="*" />
       <assign to="keyword1">GLN</assign>
       <assign to="replace1">0008586666221</assign>
       <assign to="keyword2">GTIN</assign>
       <assign to="replace2" from="string(myData/GTIN)" />
       <assign to="keyword3">USERNAME</assign>
       <assign to="replace3" from="'user1'" />
       <assign to="keystart" from="'$('" />
       <assign to="keyend" from="'$)'" />
     </output>
     <input message="inmsg">
       <assign to="." from="*" />
     </input>
   </operation>
  </sequence> 
</process>

Character Deletion Example

Sterling B2B Integrator now supports character deletion as exemplified in the following BPML assignment:

<process name="DocKeywordRemoveExample">
  <sequence name="Sequence Start">
    <operation name="Document Keyword Replace">
      <participant name="SomeDocKeywordReplaceInstance"/>
      <output message="DocKeywordReplaceInputMessage">
        <assign to="." from="*"/>
        <assign to="literal_mode">true</assign>
        <assign to="literal_bufferSize">102400</assign>
        <assign to="literal_readAheadSize">8192</assign>
        <assign to="keyword1">111111</assign>
        <assign to="replace1" from="string('')"/>
        <assign to="keyword2">ABC</assign>
        <assign to="replace2" from="string('')"/>
      </output>
      <input message="inmsg">
        <assign to="." from="*"/>
      </input>
    </operation>
  </sequence> 
</process>