For Each Document Service

The For Each Document service incrementally processes a set of documents. Each time the service runs, it makes the next document in the document set the primary document. This enables business processes to contain loops that operate on each document in turn.

The following table provides an overview of the For Each Document service:

System name	ForEachDocument
Graphical Process Modeler (GPM) category	All Services
Description	The For Each Document service incrementally processes a set of documents. Each time runs, it makes the next document in the set the primary document. This enables business processes to contain loops that operate on each document in turn.
Business usage	To loop through multiple documents within a business process.
Usage example	Used when there are multiple documents within a business process that need to be processed. This service is used within the X12 Deenvelope and EDIFACT Deenvelope business processes to iterate document deenveloping over functional groups and transaction sets.
Preconfigured?	Yes
Requires third-party files?	No
Platform availability	All supported Sterling B2B Integrator platforms
Related services	The Document Extraction service is often used in conjunction with the For Each Document service to extract individual documents out of a batch file.
Application requirements	None
Initiates business processes?	None
Invocation	Runs as part of a business process.
Business process context considerations	None
Returned status values	Returned status values: Success–The service has set the primary document appropriately. Error–The service encountered an unexpected condition that caused the iteration to fail.
Testing considerations	Create and test a business process that uses this service to incrementally process multiple documents.

How the For Each Document Service Works

Use the For Each Document service when you have multiple documents within the business process that all need to be processed.

The following sections describe a business scenario and sample solutions using the For Each Document service.

Business Scenario

Your company has multiple records that are in a flat file format. You need to extract these records and process each one individually.

Business Solution Example

The following approaches are used to solve the above business scenario.

Create maps required by the Document Extraction service to extract all the individual documents and place them in the business process.
Create a business process that:
- Extracts the documents from the flat file using the Document Extraction service.
- Uses the For Each Document service to iterate through all of the extracted documents.
- Uses a Rule (more_split_docs) created through the Rule Manager and applied through the Edge Editor that checks if all documents have been processed.
- Invokes a subprocess that processes each document.

This business solution is described for both the GPM and the Business Process Modeling Language (BPML).

Note: The focus in this example is on how to use the For Each Document service. The details on the subprocess are not included.

GPM Example

The following example shows a solution to the above business scenario using the GPM:

A flat file containing multiple records is passed to the business process as the primary document.
The Document Extraction service extracts all of the documents from the flat file and places them as individual documents in the process data of the business process.
The For Each Document service iterates through the documents, making each successive document the primary document.
A subprocess runs to process each of the documents.
The Rule (more_split_docs) is applied using the Edge Editor.

The following example shows the GPM configuration of the For Each Document service.

For Each Document Service GPM Configuration

The following graphic shows the Rule Editor and Edge Editor configuration in the GPM for the business process.

DocExtract.DONE is an output parameter from the For Each Document service.

The Rule (more_split_docs) is DocExtract.DONE = 0. This Rule is created using the Rule Manager and applied in the business process using the Edge Editor.

When this rule is true, processing continues. After all the documents are processed, DocExtract.DONE is set to 1 by the For Each Document service and processing stops.

Business Process Modeling (BPML) Example

The following example shows the corresponding business process solution using BPML.

<process name="ForEach_FlatFile_Example"> 
  <rule name="more_split_docs"> 
    <condition>DocExtract.DONE = 0</condition> 
  </rule> 
  <sequence name="Extract"> 
    <operation name="ExtractDocuments"> 
      <participant name="DocumentExtractionService"/> 
      <output message="DocumentExtractionTypeInputMessage"> 
        <assign to="BatchLikeDocuments">NO</assign> 
        <assign to="DocExtractMapList">DocExtract_CTN DocExtract_ITM</assign> 
        <assign to="." from="*"></assign> 
      </output> 
      <input message="inmsg"> 
        <assign to="." from="*"></assign> 
      </input> 
    </operation> 
<sequence name="foreachSplitDoc"> 
      <operation name="For Each Document"> 
        <participant name="ForEachDocument"/> 
        <output message="ForEachDocumentTypeInputMessage"> 
          <assign to="DOCUMENT_NAME_PREFIX">DOC-SPLIT-</assign> 
          <assign to="ITERATOR_NAME">DocExtract</assign> 
          <assign to="." from="*"></assign> 
        </output> 
        <input message="inmsg"> 
          <assign to="." from="*"></assign> 
        </input> 
      </operation> 
      <choice name="Choice Start"> 
        <select> 
          <case ref="more_split_docs" activity="new_item_split_doc"/> 
        </select> 
<sequence name="new_item_split_doc"> 
            <operation name="Invoke Sub-Process"> 
              <participant name="InvokeSubProcessService"/> 
              <output message="InvokeSubProcessServiceTypeInputMessage"> 
                <assign to="INVOKE_MODE">ASYNC</assign> 
                <assign to="NOTIFY_PARENT_ON_ERROR">ALL</assign> 
                <assign to="WFD_NAME"> ProcessNewItemRequest</assign> 
                <assign to="." from="*"></assign> 
              </output> 
              <input message="inmsg"> 
                <assign to="." from="*"></assign> 
              </input> 
            </operation> 
            <repeat name="repeater" ref="foreachSplitDoc"/> 
        </sequence> 
      </choice> 
    </sequence> 
  </sequence> 
</process>

Process Data

The following shows process data after the documents are extracted and the first document has been processed.

The following shows the process data after the business process has completed.

Process Data After BP Completion

Note: When the Document Extraction service parameter PDToProcessData is set to No, process data will only contain the current DOC_SPLIT section. Each iteration through the For Each Document service will update process data with the current DOC_SPLIT and remove the previous split.

Output from Service to Business Process

The following table describes the output from the For Each Document service to the business process. The parameters in the table, along with their values, are put into process data for use later in a business process.

Note: In the following table, I is replaced with the value of the ITERATOR_NAME parameter. If the ITERATOR_NAME were TEST, these parameters would be TEST, TEST.INDEX, TEST.NAME, and TEST.DONE.

Parameter	Description
I	ArrayList containing the document data in the order that the documents are processed.
I.INDEX	The index of the document that was most recently made the primary document.
I.NAME	Name of the document that was most recently made the primary document.
I.DONE	Valid values: 0 – There are documents remaining to be processed. 1 – The iteration is complete.

The following example shows the process data with the output parameters. The array list in this case is named DocExtract.

<ProcessData> 
. 
. 
. 
<DocExtract SCIObjectID="L2000-000248:f96c:fb591069a2:-60ea"/> 
<DocExtract.NAME>DOC-SPLIT-1</DocExtract.NAME> 
<DocExtract.INDEX SCIObjectID="L2000-000248:f96c:fb591069a2:-60e8"/> 
<DocExtract.DONE>0</DocExtract.DONE> 
. 
. 
</ProcessData>

Usage Examples

The following business processes are predefined in Sterling B2B Integrator:

The X12Deenvelope business process
The EDIFACTDeenvelope business process

Implementing the For Each Document Service

To implement the For Each Document service, complete the following tasks:

If a configuration does not already exist, create a For Each Document service configuration. For information, see Managing Services and Adapters.
Note: A For Each Document service is configured with the installation of Sterling B2B Integrator.
Configure the For Each Document service. For information, see Configuring the For Each Document Service.
Use the For Each Document service in a business process.

Configuring the For Each Document Service

To configure the For Each Document service, you must specify field settings in Sterling B2B Integrator and in the GPM.

The following example shows the GPM parameters for the For Each Document service. There are no fields to be configured on the Message From Service tab.

The following example shows the corresponding BPML parameters for the For Each Document service GPM parameters.

<operation name="For Each Document"> 
        <participant name="ForEachDocument"/> 
        <output message="ForEachDocumentTypeInputMessage"> 
          <assign to="DOCUMENT_NAME_PREFIX">DocumentPrefix</assign> 
          <assign to="ITERATOR_NAME">ExampleIterator</assign> 
          <assign to="." from="*"></assign> 
        </output> 
        <input message="inmsg"> 
          <assign to="." from="*"></assign> 
        </input> 
      </operation>

GPM Configuration

The following table describes the fields used to configure the For Each Document service in the GPM:

Field	Description
Config(participant name)	Name of the service configuration.
ITERATOR_NAME	Name used to identify this document iterator in the business process. This is the prefix for the tags that are generated by the service and is incremented as it loops through the documents.
DOCUMENT_NAME_PREFIX	Filter that restricts the documents included in the iteration. The filter is the prefix on each document name. When this parameter is used, only documents beginning with this prefix are processed. If DOCUMENT_KEY_PREFIX is used, this parameter is ignored. If neither this parameter or DOCUMENT_KEY_PREFIX is specified, all documents in the business process are processed by the For Each service.
DOCUMENT_KEY_PREFIX	Filter that restricts the documents included in the iteration. The filter is the prefix on the key in process data for each document. When this parameter is used, only documents that have keys beginning with this prefix are processed. The parameter DOCUMENT_NAME_PREFIX is ignored if this parameter is specified. If neither this parameter or DOCUMENT_NAME_PREFIX is specified, all documents in the business process are processed by the For Each service.