8 Working with Common Capture Classes

This chapter describes the common Capture classes that pertain to the Recognition Processor and the Import Processor.

This is in addition to the classes that you can use to design the Recognition Processor scripts and the Import Processor scripts. For more information on the Recognition Processor and Import Processor classes, see Recognition Processor Classes and Import Processor Classes.

8.1 Common Capture Classes

The following are the classes that pertain to the Recognition Processor and the Import Processor:

• BatchEntity

• BatchItemEntity

• BatchLockEntity

• BatchManagerSession

• BatchStatusEntity

• CaptureWorkspaceEntity

• DBSearchResults

• DBSearchResultRow

• DBSearchFieldInfo

• DocumentEntity

• DocumentPageEntity

• DocumentTypeEntity

• IndexDefinitionEntity

• IndexValue

8.1.1 BatchEntity

The BatchEntity class represents a batch within a Capture Workspace. A batch is a collection of batch items and documents.

Property	Type	Description
itemID	String	The unique batch item identifier.
id	Integer	The unique batch ID.
state	Integer	The current state of the batch, which will be one of the following values: 1 – READY 2 – LOCKED 16 – ERROR 32 – PROCESSING
errorMessage	String	An error message related to processing failure.
status	BatchStatusEntity	A reference to a BatchStatusEntity that represents the current status of the batch.
priority	Integer	The current priority value of the batch.
itemCount	Integer	The number of items in the batch.
userID	String	The user id of the user that created the batch.
workstationID	String	The host name of the system that created the batch.
comment	byte[]	A comment or note regarding the batch.
dateTime	Date	The date and time the batch was created.
workspace	CaptureWorkspaceEntity	A reference to the workspace to which the batch belongs.
documents	List<DocumentEntity>	A list of DocumentEntity references that exist in the batch.
items	List<BatchItemEntity>	A list of batch items associated with the batch.
lastModifiedDateTime	Date	The date and time the batch was last modified.
lastModifiedUserID	String	The ID of the user that last modified the batch.
batchName	String	The name of the batch.

8.1.2 BatchItemEntity

The BatchItemEntity class represents a batch item within a batch. BatchItemEntities are associated with DocumentPageEntities that are used to form documents within a batch.

Property	Type	Description
itemID	String	The unique batch item identifier.
sourceFileName	String	The original file name of the item. Useful if the item is an imported file.
sourceFormat	String	For non–image files, this is generally the file extension (DOC, XLS, PDF). For image files, the value will be empty.
patchCode	Integer	A patch code value if a patch code was read.
barcodeCount	Integer	The number of barcodes that were read during barcode detection.
linkCount	Integer	The number of documents the item is linked to.
fileLength	Long	The size of the item in bytes.
barcodes	String[]	An array of strings that represent barcode values that were read during barcode recognition.

8.1.3 BatchLockEntity

The BatchLockEntity class represents a lock on a batch. The lock is used to prevent users and processors from accessing the same batch simultaneously.

Property	Type	Description
id	String	The unique batch lock ID.
batch	BatchEntity	A reference to the locked batch.
batchName	String	The name of the batch to which the batch lock is applied.
workspace	CaptureWorkspaceEntity	A reference to the workspace to which the batch belongs.
workspaceName	String	The name of the workspace to which the batch belongs.
lockDate	Date	The date that the batch lock was created.
userID	String	The ID of the user who locked the batch.
computerName	String	The name of the computer used to lock the batch.
processID	String	The process ID used to lock the batch.

8.1.4 BatchManagerSession

The BatchManagerSession class provides methods to audit actions and manipulate batch, document, document page, and batch item objects. This includes create, read, update, delete, move, and so on.

This class includes the following methods:

• auditActivity()

• calculateTotalDocumentPagesInBatch()

• createDocument()

• createDocumentAttachments()

• deleteDocument()

• findDocumentByID()

• findBatchItemByID()

• linkItemToDocument()

• loadBatchItems()

• loadDocumentPages()

• loadDocuments()

• loadDocumentAttachments()

• persistBatch()

• persistBatchItem()

• persistDocument()

• unlinkDocumentPage()

• deleteDocumentPages()

• insertItemsIntoDocument()

• splitDocument()

• mergeDocuments()

auditActivity()

The following table describes the syntax for auditActivity() method:

Syntax	Description
public void auditActivity(BatchLockEntity ble, Integer actionID, int dataInt, float dataFloat, String dataText1, String dataText2, String dataText3, String dataText4, String dataText5) throws CaptureException	Writes an audit record to the database for a process defined action.

The following table describes the parameters for auditActivity() method:

Parameter	Type	Description
ble	BatchLockEntity	The batch lock for the batch being acted on.
actionID	Integer	The identifier of the action to log. This is specific to the process.
dataInt	int	A process and action specific integer.
dataFloat	Float	A process and action specific float.
dataText1	String	A process and action specific text value.
dataText2	String	A process and action specific text value.
dataText3	String	A process and action specific text value.
dataText4	String	A process and action specific text value.
dataText5	String	A process and action specific text value.

calculateTotalDocumentPagesInBatch()

The following table describes the syntax for calculateTotalDocumentPagesInBatch() method:

Syntax	Description
public Integer calculateTotalDocumentPagesInBatch(String batchID) throws CaptureException)	Calculates the total number of batch items that are linked to documents.

The following table describes the parameters for calculateTotalDocumentPagesInBatch() method:

Parameter	Type	Description
batchID	String	The identifier of the batch.

The following table describes the values that are returned for calculateTotalDocumentPagesInBatch() method:

Value	Type	Description
return	Integer	An integer representing the total number of document pages in the batch.

createDocument()

The following table describes the syntax for createDocument() method:

Syntax	Description
public String createDocument(String batchLockID, DocumentEntity doc, Integer insertionPoint) throws BatchLockException, CaptureException	Associates a document object with the specified locked batch.

The following table describes the parameters for createDocument() method:

Parameter	Type	Description
batchLockID	String	The unique identifier of the batch lock.
doc	DocumentEntity	The document entity that is to be associated with the batch.
insertionPoint	Integer	The document number where this doc should be inserted.

The following table describes the values that are returned for createDocument() method:

Value	Type	Description
return	String	The unique document identifier.

createDocumentAttachments()

The following table describes the syntax for createDocumentAttachments() method:

Syntax	Description
public void createDocumentAttachments(String batchLockID, List<DocumentEntity> documents, List<BatchItemEntity> items, Integer insertionPoint, Boolean reNumberFirstDocument, String parentDocID) throws BatchLockException, CaptureException	Creates a collection of DocumentEntities as attachments to a specified document and BatchItemEntities to the database. A client might call this method to create a series of batch items and document entities rather than making repeated requests to the server.

The following table describes the parameters for createDocumentAttachments() method:

Parameter	Type	Description
batchLockID	String	The unique identifier of the batch lock.
documents	List<DocumentEntity>	A collection of document objects that require database persistence.
items	List<BatchItemEntity>	A collection of batch item objects that require database persistence.
insertionPoint	Integer	An integer that represents where the document will be inserted.
reNumberFirstDocument	Boolean	A Boolean indicating whether the first document should be renumbered. You should specify False, if the first document already exists in the database.
parentDocID	String	An identifier of a parent document to associate the attachments with.

deleteDocument()

The following table describes the syntax for deleteDocument() method:

Syntax	Description
public void deleteDocument(String batchLockID, String documentID) throws BatchLockException, CaptureException	Deletes a document in the specified locked batch.

The following table describes the parameters for deleteDocument() method:

Parameter	Type	Description
batchLockID	String	The unique identifier of the batch lock.
documentID	String	The unique identifier of the document to delete.

findDocumentByID()

The following table describes the syntax for findDocumentByID() method:

Syntax	Description
public DocumentEntity findDocumentByID(String docID) throws CaptureException	Locates a DocumentEntity by its identifier.

The following table describes the parameters for findDocumentByID() method:

Parameter	Type	Description
docID	String	The unique identifier of the document to locate.

The following table describes the values that are returned for findDocumentByID() method:

Value	Type	Description
return	DocumentEntity	If a matching document is found, the associated entity of the document will be returned. If a match could not be found, then null is returned.

findBatchItemByID()

The following table describes the syntax for findBatchItemByID() method:

Syntax	Description
public BatchItemEntity findBatchItemByID(String docPageID) throws CaptureException	Locates the BatchItemEntity for the specified docPageID.

The following table describes the parameters for findBatchItemByID() method:

Parameter	Type	Description
docPageID	String	The unique identifier of the batch item to locate.

The following table describes the values that are returned for findBatchItemByID() method:

Value	Type	Description
return	BatchItemEntity	If a matching batch item is found, the associated entity of the batch item will be returned. If a match could not be found, then null is returned.

linkItemToDocument()

The following table describes the syntax for linkItemToDocument() method:

Syntax	Description
public DocumentPageEntity linkItemToDocument(String batchLockID, String imageID, String documentID, Integer documentPage) throws CaptureException, BatchLockException	Associates a batch item with a document.

The following table describes the parameters for linkItemToDocument() method:

Parameter	Type	Description
batchLockID	String	The identifier of the batch lock.
imageID	String	The identifier of the batch item.
documentID	String	The document identifier.
documentPage	Integer	The page number for this item.

The following table describes the values that are returned for linkItemToDocument() method:

Value	Type	Description
return	DocumentPageEntity	A DocumentPageEntity reference containing the linked page.

loadBatchItems()

The following table describes the syntax for loadBatchItems() method:

Syntax	Description
public List<BatchItemEntity> loadBatchItems(String batchID) throws CaptureException	Returns a list of batch items belonging to the specified batch.

The following table describes the parameters for loadBatchItems() method:

Parameter	Type	Description
batchID	String	The unique identifier of the batch.

The following table describes the values that are returned for loadBatchItems() method:

Value	Type	Description
return	List<BatchItemEntity>	A collection of items belonging to the batch.

loadDocumentPages()

The following table describes the syntax for loadDocumentPages() method:

Syntax	Description
public List<DocumentPageEntity> loadDocumentPages(String documentID) throws CaptureException	Returns a collection of document objects associated with a batch.

The following table describes the parameters for loadDocumentPages() method:

Parameter	Type	Description
documentID	String	The document identifier.

The following table describes the values that are returned for loadDocumentPages() method:

Value	Type	Description
return	List<DocumentPageEntity>	A collection of document pages associated with the document.

loadDocuments()

The following table describes the syntax for loadDocuments() method:

Syntax	Description
public List<DocumentEntity> loadDocuments(String batchID) throws CaptureException	Returns a collection of document objects associated with a batch.

The following table describes the parameters for loadDocuments() method:

Parameter	Type	Description
batchID	String	The unique identifier of the batch.

The following table describes the values that are returned for loadDocuments() method:

Value	Type	Description
return	List<DocumentEntity>	A collection of document pages associated with the document.

loadDocumentAttachments()

The following table describes the syntax for loadDocumentAttachments() method:

Syntax	Description
public List<DocumentEntity> loadDocumentAttachments(String docID) throws CaptureException	Returns a collection of document objects attached to a specified document.

The following table describes the parameters for loadDocumentAttachments() method:

Parameter	Type	Description
docID	String	The unique identifier of the source document.

The following table describes the values that are returned for loadDocumentAttachments() method:

Value	Type	Description
return	List<DocumentEntity>	A collection of documents attached to the source document.

persistBatch()

The following table describes the syntax for persistBatch() method:

Syntax	Description
public void persistBatch(String batchLockID, BatchEntity be) throws BatchLockException, CaptureException	Persists the specified batch to the database.

The following table describes the parameters for persistBatch() method:

Parameter	Type	Description
batchLockID	String	The unique identifier of the batch lock.
be	BatchEntity	The batch entity that is to be updated.

persistBatchItem()

The following table describes the syntax for persistBatchItem() method:

Syntax	Description
public BatchItemEntity persistBatchItem(String batchLockID, BatchItemEntity entity) throws BatchLockException, CaptureException	Persists an item to the specified locked batch.

The following table describes the parameters for persistBatchItem() method:

Parameter	Type	Description
batchLockID	String	The identifier of the batch lock.
entity	BatchItemEntity	A BatchItemEntity to persist.

The following table describes the values that are returned for persistBatchItem() method:

Value	Type	Description
return	BatchItemEntity	A reference to the BatchItemEntity object that was persisted.

persistDocument()

The following table describes the syntax for persistDocument() method:

Syntax	Description
public void persistDocument(String batchLockID, DocumentEntity document) throws CaptureException	Persists a specific document entity within a batch.

The following table describes the parameters for persistDocument() method:

Parameter	Type	Description
batchLockID	String	The identifier of the batch lock.
document	DocumentEntity	A DocumentEntity to persist.

unlinkDocumentPage()

The following table describes the syntax for unlinkDocumentPage() method:

Syntax	Description
public void unlinkDocumentPage(String batchLockID, String documentPageID) throws BatchLockException, CaptureException	Unlinks a document page in the specified pages collection from their associated document.

The following table describes the parameters for unlinkDocumentPage() method:

Parameter	Type	Description
batchLockID	String	The unique identifier of the batch lock.
documentPageID	String	The identifier of the page to unlink.

deleteDocumentPages()

The following table describes the syntax for deleteDocumentPages() method:

Syntax	Description
public void deleteDocumentPages(String batchLockID, List<DocumentPageEntity> pages) throws BatchLockException, CaptureException	Unlinks the specified document pages in the pages collection from their associated document.

The following table describes the parameters for deleteDocumentPages() method:

Parameter	Type	Description
batchLockID	String	The unique identifier of the batch lock.
pages	List<DocumentPageEntity>	A collection of pages that require unlinking from their respective documents.

insertItemsIntoDocument()

The following table describes the syntax for insertItemsIntoDocument() method:

Syntax	Description
public void insertItemsIntoDocument(String batchLockID, String docID, Integer insertionPoint, List<BatchItemEntity> items) throws BatchLockException, CaptureException	Persists batch item entities in the items collection to the database and creates links to the items in the specified document.

The following table describes the parameters for insertItemsIntoDocument() method:

Parameter	Type	Description
batchLockID	String	The unique identifier of the batch lock.
docID	String	The identifier of the document to which items will be inserted.
insertionPoint	Integer	The point at which the items must be inserted.
items	List<BatchItemEntity>	A collection of items that need persistence.

splitDocument()

The following table describes the syntax for splitDocument() method:

Syntax	Description
public DocumentEntity splitDocument(String batchLockID, String sourceDocID, Integer docBreakPoint, String newDocTitle) throws BatchLockException, CaptureException	Breaks a source document into a new document at the specified break point. A new document is created in the database and all pages from the source document starting at the specified breakpoint will be moved into the new document and removed from the source.

The following table describes the parameters for splitDocument() method:

Parameter	Type	Description
batchLockID	String	A valid batch lock identifier for the batch being manipulated.
sourceDocID	String	The source document containing the pages to branch.
docBreakPoint	Integer	The starting page number of pages to move.
newDocTitle	String	The title of the new document to be created.

The following table describes the values that are returned for splitDocument() method:

Value	Type	Description
return	DocumentEntity	A new document entity that contains the pages from the source branch.

mergeDocuments()

The following table describes the syntax for mergeDocuments() method:

Syntax	Description
public void mergeDocuments(String batchLockID, MetadataMergeOption mergeOption,DocAttachmentIncludeOption attachmentIncludeOption, DocumentEntity sourceDocument, List<DocumentEntity> destinationDocuments, boolean addToBeginning) throws CaptureException, BatchLockException	Merges two documents into one.

The following table describes the parameters for mergeDocuments() method:

Parameter	Type	Description
batchLockID	String	The identifier of the batch lock.
mergeOption	MetadataMergeOption	Indicates how to handle document indexes during merge. Following are the possible values: discardSourceValues applySourceValuesOverwrite applySourceValuesDoNOTOverwrite
attachmentIncludeOption	DocAttachmentIncludeOption	Indicates how to handle document attachments during merge. Following are the possible values: doNotInclude includeAll includeOnlyMatches (Include only those attachments with matching attachment types.)
sourceDocument	DocumentEntity	Source document entity.
destinationDocuments	List<DocumentEntity>	The destination documents collection.
addToBeginning	Boolean	Indicates whether the source document is to be merged to the beginning of the destination documents collection or not.

8.1.5 BatchStatusEntity

The BatchStatusEntity class defines a batch status within a Capture Workspace. Batch statuses may be associated with batches within a Capture Workspace.

Property	Type	Description
statusID	String	The unique identifier of the status.
value	String	The text value of the status.
workspaceEntity	CaptureWorkspaceEntity	A reference to the workspace where the status is defined.

8.1.6 CaptureWorkspaceEntity

The CaptureWorkspaceEntity class represents a workspace in the Capture system. A workspace defines metadata, document profiles, and batch statuses.

Property	Type	Description
workspaceID	String	The unique workspace identifier.
workspaceName	String	The name of the workspace.
description	String	A description of the workspace.
dateCreated	Date	The date the workspace was created.
dateLastModified	Date	The date the workspace was last modified.
createdBy	String	The user ID of the user that created the workspace.
lastModifiedBy	String	The user ID of the user that last modified the workspace.
indexDefinitions	List<IndexDefinitionEntity>	A list of index definition entities that have been defined in the workspace.
statuses	List<BatchStatusEntity>	A list of batch statuses defined in the workspace.
documentTypes	List<DocumentTypeEntity>	A list of document profiles that have been defined in the workspace.

8.1.7 DBSearchResults

The DBSearchResults class contains information returned from executing a database lookup. It contains a list of the rows returned as well as a list of the search field information describing the columns of the rows.

Property	Type	Description
resultsList	List<DbSearchResultRow>	A list of rows from the database lookup.
fieldInfoList	List<DbSearchFieldInfo>	A list of search field information describing the columns used in the database lookup.

8.1.8 DBSearchResultRow

The DbSearchResultRow class represents one row result returned from a database lookup.

Property	Type	Description
results	List<String>	A list of string values associated with one search result. The values in the list will be in the same order in which the return fields are defined.

8.1.9 DBSearchFieldInfo

The DbSearchFieldInfo class represents the field information describing the results of a database lookup.

Property	Type	Description
captureIndexDefID	String	The metadata field ID.
dbColumnName	String	The name of the database column.
dbColumnType	Integer	The type of the database column.
captureFieldType	Integer	The data type of the metadata field.

8.1.10 DocumentEntity

The DocumentEntity class represents a document within a batch. A document consists of a collection of DocumentPageEntity references which refer to BatchItemEntity references.

Property	Type	Description
documentID	String	A value that uniquely identifies the document.
documentTitle	String	The document title.
documentNumber	Integer	The document's position within the batch.
batchEntity	BatchEntity	A reference to the batch to which the document belongs.
documentPages	List<DocumentPageEntity>	A list of document page entity references that make up the document.
documentType	DocumentTypeEntity	A reference to the documentType associated with the document.
indexes	List<IndexValue>	A list of index values for the document.
documentState	Integer	The current state of the document which will be one of the following values: 1 (READY) – Document is ready to be committed. 2 (ON HOLD) – Document will not be committed by the Commit Processor.
lastModifiedDateTime	Date	The date and time the document was last modified.
lastModifiedUserID	String	The ID of the user that last modified the document.

8.1.11 DocumentPageEntity

The DocumentPageEntity class represents a page within a document. It refers to a BatchItemEntity within a batch and contains a page number that represents the page's position within the parent document.

Property	Type	Description
docPageID	String	A value that uniquely identifies the document page.
batchItemEntity	BatchItemEntity	A reference to the BatchItemEntity associated with the document page.
documentEntity	DocumentEntity	A reference to the DocumentEntity to which the page belongs.
pageNumber	int	The position of the page within a document.

8.1.12 DocumentTypeEntity

The DocumentTypeEntity class defines a document profile within a Capture Workspace. A DocumentTypeEntity consists of a name, description, and list of index definition fields that pertain to the document profile.

Property	Type	Description
docTypeID	String	The unique identifier of the document profile.
docTypeName	String	The name of the document profile.
description	String	The description of the document type.
workspaceEntity	CaptureWorkspaceEntity	The parent workspace to which the document profile belongs.
fields	List<IndexDefinitionEntity>	A list of IndexFieldDefinitionEntity object references that are associated with the document profile.

8.1.13 IndexDefinitionEntity

The IndexDefinitionEntity represents an index definition defined in a workspace. An index definition defines a metadata field that can be used for input.

Property	Type	Description
indexFieldID	String	The unique identifier of the index definition.
fieldName	String	The name of the field.
workspaceEntity	CaptureWorkspaceEntity	A reference to the parent workspace where the field is defined.
dataType	Integer	The data type of the field. 0 – NUMERIC 1 – ALPHA NUMERIC 3 – DATE 4 – FLOAT
maxLength	Integer	The maximum number of characters the field will hold.
minValue	Float	The minimum value allowed.
maxValue	Float	The maximum value allowed.
required	Boolean	Set to True, if the field is required to have a value at commit time; set to False if it is not. The default value is False.
defaultValue	String	A default value for the field.
inputMask	String	The input mask defined for the field.
displayFormat	String	The field's display format.
locked	Boolean	Indicates if the field is locked for input.
autoPopulate	Integer	Includes the following: 0 – None 1 – Default Value 2 – Scan Date 3 – Current Date 4 – Batch Name 5 – User ID 6 – Host Name 7 – Profile Name 8 – Batch Status 9 – Batch Priority 10 – Document Type
validationExpression	String	The regular expression string used to validate the field value.

8.1.14 IndexValue

The IndexValue class represents the value of a metadata field in a document. It contains a display value that is presented to the user as well as a fieldValue which will be used at commit time.

Property	Type	Description
fieldID	String	The unique identifier of the IndexDefinitionEntity that is associated with the index value.
fieldValue	String	The value of the field that will be used when the document is committed.
displayValue	String	A value that is presented to the user. This value will not be used at commit time.