SplitBatch

Syntax

bool SplitBatch ()

Parameters

SplitIndicatorVariable: String.

The specified variable must exist on document and page objects that are to be split into one or more child batches. The name of the variable is determined by the user. It is expected that before calling this action, the application has added the variable to the objects that are to be split and been configured with a value indicating which objects are grouped together. This variable can be procreated in the Setup DCO or can be set at runtime on the appropriate objects to split.

The values of the smart parameter variable found during the document and page evaluation are grouped into "buckets":
  1. Pages/documents that contain the variable and the variable values are identical go into the same bucket.
  2. If there are multiple buckets, all pages/documents that share the same value will split to the same child batch. A child batch will be created for each unique value of the variable. The values are user defined. The action only determines which objects have the same value for the specified variable.
  3. There can be only one child batch for each unique bucket value.

Child batches have the same name as the parent batch, but include an additional two character alpha-decimal suffix such as .01, .02, .0A, ..., up to .ZZ. This hexadecimal numbering for child batches is required by the Datacap Server. Datacap Server creates the batch and queue entries for the child batches after the task is finished, when the split condition is processed. There is a maximum of 1295 child batches.

Returns

False if an error occurs such as a file that could not be created, etc., and the batch will be set to abort. Otherwise True. If the specified variable is not found in any documents or unbound pages, meaning there is nothing to split, the action is still considered to be successful and will return true.

Each child batch split off will generate a condition, which should be configured for Split in the workflow. Any page or document with a blank value for the splitting value will remain in the original "parent" batch.

Level

Batch level only.

Details

This action will process all of the documents and "unbound" pages that are in the batch and attempt to split the identified documents and pages into child batches. The action will look in the documents or unbound pages for the variable specified in the a parameter, group the objects that have a matching value and split each group into a unique child batch.

Only documents and unbound pages will be processed. An unbound page is a page that is not a child of a document object. An unbound page has the batch object as its direct parent. Pages that are already placed within in a document structure will not be processed individually, the pages will be as part of their document, not as a separate page. If a document object contains the specified variable, then all of the child pages will be moved to the child batch and remain as child pages for the document.

Additional considerations: There is only one "job routing condition" raised by this action: it is the first one in the task's list of conditions. The task's Task Setup/Task Settings screen must be configured as Job Router, and a single condition defined (by convention, call it Split).
  1. Any and all child batches will be routed via this single condition.
  2. If the application wants to treat the individual buckets differently, then the first step in the workflow after splitting can check the same smart parameter value and branch or re-route the child batch using that value.
  3. All the structure and variables, etc. that were in the parent batch docs/pages are retained in the child batches.
  4. In addition, new variables ParentBatch and ParentBatchDir are added.
  5. The action can only be used once per Parent Batch.
  6. The maximum number of child batches is 1295.

If there is an error during the split batch processing, such as a file cannot be accessed, then the operation will be automatically retried. The DCO variables Counterrevolutionary and SplitBatchRetrySleep can be configured to control the retry operation.

SplitBatchRetrySleep

This variable can be used to set the retry count for the SplitBatch action. To take affect, this variable must be set on the object that calls the SplitBatch action. If not set, the retry count will default to 3.

SplitBatchRetrySleep

This variable can be set sleeping time between the retries. To take affect, this variable must be set on the object that calls the SplitBatch action. If not set default value will be 1 second.
SplitBatch(@D.SplitBucket)
This example uses a user defined variable called SplitBucket. This variable must exist on all "unbound" page objects or document objects that are to be moved to child batches. Any unbound page or document object that does not have this variable will remain in the main batch.
Assuming the batch has this document structure prior to calling split batch:
˂B id="MyApplication">
+ ˂P ID="TM000001">
- - ˂V n="TYPE">Other˂/V>
- - ˂V n="STATUS">0˂/V>
- ˂/P>
+ ˂P ID="TM000002">
- - ˂V n="TYPE">Other˂/V>
- - ˂V n="STATUS">0˂/V>
- - ˂V n="SplitBucket">B1˂/V>
- ˂/P>
+ ˂P ID="TM000003">
- - ˂V n="TYPE">Other˂/V>
- - ˂V n="STATUS">0˂/V>
- - ˂V n="SplitBucket">B2˂/V>
- ˂/P>
+ ˂D type="20290425.000007.01">
- - ˂V n="TYPE">Document1˂/V>
- - ˂V n="STATUS">0˂/V>
- - ˂V n="SplitBucket">B2˂/V>
+ - ˂P ID="TM000004">
- - - ˂V n="TYPE">Main_Page˂/V>
- - - ˂V n="STATUS">0˂/V>
- - ˂/P>
+ - ˂P ID="TM000005">
- - - ˂V n="TYPE">Trailing_Page˂/V>
- - - ˂V n="STATUS">0˂/V>
- - ˂/P>
- ˂/D>
+ ˂D type="20290425.000007.02">
- - ˂V n="TYPE">Document1˂/V>
- - ˂V n="STATUS">0˂/V>
+ - ˂P ID="TM000006">
- - - ˂V n="TYPE">Main_Page˂/V>
- - - ˂V n="STATUS">0˂/V>
- - ˂/P>
+ - ˂P ID="TM000007">
- - - ˂V n="TYPE">Trailing_Page˂/V>
- - - ˂V n="STATUS">0˂/V>
- - ˂/P>
- ˂/D>
˂/B>
Two child batches will be created because there are two unique values in the variable "SplitBucket". One child batch will contain the page with ID=TM000002. The other batch will contain the page TM000003, the document "01" object and the pages TM000004 and TM000005.

The original batch will still contain the page TM000001 and the document "02" with the pages TM000006 and TM000007.