4 Creating Recognition Processor Scripts

This chapter describes creating Recognition Processor scripts.

The following are common uses for Recognition Processor scripts:

• Splitting a single bar code value into multiple field values.

• Assigning bar code value(s) to proper fields.

• Using custom logic to determine which pages constitute document separation.

• Performing custom auditing of server activity.

• Canceling the committing of a batch due to invalid data.

Capture enables you to create Recognition Processor scripts to customize recognition processing. For more information, see Managing Oracle WebCenter Enterprise Capture.

This chapter covers the following topics:

• Recognition Processor Methods

• Recognition Processor Classes

• Sample Recognition Processor Script

4.1 Recognition Processor Methods

This section provides a description of the Recognition Processor methods. Methods are executed in the following order in Recognition Processor batch jobs:

1. initialize

2. processBatch

3. restoreCaptureBatch

4. beginPhase

5. endPhase

6. extractBatchItem

7. barcodesFoundOnItem

8. batchItemAllValidBarcodes

9. determineSeparatorPage

10. batchItemValidBarcode

11. determineDocType

12. beginDatabaseLookup

13. determineIndexValues

14. renameOrigCaptureDocTitle

15. createCaptureDoc

16. postProcess

17. endBatchProcess

Note: Some methods are only executed under certain job configurations.

4.1.1 initialize

This is the very first call the Recognition Processor makes to the script. There is no batch identified yet.

The following are the properties populated in the Recognition Processor class (rpc):

• phaseID: 0

• logger: Logger can be used to log additional entries. This property remains during the entire process, and does not repeat for every method.

• job: current Recognition Job. This property remains during the entire process, and does not repeat for every method.

• workspaceEntity: Current workspace entity. This property remains during the entire process, and does not repeat for every method.

• batchManager: BatchManager can be used to audit and manipulate batches, documents, and batch items. Use this property with caution when calling methods within BatchManager. If this property is not used properly, batch can get corrupted.

The following table describes the syntax and parameter for this method:

4.1.2 processBatch

The processBatch method is called before the Recognition Processor processes the batch. The following are the properties populated in the rpc:

• phaseID: 0

• ble: At this point, the Recognition Processor has refreshed the document list for the batch. This property will remain during the remainder of the process, and will not repeat for the rest of the methods.

• cancelAction: You can set the flag to true to skip processing of a batch.

• processorBase: Represents a Dynamic Monitoring Service (DMS) Noun object that can be used to collect your own set of metrics. This property will stay through the remainder of the process and does not repeat for each method.

• DMS_Literals: Resource bundles that are being used by DMS. This property will stay through the remainder of the process and does not repeat for each method.

The following table describes the syntax and parameter for this method:

4.1.3 restoreCaptureBatch

The restoreCaptureBatch method is invoked when a batch that was processed earlier was aborted due to an error or other reasons during document creation phase. Recognition Processor must first clean up the batch to restore the batch to its original state, before initiating processing.

The restoreCaptureBatch method is invoked when all the following conditions are met:

• Batch state indicates that the Recognition Processor last failed at the document creation phase.

• Batch has not been modified since last process.

• Recognition job has not been modified since last process.

The Recognition Processor makes sure that both batch and job have not been modified since the last process. In such cases, the Recognition Processor attempts to restore the batch to its original state by removing previous documents created by the recognition process.

The following are the properties populated in the rpc:

• phaseID: 0

• cancelAction: You can set the flag to true to skip restoring of the batch, and the process skips processing this batch.

The following table describes the syntax and parameter for this method:

4.1.4 beginPhase

The beginPhase method indicates the beginning of a phase. The following are the properties populated in the rpc:

• phaseID: Identification of the phase. There are six different phases (see RecognitionProcessorContext for details on RecognitionProcessorContext phaseID).

• cancelAction: You can set the flag to true to skip certain phases. For phases that cannot be skipped, this flag is ignored.

  • Phases that can be canceled are: bar code recognition, document classification, and indexing.

  • Phases that cannot be canceled are: document organization, document creation, and post-processing.

The following table describes the syntax and parameter for this method:

4.1.5 endPhase

The endPhase method indicates the end of a phase. The following are the properties populated in the rpc:

• phaseID: Identification of the phase. There are six different phases (see RecognitionProcessorContext for details on RecognitionProcessorContext phaseID).

The following table describes the syntax and parameter for this method:

4.1.6 extractBatchItem

The extractBatchItem method is executed during the bar code recognition phase. The Recognition Processor extracts batch items, one at a time, into a directory right before the Recognition Processor performs bar code recognition on the page. Then the Recognition Processor informs you where the items are located.

The following are the properties populated in the rpc:

• phaseID: 1.

• extractPath: The directory where the batch item is located.

The following table describes the syntax and parameter for this method:

4.1.7 barcodesFoundOnItem

The barcodesFoundOnItem method is invoked after the Recognition Processor processed the batch item, collected and recognized bar codes on this item.

The following are the properties populated in the rpc:

• phaseID: 1.

• batchItem: Current batch item that is used to perform bar code recognition.

• patchCodeRead: Patch code value found on the batch item.

• barCodesRead: A combination of bar codes read on the page and existing bar codes on the batch item.

The following table describes the syntax and parameter for this method:

4.1.8 batchItemAllValidBarcodes

The batchItemAllValidBarcodes method is called after the Recognition Processor has finished validating bar codes on a specific batch item.

The following are the properties populated in the rpc:

• phaseID: 2.

• batchItem: Current batch item that is used to perform bar code validation.

• validBarCodes: A list of name and value pairs of the valid bar codes found on the batch item. This list includes all bar codes definitions in the recognition job. You can change the value, but you must not change the name, or add or remove items from the list.

The following table describes the syntax and parameter for this method:

4.1.9 determineSeparatorPage

The determineSeparatorPage method is called after the Recognition Processor has validated a page as a separator. This method is only invoked if a separator page is defined for a recognition job.

The following are the properties populated in the rpc:

• phaseID: 2.

• batchItem: Current batch item that is to determine whether the page is a separator or not.

• validBarCodes: A list of name and value pairs for the valid bar codes found on the batch item. This list includes all bar code definitions in the recognition job.

• separator: This object is null unless this batch item is a valid separator page. If you want to make changes, you must either set the separator to null or to a valid object of class ProcessSeparatorPage.

Recognition Processor’s hierarchical separator feature processes and organizes documents within a hierarchy of levels. You can change the level determined by the Recognition Processor. However, if the level does not fit into a recognition job definition, the Recognition Processor uses either the lowest level (level<=0) or highest level (level>=max defined level). The level property of the separator object is used for the hierarchy separator page type only. For any other document organization type, this value is ignored. Level should always begin with 1.

The following table describes the syntax and parameter for this method:

4.1.10 batchItemValidBarcode

The batchItemValidBarcode method passes in one valid bar code recognized on a specific batch item. This method call will only happen when the document organization type is Same bar code value on each page and Optimize Bar Code Recognition is turned on.

When the Recognition Processor cannot find a bar code on a page, it will try to determine the separator bar code value on the next page. validBarcode is populated with the bar code found on the next page. If bar code is not found, validBarcode is set to null. In such cases, this method is called right after the Recognition Processor has determined the bar code value.

The following are the properties populated in the rpc:

• phaseID: 2.

• batchItem: Next page batch item that is to determine the separator bar code value.

• validBarcode: Name and value pair for the separator bar code. You can change the value if required.

The following table describes the syntax and parameter for this method:

4.1.11 determineDocType

The determineDocType method is called after the Recognition Processor has identified a document type as either the default document type or one of the dynamic document type mappings. docTypeID can be null if the Recognition Processor is unable to identify it.

The following are the properties populated in the rpc:

• phaseID: 3.

• document: Contains the current document information. Some properties are specific to certain document organization type. You can modify the document’s metadata values by using the indexValues property of the document object.

The following table describes the syntax and parameter for this method:

4.1.12 beginDatabaseLookup

The beginDatabaseLookup method is called after the Recognition Processor has determined the lookup value, and before the actual execution of the lookup is called.

The following are the properties populated in the rpc:

• phaseID: 4.

• dbLookupValue: You can modify the lookup value.

• cancelAction: You can cancel lookup.

The following table describes the syntax and parameter for this method:

4.1.13 determineIndexValues

The determineIndexValues method is called after the Recognition Processor has determined all metadata values for a particular document. You can modify the metadata values.

The following are the properties populated in the rpc:

• phaseID: 4.

• document: Contains the current document information. Some properties are specific to certain document organization types. You can modify the metadata values of the document by using the indexValues property of the document object.

The following table describes the syntax and parameter for this method:

4.1.14 renameOrigCaptureDocTitle

The renameOrigCaptureDocTitle method is called before the Recognition Processor renames the original document as unindexed. This applies to all document organization types except the Do not perform document organization type.

The following are the properties populated in the rpc:

• phaseID: 5.

• unIndexedDocTitle: You can change the title.

The following table describes the syntax and parameter for this method:

4.1.15 createCaptureDoc

Before the Recognition Processor creates the Capture document, it is possible to customize the document title, document type id, metadata values, and document comments. You can also change the batch items associated with this document, although in the case of the Do not perform document organization type, changing batch items does not affect the outcome.

Note: You must be careful while changing batch items as it may, possibly leave orphan items in the batch, that are not associated with any documents.

The following are the properties populated in the rpc:

• phaseID: 5.

• document: Capture document that the Recognition Processor is about to create.

The following table describes the syntax and parameter for this method:

4.1.16 postProcess

The postProcess method is invoked after the Recognition Processor has determined all post-process settings, but before any actual changes take place.

The following is the property populated in the rpc:

• phaseID: 6.

The following table describes the syntax and parameter for this method:

4.1.17 endBatchProcess

The endBatchProcess method indicates that the Recognition Processor has finished processing the batch.

The following is the property populated in the rpc:

• phaseID: 0

The syntax for this method is: public void endBatchProcess(RecognitionProcessorContext rpc);

4.2 Recognition Processor Classes

The Recognition Processor classes can be used to design Recognition Processor scripts. This section describes the following classes:

• BarcodeDefinition

• DocumentDefinition

• PostProcessContext

• ProcessorAttachment

• ProcessorDocument

• ProcessorItem

• ProcessSeparatorPage

• RecognitionJob

• RecognitionJobField

• RecognitionProcessorContext

• SeparatorDefinition

• SeparatorRuleDefinition

In addition to the following classes that can be used to design Recognition Processor scripts, there are some common classes that pertain to the Recognition Processor and the Import Processor. For more information on the common classes, see Common Capture Classes.

4.2.1 BarcodeDefinition

The BarcodeDefinition class contains the constants for the bar code validation rule type. This class represents one bar code definition specified in the third train stop of Recognition Processor Job.

4.2.2 DocumentDefinition

When a document profile is set to Determine dynamically using bar code, you can define Document Profile and Bar Code Value Mappings. Each mapping is represented by a DocumentDefinition class.

4.2.3 PostProcessContext

The PostProcessContext class represents all the settings needed to apply to a batch after processing is completed. If there is any error during processing, PostProcessContext data is populated from the setting of Post Process train stop of Recognition Processor Job.

4.2.4 ProcessorAttachment

The ProcessorAttachment class is a representation of a logical capture document attachment that Recognition Processor has identified. In the last phase of the document creation phase, the Recognition Processor attempts to create document attachment to the associated capture documents, based on a collection of ProcessorAttachments.

4.2.5 ProcessorDocument

The ProcessorDocument class is a representation of a logical capture document that Recognition Processor has identified. In the last phase of the document creation phase, the Recognition Processor attempts to create documents within the batch, based on a collection of ProcessorDocument.

4.2.6 ProcessorItem

The ProcessorItem class is a representation of an item identified by Name and Value properties. This class holds the name and value pair for a metadata field. In this case, this class holds a particular bar code’s name and value.

4.2.7 ProcessSeparatorPage

The ProcessSeparatorPage class represents a separator page that has been identified by Recognition Processor.

4.2.8 RecognitionJob

The RecognitionJob class represents a Recognition Process Job and contains the constants for the bar code symbologies.

4.2.9 RecognitionJobField

The RecognitionJobField class represents each field in the Fields train stop.

4.2.10 RecognitionProcessorContext

The RecognitionProcessorContext class is a context object that contains relevant attributes that relates to the recognition processing.

4.2.11 SeparatorDefinition

The SeparatorDefinition class represents the definition on what is considered a separator page.

4.2.12 SeparatorRuleDefinition

The SeparatorRuleDefinition class represents one rule that applies to a separator definition.

4.3 Sample Recognition Processor Script

The following steps are involved in configuring a batch job:

• Set the job to detect PDF417 bar codes.

• Set the PDF417 bar code on the page to be | delimited, and has 10 fields concatenated together.

• Define three bar code definitions: processorDate, Title, and Amount (with no validation rules).

• Map the three bar code definitions to three index fields.

The Recognition Processor script parses a PDF417 bar code found on a batch item, parses the value, and applies appropriate parsed text to the three bar code definitions. This sample script allows you to modify the processing behavior based on the job configuration steps:

function batchItemAllValidBarcodes (rpc) {
        // Obtain current batch item
        var batchItem = rpc.getBatchItem();
	
        // obtain bar code count.
        var count = batchItem.getBarcodeCount();
 
        // All barcodes on a batch item.
	var allBarcodes;
 
        // bar code of interest.
	var barcodeValue;
 
        // after parsed barcode value.
        var parsed;
	
        // Obtain bar code value if there is a bar code found.
        if (count > 0) {
                allBarcodes = batchItem.getBarcodes();
                barcodeValue = allBarcodes[0];
 
                // Parse the bar code value by | character.
                var regex = "|";
                  parsed = barcodeValue.split(regex);
                var len = parsed.length;
 
 
                // It should get splitted into 10 strings.
                if (len == 10) {
                        // This is the barcode we want, populate valid bar codes.
                        populateValues(rpc, parsed);
                }
 
        }	
}
 
function populateValues(rpc, parsed) {
        var valid = rpc.getValidBarcodes();
        var i;
 
        for (i=0; i<valid.size(); i++) {
                var bar = valid.get(i);
 
                if (bar.getName() == "processDate") {
                        bar.setValue(parsed[5]);
                } else if (bar.getName() == "Title") {
                        bar.setValue(parsed[6]);
                } else if (bar.getName() == "Amount") {
                        bar.setValue(parsed[4]);
                }	
        }
}