About ABBYY FlexiCapture Application Server Web Services API

The Web Services API of the Application Server enables an external system to connect to the Application Server of ABBYY FlexiCapture 10 using the SOAP protocol over HTTP, create a document processing task, start the task, and get the results. The Web Services API allows you to create your own applications that use ABBYY FlexiCapture 10 as a service that analyzes document images and exports the results.

The Application Server Web Services API can be used to control a pre-configured workflow. Before you commence, you need to create projects on the Project Setup Station and specify the Document Definitions, batch types, image processing settings, etc. to be used.

The control is exercised by calling Web Services API methods. Standard and specially designed data types are used as parameters and returned values.

The formal description of the service (WSDL) is available here:

http://appServer/FlexiCapture10/Server/WebServices.dll?Handler=Version2WSDL, where appServer is the name of the Application Server installed.

Alternatively, you can open the document in your Web browser.


What's New

New methods for working with the following objects:

  • Tasks
  • Sessions
  • Pages

Some of the new methods overlap with the functionality of the methods implemented in the previous version of the API. However, the old methods have been retained to ensure compatibility of the existing applications (see the Migrating from earlier versions of the Web Services API section).

Additionally, methods for working with the following objects have been added:

  • Users
  • Licensing tickets
  • Named parameters

Finally, a new way for working with files has been added: now you can use POST requests.


Migrating from earlier versions of Web Services API

Applications that use previous versions of the Web Services API can be used with the new version. You will need to do the following

  1. In the source code of the application, change the of the URL Web service to the following:
    http://<server name>/flexicapture10/server/webservices.dll?Handler=Version2WSDL
  2. Update WebReference.
  3. Compile your project.


Using the Web Services API of the ABBYY FlexiCapture 10 Application Server

The standard usage scenario includes the following processing stages:

  • Scanning the documents and sending them for processing
  • Verifying the scanned documents
  • Rescanning the documents
  • Getting the processing results

It is recommended to use Web Services API to process documents at User Type (ID=2000) stages. These stages can be created on the Workflow tab of the Project Properties dialog box in the Advanced mode. When connecting, the "External User" (ID=12) role and the "External Station" (ID=10) station type must be used.

For tasks at these stage, both pre- and post-processing are always executed, irrespective of the stage type specified when calling the CloseTaskEx method (for other stages, post-processing is executed only if the stage of the required type is specified, e.g. "Verification Postprocessing"). During pre-processing, XML-files with description of documents of the task are created. It is necessary to upload these documents by the using a POST request, make necessary changes and save them on the server, then close the task by the CloseTaskEx method. During post-processing, information from XML-files that describes the documents will be saved in ABBYY FlexiCapture 10 database.


Scanning Documents

To scan documents:

  • Open a session
  • Open a project
  • Create a new batch
  • Open the newly created batch
  • Add pages/documents into the batch
  • Close the batch
  • Start processing the batch
  • Close the project;
  • Close the session


Verifying the Documents

To verify the documents:

  • Open a session
  • Open a project
  • Request a task
  • Open the batch specified in the task
  • Request the list of documents in the task
  • Requests the files from the server which are attached either to the task (data verification stage) or to the document (verification stage)
  • If required, modify the files of the task and save them on the server
  • Return the task to the server
  • Close the project
  • Close the session


Rescanning the Documents

To verify the documents:

  • Open a session
  • Open a project
  • Request a task
  • Request the task information
  • Open the batch specified in the task
  • Request the list of documents in the task
  • Replace images of pages or add documents/pages/images
  • Return the task to the server in the Scanning stage.
  • Close the project
  • Close the session


Getting the Processing Results

To get the processing results:

  • Open a session
  • Open a project
  • Get the list of files with the document export results
  • Get the files with the document export results
  • Close the project
  • Close the session


References

This section contains the following information about the Web Services API: descriptions of the available methods, the data types used and working with files.


API Methods

API methods are used to control the Application Server.

Note: Some methods extend the functionality of methods available in the previous version of the API. However, the old methods have been retained to ensure compatibility with existing applications.

<
Sessions | Projects
Batch Types | Batches
Tasks | Documents
Pages | Licensing tickets
Users | Files
Attachments | Log
Templates | Other

Sessions

IsSessionExists | Checks if a session exists
CloseSession | Closes a session
OpenSession | Opens a session
OpenSessionEx | Opens a session and specifies the role types and station

Projects

CloseProject | Closes a project
GetProjects | Gets the list of batches loaded onto the Application Server
GetProjectsForUser | Gets the set of records listing the stages available to the user
OpenProject | Opens a project

Batch Types

GetBatchType | Gets information about a batch type
GetBatchTypes | Gets the list of batch types
GetProcessingStages | Gets the list of processing stages
GetProcessingStagesExt | Gets extended information about processing stages
HasRightsToBatchType | Checks if the user role has access rights to a certain batch type

Batches

AddNewBatch | Adds a new batch
AddNewImage | Adds an image into a batch
CloseBatch | Closes (unlocks) a batch
DeleteBatch | Deletes a batch
GetBatch | Gets information about a batch
GetBatches | Gets the list of batches in a project
GetBatchPercentCompleted | Gets information about the processing of a batch
GetDetailedBatch | Gets extended information about a batch
GetDetailedBatches | Gets extended information about batches
OpenBatch | Opens (locks) a batch
ProcessBatch | Starts processing a batch

Tasks

CancelTask | Cancels a task
CloseTask | Closes a task
CloseTaskEx | Opens a task and sends it to a processing stage
CreateTask | Creates a task
GetAvailableTasks | Get the list of available tasks for the selected stage type
GetAvailableTasksByStageId | Get the list of available tasks for the specified processing stages
GetAvailableQueues | Gets the set of records listing the processing stages available to the user
GetCurrentTask | Gets the ID of the task obtained with the GetTask method and not yet processed
GetPostponedTasks | Gets the list of postponed tasks
GetTask | Select the task with the highest priority at the processing stages of the selected tupe and open it for processing
GetTaskByStageId | Select the task with the highest priority at the specified processing stages and open it for processing
GetTaskDocuments | Gets the list of documents in a task
GetTaskInfo | Gets information about a task
GetTaskInfoExt | Gets extended information about a task
OpenTask | Opens a task
PostponeTask | Postpones a task
SendTask | Sends the task to the specified processing stage
SendTaskToException | Sends a task to Exceptions

Documents

AddNewDocument | Adds a new document
AddNewDocumentEx | Adds a new document and includes additional information
AddNewEmptyDocument | Adds an empty document (i.e. a document without images)
AddNewImage | Adds an image into a batch
DeleteDocument | Deletes a document
GetDocument | Gets information about a document
GetDocumentResultList | Gets the list of files into which the document processing results were exported
GetDocuments | Gets the list of documents in a batch
LoadDocumentResult | Gets the file into which the document processing results were exported
SetDocumetnProperties | Specifies registration parameters for a document

Pages

AddNewPage | Adds a page image to a document
AddNewPageEx | Adds a page image to a document and includes a description
DeletePage | Deletes a page from a document
ReplacePageImage | Replaces a page image

Licensing tickets

GetNewTicket | Gets a new licensing ticket
ReleaseTicket | Releases a licensing ticket
UpdateTicket | Updates the status of a licensing ticket

Users

AddUserIfNotExist | Gets the ID of the current user and creates a database record if required
FindUser | Gets the user ID and user name
GetAvailableQueues | Gets the set of records listing the processing stages available to the user
GetProjectsForUser | Gets the set of records listing the stages available to the user
GetUser | Gets information about the user based on the user ID
GetUsers | Gets the lust of users
GetUserStatistics | Gets a set of records listing the the number of batches, documents and pages whose state changed to "processed" for a given period of time
HasRightsToBatchType | Checks if the user role has access rights to a certain batch type

Files

GetCustomFileNames | Gets a list of user files stored on the Application Server
LoadCustomFile | Loads a user file from the Application Server
RemoveCustomFile | Deletes a user file from the Application Server
SaveCustomFile | Saves a user file on the Application Server

Attachments

GetAttachmentNames | Gets a list of attachments on the Application Server
LoadAttachment | Loads an attachment from the Application Server
RemoveAttachment | Deletes an attachment from the Application Server
SaveAttachment | Saves an attachment on the Application Server

Templates

GetTemplates | Get the set of Document Definitions of the project
GetBatchTypeTemplates | Returns the set of identifiers for Document Definitions attached to the batch type

Log

WriteToLog Writes information about events into the Application Server's log

Other

GetSettingValue | Get the named parameter from the database
SetSettingValue | Save the named parameter in the database


Sessions

The API methods allow you to perform the following operations on connection sessions:

CloseSession | Close a connection session
IsSessionExists | Check that the connection session exists
OpenSession | Open a connection session
OpenSessionEx | Open a connection session and specify the types of role and station


CloseSession

What is does

Closes a previously opened connection to the Application Server.

Definition

void CloseSession(int sessionId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server to be closed
Returned value

None.


IsSessionExists

What it does

Checks if a session with the specified ID exists.

Definition

bool IsSessionExists(int sessionId);

Parameters
Name | Type | Description
sessionID | int | The ID of the session
Returned value
Type Description
bool A flag which shows whether a session with the specified ID exists or not:
  • True - the session exists
  • False - the session does not exist


OpenSession

What it does

Opens a connection to the Application Server.

Note: This method has been retained for compatibility with the previous versions of the Web Services API. Use the OpenSessionEx method instead.

Definition

int OpenSession();

Parameters

None.

Returned value
Type | Description
int | The ID of the opened connection


OpenSessionEx

What it does

Opens a connection to the Application Server.

Note: This method has been developed to replace the OpenSession method available in the previous versions of the Web Services API.

Definition

int OpenSession Ex(int roleType, int stationType);

Parameters
Name | Type | Description
roleType | int | The type of role to be used for the connection. See Role for possible values.
stationType | int | The type of connecting station. See WorkstationType for possible values.
Returned value
Type | Description
int | The ID of the currently open connection


Projects

The API methods allow you to perform the following operations on projects:

CloseProject | Close a project
GetProjects | Get the list of batches loaded onto the Application Server
GetProjectsForUser | Get the set of records listing the stages available to the user
OpenProject | Open a project


CloseProject

What it does

Closes a previously opened project.

Definition

void CloseProject(int sessionId, int projectId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
projectId | int | The ID of the project to be closed
Returned value

None.


GetProjects

What it does

Gets information about all the projects on the Application Server.

Definition

Project[] GetProjects();

Parameters

None.

Returned value
Type | Description
Project[] | A set of records, each containing information about one of the projects


OpenProject

What it does

Opens a project for further work.

Note: An opened project cannot be deleted. To delete the project, first close it using the CloseProject method.

Definition

int OpenProject(int sessionId, string projectNameOrGuid);

Parameters
Name | Type | Description
sessionId | int | The IDof the connection to the Application Server
projectNameOrGuid | string | The name or GUID of the project to be opened
Returned value
Type | Description
int | The ID of the opened project


Batch Types

The API methods allow you to perform the following operations on batch types:

GetBatchType | Gets information about a batch type
GetBatchTypes | Gets the list of batch types
GetProcessingStages | Gets the list of processing stages
GetProcessingStagesExt | Gets extended information about processing stages.
HasRightsToBatchType | Check if the user under this role may access this batch type


GetBatchType

What it does

Gets information about a batch type.

Definition

BatchType GetBatchType(int batchTypeId);

Parameters
Name | Type | Description
batchTypeId | int | The ID of the batch type about which information is to be retrieved
Returned value
Type | Description
BatchType | Information about the batch type


GetBatchTypes

What it does

Gets information about all the batch types within a project.

Definition

BatchType [] GetBatchTypes(int projectId);

Parameters
Name | Type | Description
projectId | int | The ID of the project that contains the batch types for which information is to be retrieved
Returned value
Type | Description
BatchType [] | A set of records, each containing information about one of the batch types contained in the project


GetProcessingStages

What it does

Gets information about processing stages.

Definition

ProcessingStage[] GetProcessingStages(int projectId, int batchTypeId, int stageType, string Name);

Parameters
Name | Type | Description
projectId | int | The ID of the project
batchType | int | The ID of the batch type. The following values are also possible: 0 – default batch type -1 – all the batch types
stageType | int | The ID of the stage type. See ProcessingStage for possible values. Use '-1' value to get processing stages of all types.
Name | string | The name of the processing stage. Use an empty string ("") to get all the processing stages.
Returned value
Type | Description
ProcessingStage[] | A set of records, each containing information about a processing stages


GetProcessingStagesExt

What it does

Gets extended information about processing stages.

Definition

ProcessingStagesExt[] GetProcessingStagesExt(int projectId, int batchTypeId, int stageType, string Name);

Parameters
Name | Type | Description
projectId | int | The ID of the project
batchType | int | The ID of the batch type. The following values are also possible: 0 – default batch type -1 – all the batch types
stageType | int | The ID of the stage type. See ProcessingStage for possible values. Use '-1' value to get processing stages of all types.
Name | string | The name of the processing stage. Use an empty string ("") to get all the processing stages.
Returned value
Type | Description
ProcessingStagesExt[] | A set of records, each containing extended information about a processing stages


HasRightsToBatchType

What it does

Checks if the specified user role has access rights to certain batch types.

Definition

bool HasRightsToBatchType(int sessionId, int projectId, int batchTypeId, int roleType);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
projectId | int | Project ID
batchTypeId | int | Batch type ID. 0 - "default" batch type, -1 - checks for access rights to at least one batch type.
roleType | int | User role. See Role for possible values. The roleType value can be viewed in the Role table of the database.
Returned value
Type Description
bool Availability of access rights. Possible values:
  • True - has access rights
  • False - has no access rights


Batches

The API methods allow you to perform the following operations on batches:

AddNewBatch | Add a new batch
AddNewImage | Add an image to a batch
CloseBatch | Close (unlock) a batch
DeleteBatch | Delete a batch
GetBatch | Get information about a batch
GetBatches | Get the list of batches in a project
GetBatchPercentCompleted | Get information about the processing of a batch
GetBatchType | Get information about a batch type
GetBatchTypes | Get the list of batch types
GetDetailedBatch | Get extended information about a batch
GetDetailedBatches | Get extended information about batches
OpenBatch | Open (lock) a batch
ProcessBatch | Start the processing of a batch


AddNewBatch

What it does

Adds a new batch to a project.

Definition

int AddNewBatch(int sessionId, int projectId,  Batch batch);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
projectId | int | The ID of the project to which a batch is to be added
batch | Batch | The parameters of the batch to be added
Returned value
Type | Description
int | The ID of the created batch


AddNewImage

What it does

Adds an image (or a multi-page image) to a batch.

Important! The added images will become accessible only after they are pre-processed. Use the ProcessBatch method to initiate batch processing after you have added the images or use the CloseTaskEx method to close the task and to send it in the Import stage if the images were added into the documents of a task that was opened with the OpenTask method.

Definition

void AddNewImage(int sessionId, int batchId,  File file);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch to which an image is to be added
file | File | The file that contains an image
Returned value

None.


CloseBatch

What it does

Closes a batch and unlocks it for deletion.

Definition

void CloseBatch(int sessionId, int batchId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch to be unlocked for deletion
Returned value

None.


DeleteBatch

What it does

Deletes a batch.

Important! Deleting a batch deleted the exported documents contained in that batch.

Definition

bool DeleteBatch(int sessionId, int batchId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch to be deleted
Returned value
Type Description
bool A flag that shows whether the operation has been successfully completed:
  • True - the batch was successfully deleted
  • False - the batch was not deleted


GetBatch

What it does

Gets information about a batch.

Definition

Batch GetBatch(int batchId);

Parameters
Name | Type | Description
batchId | int | The ID of the batch about which information is to be retrieved
Returned value
Type | Description
Batch | Information about the batch


GetBatches

What it does

Gets information about all the batches in a project.

Definition

Batch [] GetBatches(int projectId);

Parameters
Name | Type | Description
projectId | int | The ID of the project that contains the batches about which information is to be retrieved
Returned value
Type | Description
Batch [] | A set of records, each containing information about one of the batches in the project. The returned set does not include batches created in the Web Capture Station.


GetBatchPercentCompleted

What it does

Gets information about the progress of batch processing.

Definition

int GetBatchPercentCompleted(int batchId);

Parameters
Name | Type | Description
batchId | int | The ID of the batch for which processing information is to be retrieved
Returned value
Type | Description
int | The percentage of the task completed (100% means the task is completed)


GetDetailedBatch

What it does

Gets extended information about a batch.

Definition

DetailedBatch GetDetailedBatch(int batchId);

Parameters
Name | Type | Description
batchId | int | The ID of the batch about which information is to be retrieved
Returned value
Type | Description
DetailedBatch | Information about the batch


GetDetailedBatches

What it does

Gets extended information about batches.

Definition

DetailedBatch GetDetailedBatches(int batchId, int sessionId, bool onlyPrivateBatches);

Parameters
Name | Type | Description
batchId | int | The ID of the batch about which information is to be retrieved
sessionId | int | The ID of the connection to the Application Server
onlyPrivateBatches bool A flag which shows whether batches created in the Web Capture Station are returned or not:
  • True - all batches created in the Web Capture Station are returned. In the Verification stage, these batches are availabe only to the operator who created them in the Scanning stage;
  • False - batched created in all stations but the Web Capture Station are returned.
Returned value
Type | Description
DetailedBatch[] | Extended information about batches


OpenBatch

What it does

Opens a batch (locks it to prevent deletion by other connections). To delete a batch, close it first using the CloseBatch method.

Definition

bool OpenBatch(int sessionId, int batchId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch being opened
Returned value
Type Description
bool A flag that shows whether the operation has been successfully completed:
  • True - the batch was successfully opened
  • False - the batch was not opened


ProcessBatch

What it does

Starts the processing of a batch. The batch is sent to the Import processing stage.

Definition

void ProcessBatch(int sessionId, int batchId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch to be processed
Returned value

None.


Tasks

The API methods allow you to perform the following operations on tasks:

CancelTask | Cancel a task
CloseTask | Close a task
CloseTaskEx | Close a task and send it to a processing stage
CreateTask | Create a task from the set of documents of one batch
GetAvailableTasks | Get the list of available tasks for the selected stage type
GetAvailableTasksByStageId | Get the list of available tasks for the specified processing stages
GetAvailableQueues | Get the set of records listing the processing stages available to the user
GetCurrentTask | Get the ID of the task obtained with the GetTask method and not yet processed
GetPostponedTasks | Get the list of postponed tasks
GetTask | Select the task with the highest priority at the processing stages of the selected type and open it for processing
GetTaskByStageId | Select the task with the highest priority at the specified processing stages and open it for processing
GetTaskDocuments | Get the list of documents in a task
GetTaskInfo | Get information about a task
GetTaskInfoExt | Get extended information about a task
OpenTask | Open a task
PostponeTask | Postpone a task
SendTask | Send a task to the specified processing stage
SendTaskToException | Send a task to Exceptions

Important! You can use the Web Services API to access only tasks at those stages for which Web stations are allowed in the project (Project>Project Properties…, Workflow tab).


CancelTask

What it does

Cancels the processing of a task.

Definition

void CancelTask(int sessionId, int taskId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
taskId | int | The ID of the task to be canceled
Returned value

None.


CloseTask

What it does

Closes a task and makes it available for further operations.

Important! If the Web Services API is used to route documents, other routing methods such as enter conditions or scripts are not applied. Exceptions is the stages of the User type (ID=2000) - for them both pre- and post-processing are always executed and workflow works properly.

Note: This method has been retained for compatibility with the previous versions of the Web Services API. Use the CloseTaskEx method instead.

Definition

void CloseTask(int sessionId, int taskId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
taskId | int | The ID of the task to be closed
Returned value

None.


CloseTaskEx

What it does

Returns the task for further processing.

Important! If the Web Services API is used to route documents, other routing methods such as enter conditions or scripts are not applied. Exceptions is the stages of the User type (ID=2000) - for them both pre- and post-processing are always executed and workflow works properly.

Note: This method has been developed to replace the CloseTask method available in the previous versions of the Web Services API.

Definition

void CloseTaskEx(int sessionId, int taskId, int stageType);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
taskId | int | The ID of the task to be returned for further processing
stageType | int | The ID of the stage type to which the task is to be sent. See ProcessingStage for possible values. Note: To return the task for further processing, the stageType value must be 410 or 510. Note: At the Data Verification stage, the changes that have been made are saved in the task. To transfer them into the documents, you must upload xml file containing task data using POST request and send the task to the Data Verification Postprocessing stage when closing the task. Web Data Verification station must also be enabled on the Workflow tab of the Project Properties dialog to allow working with the Data Verification stage using Web Services API.
Returned value

None.


CreateTask

What it does

Creates a task from the set of documents of one batch.

Definition

int GetTask(int sessionId, int stageExternalId, int priority, string comment, int UserId, int[] docIds, bool setAsCurrentTask);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
stageExternalId | int | The ID of the stage the task will be placed in
priority | int | The priority of the task. See ProcessingPriority for possible values.
comment | string | A text comment to the task
userId | int | The ID of the user the task will be assigned to. If the value is "0" the task can be processed by any user.
docIds | int[] | The IDs of the batch documents
setAsCurrentTask bool The flag that shows whether the task will added to the stage in the "in process" state or will be placed in a queue. Possible values:
  • True - the task will be in the "in process" state;
  • False - the task will be placed in a queue.
Returned value
Type | Description
int | Task ID


GetAvailableTasks

What it does

Gets the list of tasks available at the processing stage of the specified type.

Note: If stage allows web-stations, only preprocessed tasks will be added to the list.

Definition

TaskList GetAvailableTasks(int sessionId, int projectId, int processingStage);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
projectId | int | The ID of the project for which the list of tasks is to be retrieved
processingStage | int | The ID of the stage type. Possible values: see ProcessingStage.
Returned value
Type | Description
TaskList | List of available tasks


GetAvailableTasksByStageId

What it does

Gets the list of tasks available at the specified processing stages.

Note: If stage allows web-stations, only preprocessed tasks will be added to the list.

Definition

TaskList GetAvailableTasksByStageId(int sessionId, int projectId, int[] stageIds);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
projectId | int | The ID of the project for which the list of tasks is to be retrieved
stageIds | int[] | The IDs of the stages to get task from
Returned value
Type | Description
TaskList | List of available tasks


GetCurrentTask

What it does

Returns the ID of the task obtained with the GetTask method which has not been closed.

Definition

int GetCurrentTask (int sessionId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
Returned value
Type | Description
int | Task ID


GetPostponedTasks

What it does

Gets the list of postponed tasks at the specified processing stage.

Definition

TaskList GetPostponedTasks(int sessionId, int projectId, int processingStage);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
projectId | int | The ID of the project for which the list of tasks is to be retrieved
processingStage | int | The ID of the stage. Possible values: see ProcessingStage.
Returned value
Type | Description
TaskList | List of available tasks


GetTask

What it does

Selects the task with the highest priority and opens it for processing. The selected task is locked (i.e. cannot be opened by other users).

Important! A task must be opened before any actions on the task can be performed.

Definition

int GetTask(int sessionId, int projectId, int stageType, bool onlyPreprocessedTask);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
projectId | int | Project ID
stageType | int | The ID of the stage type. See ProcessingStage for possible values.
onlyPreprocessedTask bool The flag which determines from which tasks to select. Possible values:
  • True - select only pre-processed tasks;
  • False - select from all tasks.
Returned value
Type | Description
int | Task ID


GetTaskByStageId

What it does

Selects the task with the highest priority and opens it for processing. The selected task is locked (i.e. cannot be opened by other users).

Important! A task must be opened before any actions on the task can be performed.

Definition

int GetTaskByStageId(int sessionId, int projectId, int[] stageIds, bool onlyPreprocessedTask);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
projectId | int | Project ID
stageIds | int[] | The IDs of the stages to get task from
onlyPreprocessedTask bool The flag which determines from which tasks to select. Possible values:
  • True - select only pre-processed tasks;
  • False - select from all tasks.
Returned value
Type | Description
int | Task ID


GetTaskDocuments

What it does

Gets information about all the documents in a task.

Definition

TaskDocumentList GetTaskDocuments(int taskId);

Parameters
Name | Type | Description
taskId | int | The ID of the task for which information is to be retrieved
Returned value
Type | Description
TaskDocumentList | The list of documents in a task


GetTaskInfo

What it does

Gets information about a task.

Definition

Task GetTaskInfo(int taskId);

Parameters
Name | Type | Description
taskId | int | The ID of the task for which information is to be retrieved
Returned value
Type | Description
Task | Information about the task


GetTaskInfoExt

What it does

Gets extended information about a task.

Definition

TaskExt GetTaskInfoExt(int taskId);

Parameters
Name | Type | Description
taskId | int | The ID of the task for which information is to be retrieved
Returned value
Type | Description
TaskExt | Extended information about the task


OpenTask

What it does

Opens a task for further operations on it. The task becomes locked (i.e. other users cannot open it).

Important! You must open a task before you can perform any operations on it.

Definition

bool OpenTask(int sessionId, int taskId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
taskId | int | The ID of the task to be opened
Returned value
Type Description
bool A flag that shows whether the operation was successful or not:
  • True - the task was successfully opened
  • False - the task failed to open


PostponeTask

What it does

Postpones a task to be processed at a later time.

Definition

void PostponeTask(int sessionId, int taskId, string comment);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
taskId | int | The ID of the task to be postponed
comment | string | A comment to the postponed task.
Returned value

None.


SendTask

What it does

Sends the entire task to the specified processing stage.

Definition

void SendTask(int sessionId, int taskId, int stageId, string comment);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
taskId | int | The ID of the task to be sent to the Exceptions stage
stageId | int | The ID of the stage to which the task must be sent
comment | string | The text of the comment to the task.
Returned value

None.


SendTaskToException

What it does

Sends a task to the Exceptions stage.

Definition

void SendTaskToException(int sessionId, int taskId, string comment, bool needPostprocessing));

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
taskId | int | The ID of the task to be sent to the Exceptions stage
comment | string | A comment to the task.
needPostprocessing bool The flag which shows if post-processing is required. Possible values:
  • True - post-processing required
  • False - no post-processing required
Returned value

None.


Documents

The API methods allow you to perform the following operations on documents:

AddNewDocument | Add a new document
AddNewDocumentEx | Add a new document and specify additional information
AddNewEmptyDocument | Add an empty documents (i.e. a document without an image)
AddNewImage | Adds an image into a batch
DeleteDocument | Delete a document
GetDocument | Get information about a document
GetDocumentResultList | Get the list of files into which the document processing results were exported
GetDocuments | Get the list of documents in a batch
LoadDocumentResult | Get the file into which the document processing results were exported
SetDocumetnProperties | Specify registration parameters for a document


AddNewDocument

What it does

Adds a new document from an image file into a batch.

Important! The added documents will become accessible only after the images are pre-processed. Use the ProcessBatch method to initiate batch processing after you have added the documents.

Note: This method has been retained for compatibility with the previous versions of the Web Services API. Use the AddNewDocumentEx method instead.

Definition

int AddNewDocument(int sessionId, int batchId,  File file);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch into which a document is to be added
file | File | The file that contains the document image
Returned value
Type | Description
int | The ID of the created document


AddNewDocumentEx

What it does

Adds a new document from an image file into a batch.

Important! The added documents will become accessible only after the images are pre-processed. Use the ProcessBatch method to initiate image pre-processing after you have added the documents.

Note: This method has been developed to replace the AddNewDocument method available in the previous version of the Web Services API.

Definition

int AddNewDocumentEx(int sessionId, int batchId, DocumentEx document, File file, bool excludeFromAutomaticAssembling);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch into which a document is to be added
document | DocumentEx | A description of the document that is being created
file | File | The file that contains the document image. To create an empty document, leave the file parameter empty (file.Name = "", file.Bytes = new bytes [0]).
excludeFromAutomaticAssembling bool A flag that shows whether the document is excluded from document assembly or not:
  • True - the document has already been assembled and is not included in document assembly;
  • False - the document is included into document assembly.

Note: You can also use a POST request to add document image. For this, create a document with an empty file by this method (file.Name = "FileName", file.Bytes = new bytes [0]). Then execute a POST request with the following parameters:

Action = Save

objectType = 0

objectId = documentId, where documentId – document ID returned by the AddNewDocumentEx method

version = 0

streamName = "FileName", where FileName is a name of the file specified when calling the AddNewDocumentEx method

Returned value
Type | Description
int | The ID of the created document


AddNewEmptyDocument

What it does

Adds an empty document into a batch. You can then attach pages to this document using the AddNewPageEx method.

Note: This method has been retained for compatibility with the previous versions of the API. To create an empty document, use the AddNewDocumentEx method, leaving the file parameter empty (file.Name = "", file.Bytes = new bytes [0]).

Definition

int AddNewEmptyDocument(int sessionId, int batchId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch into which a document is to be added
Returned value
Type | Description
int | The ID of the created empty document


DeleteDocument

What it does

Deletes a document.

Important! The document export results will be deleted together with the document.

Definition

bool DeleteDocument(int sessionId, int batchId, int documentId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch that contains the document to be deleted
documentId | int | The ID of the document to be deleted
Returned value
Type Description
bool A flag which show whether the operation was successful or not:
  • True - the document was successfully deleted;
  • False - the document was not deleted.


GetDocument

What it does

Gets extended information about a document.

Definition

DocumentEx GetDocument(int batchId, int documentId);

Parameters
Name | Type | Description
batchId | int | The ID of the batch that contains the document about which information is to be retrieved
documentId | int | The ID of the document about which information is to be retrieved
Returned value
Type | Description
DocumentEx | Information about the document


GetDocumentResultList

What it does

Gets the list of files into which the document processing results were exported.

Definition

string[] GetDocumentResultsList(int documentId);

Parameters
Name | Type | Description
documentId | int | The ID of the document about which information is to be retrieved
Returned value
Type | Description
string[] | The list of files into which the document processing results were exported


GetDocuments

What it does

Gets information about all the documents of a batch.

Definition

Document [] GetDocuments(int batchId);

Parameters
Name | Type | Description
batchId | int | The ID of the batch that contains the documents for which information is retrieved
Returned value
Type | Description
Document[] | A set of records, each containing information about one of the documents from the batch


LoadDocumentResult

What it does

Gets the files into which the document processing results were exported.

Definition

File LoadDocumentResult(int documentId, string fileName);

Parameters
Name | Type | Description
documentId | int | The ID of the exported document
fileName | string | The name of the file to be retrieved from the server
Returned value
Type | Description
File | The file into which the document processing results were exported


SetDocumentProperties

What it does

Specifies the registration parameters of a document.

Definition

void SetDocumentProperties(int sessionId, int batchId, int documentId, RegistrationProperty [] properties);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch that contains the document
documentId | int | The ID of the document for which registration parameters are to be specified
properties | RegistrationProperty [] | A set of records, each describing one of the registration parameters of the document
Returned value

None.


Pages

The API methods allow you to perform the following operations on pages:

AddNewPage | Add a page image into a document
AddNewPageEx | Add a page image and its description into a document
DeletePage | Delete a page from a document
ReplacePageImage | Replace a page image


AddNewPage

What it does

Adds a page image into a document.

Important! The added images will become accessible only after they are pre-processed. Use the ProcessBatch method to initiate batch processing after you have added the images or use the CloseTaskEx method to close the task and to send it in the Import stage if the images were added into the documents of a task that was opened with the OpenTask method.

Note: This method has been retained for compatibility with the previous versions of the Web Services API. Use the AddNewPageEx method instead.

Definition

int AddNewPage(int sessionId, int documentId,  File file);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
documentId | int | The ID of the document into which a page is to be added
file | File | The file that contains the page image
Returned value
Type | Description
int | The ID of the added page


AddNewPageEx

What it does

Adds a page image from a file into a document.

Important! The added images will become accessible only after they are pre-processed. Use the ProcessBatch method to initiate batch processing after you have added the images or use the CloseTaskEx method to close the task and to send it in the Import stage if the images were added into the documents of a task that was opened with the OpenTask method.

Note: This method has been developed to replace the AddNewPage method available in the previous version of the Web Services API.

Definition

int AddNewPageEx(int sessionId, int batchId, int documentId, PageEx page, File file);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch that contains the document
documentId | int | The ID of the document into which a page is to be added
page | PageEx | A description of the page
file | File | The file that contains the page image

Note: You can also use a POST request to add page image. Add a page without an image by using this method. Then execute a POST request with the following parameters:

Action = Save

objectType = 0

objectId = documentId

version = 0

streamName = "Page pageId", where pageId – page ID returned by the AddNewPageEx method

Returned value
Type | Description
int | The ID of the added page


DeletePage

What it does

Deletes a page from a document

Definition

bool DeletePage(int sessionId, int batchId, int documentId, int pageId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
batchId | int | The ID of the batch that contains the document
documentId | int | The ID of the document from which a page is to be deleted
pageId | int | The ID of the page to be deleted
Returned value
Type Description
bool A flag which shows whether the operation was successful or not:
  • True - the page was successfully deleted;
  • False - the page was not deleted.


ReplacePageImage

What it does

Replaces a page image.

Important! The added images will become accessible only after they are pre-processed. Use the ProcessBatch method to initiate batch processing after you have added the images or use the CloseTaskEx method to close the task and to send it in the Import stage if the images were added into the documents of a task that was opened with the OpenTask method.

Definition

void ReplacePageImage(int sessionId, int documentId, int pageId, File file);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
documentId | int | The ID of the document in which to replace a page image
pageId | int | The ID of the page whose image is to be replaced
file | File | The file of the image

Note: You can also use a POST request to add page image. Call this method and then execute a POST request with the following parameters:

Action = Save

objectType = 0

objectId = documentId

version = 0

streamName = "Page pageId", where pageId – the ID of the page whose image is to be replaced

Returned value

None.


Users

The API methods allow you to perform the following operations on user accounts:

AddUserIfNotExist | Get the ID of the current user and create a database record if required
FindUser | Get the ID of the user with the specified name
GetAvailableQueues | Get the set of records listing the processing stages available to the user
GetProjectsForUser | Get the set of records listing the stages available to the user
GetUser | Get information about the user based on the user ID
GetUsers | Get the list of users
GetUserStatistics | Gets a set of records listing the the number of batches, documents and pages whose state changed to "processed" for a given period of time
HasRightsToBatchType | Check if the specified user role has access rights to a certain batch type


AddUserIfNotExist

What it does

Returns the ID of the current user. If there is no database record for the user, a record is created.

Definition

int AddUserIfNotExist();

Parameters

None.

Returned value
Type | Description
int | User ID


FindUser

What it does

Returns the ID of the user and specifies the user name

Definition

int FindUser(string userLogin);

Parameters
Name | Type | Description
userLogin | string | User name
Returned value
Type | Description
int | User ID


GetAvailableQueues

What it does

Gets a set of records listing the processing stages available to the user.

Definition

Queue [] GetAvailableQueues(int sessionId, int projectId);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
projectId | int | The ID of the project for which to get the list of tasks
Returned value
Type | Description
Queue[] | The set of records listing the processing stages available to the user


GetProjectsForUser

What it does

Gets information about the projects on the Application Server, taking into account the user's access rights.

Definition

Project[] GetProjectsForUser(int userId, int roleType);

Parameters
Name | Type | Description
userId | int | User ID
roleType | int | The ID of the user's role type. See Role for possible values. The roleType value can be viewed in the Role table of the database.
Returned value
Type Description
Project[] A set of records, each of which contains information about one of the projects. The set is created based on the values of the input parameters as follows:
  • userId<>0, roleType<>0 – the projects where this user has access rights to at least one of the batch types for the specified role
  • userId<>0, roleType=0 – the projects where this user has some access rights to at least one of the batch types
  • userId=0, roleType=0 – the list of all projects
  • userId=0, roleType<>0 – empty list


GetUser

What it does

Returns information about the user.

Definition

bool GetUser(int userID, out User user);

Parameters
Name | Type | Description
userId | int | User ID
Returned value
Type | Description
bool The flag which shows if the user has been found or not. Possible values:
  • True - user found
  • False - user not found
User | Information about the user


GetUsers

What it does

Returns the list of users.

Definition

UserList GetUsers();

Parameters

None.

Returned value
Type | Description
UserList | List of users


GetUserStatistics

What it does

Gets a set of records listing the the number of batches, documents and pages whose state changed to "processed" for a given period of time.

Definition

UserStatistics [] GetUserStatistics(int userId, long fromDate, long toDate);

Parameters
Name | Type | Description
userId | int | User ID
fromDate | long | The start date for counting statistics. To convert values, use the following methods (C#): DateTime dtTime; long lTime; ... // conversion from DateTime to long dTime = DateTime.FromFileTime(lTime); ... // conversion from long to DateTime lTime = dTime.ToFileTime();
toDate | long | The end date for counting statistics. To convert values, use the following methods (C#): DateTime dtTime; long lTime; ... // conversion from DateTime to long dTime = DateTime.FromFileTime(lTime); ... // conversion from long to DateTime lTime = dTime.ToFileTime();
Returned value
Type | Description
UserStatistics[] | The set of records listing the number of batches, documents and pages whose state changed to "processed" for a given period of time.


Licensing tickets

The API methods allow you to perform the following operations on licensing tickets:

GetNewTicket | Get a new licensing ticket
ReleaseTicket | Release the ticket
UpdateTicket | Update the status of the ticket


GetNewTicket

What it does

Returns the licesning ticket.

Definition

bool GetNewTicket(int sessionId, int stationType, out TicketInfo ticketInfo);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
stationType | int | The type of the station for which the ticket must be obtained. See WorkstationType for possible values. Note. Use the WT_Verification and the WT_Validation values instead of the WT_RemoteDataVerification and the WT_RemoteVerification ones respectively.
Returned value
Type | Description
bool The flag that shows if the ticket has been obtained. Possible values
  • True - ticket obtained successfully
  • False - failed to obtain the ticket
TicketInfo | Licensing ticket


ReleaseTicket

What it does

Releases the licensing ticket.

Definition

void ReleaseTicket(int sessionID, int ticketID);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
ticketId | int | The ID of the licensing ticket
Returned value

None.


UpdateTicket

What it does

Updates the licensing ticket.

Definition

bool UpdateTicket(int sessionId, int ticketId, out TicketInfo ticketInfo);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
ticketId | int | The ID of the licensing ticket
Returned value
Type | Description
bool The flag which shows if the ticket has been updated or not. Possible values:
  • True - the ticket updated successfully
  • False - failed to update the ticket
TicketInfo | Licensing ticket


Files

The API methods allow you to perform the following operations on files:

GetCustomFileNames | Get the list of user files stored on the Application Server
LoadCustomFile | Load a user file from the Application Server
RemoveCustomFile | Delete a user file from the Application Server
SaveCustomFile | Save a user file on the Application Server


GetCustomFileNames

What it does

Gets a list of user files saved on the Application Server.

Definition

string[] GetCustomFileNames();

Parameters

None.

Returned value
Type | Description
string[] | The list of saved files


LoadCustomFile

What it does

Gets a user file saved on the Application Server.

Definition

File LoadCustomFile(string fileName);

Parameters
Name | Type | Description
fileName | string | The name of the file to be retrieved from the Application Server
Returned value
Type | Description
File | The user file


RemoveCustomFile

What it does

Removes a user file from the Application Server.

Definition

void RemoveCustomFile(int sessionId, string filename);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
filename | string | The name of the file to be removed from the Application Server
Returned value

None.


SaveCustomFile

What it does

Saves a user file on the Application Server.

Definition

void SaveCustomFile(int sessionId, File file);

Parameters
Name | Type | Description
sessionId | int | The ID of the connection to the Application Server
file | File | A user file
Returned value

None.


Attachments

The API methods allow you to perform the following operations on attachments:

GetAttachmentNames | Gets a list of attachments on the Application Server
LoadAttachment | Loads an attachment from the Application Server
RemoveAttachment | Deletes an attachment from the Application Server
SaveAttachment | Saves an attachment on the Application Server


GetAttachmentNames

What it does

Gets a list of attachents of the specified type.

Definition

string[] GetAttachmentNames(int attachmentType, int objectId, int batchId, int projectId);

Parameters
Name | Type | Description
attachmentType int Type of attachment. Possible values
  • 9 - attachment to a document;
  • 10 - attachment to a page;
  • 11 - attachment to a batch.
objectId | int | The ID of the object
batchId | int | The ID of the batch
projectId | int | The ID of the project
Returned value
Тип | Значение
string[] | The list of attachments


LoadAttachment

What it does

Gets attachment as a file.

Definition

File LoadAttachment(int session, int attachmentType, int objectId, int batchId, int projectId, string attachmentName);

Parameters
Name | Type | Description
session | int | The ID of the connection to the Application Server
attachmentType int Type of attachment. Possible values
  • 9 - attachment to a document;
  • 10 - attachment to a page;
  • 11 - attachment to a batch.
objectId | int | The ID of the object
batchId | int | The ID of the batch
projectId | int | The ID of the project
attachmentName | string | Name of attachment to be deleted
Returned value
Type | Value
File | Attachment file


RemoveAttachment

What it does

Removes attachment

Definition

void RemoveAttachment(int session, int attachmentType, int objectId, int batchId, int projectId, string attachmentName);

Parameters
Name | Type | Description
session | int | The ID of the connection to the Application Server
attachmentType int Type of attachment. Possible values
  • 9 - attachment to a document;
  • 10 - attachment to a page;
  • 11 - attachment to a batch.
objectId | int | The ID of the object
batchId | int | The ID of the batch
projectId | int | The ID of the project
attachmentName | string | Name of attachment to be deleted
Returned value

None.


SaveAttachment

What it does

Adds attachment to the specified object.

Definition

void SaveAttachment(int session, int attachmentType, int objectId, int batchId, int projectId, File file);

Parameters
Name | Type | Description
session | int | The ID of the connection to the Application Server
attachmentType int Type of attachment. Possible values
  • 9 - attachment to a document;
  • 10 - attachment to a page;
  • 11 - attachment to a batch.
objectId | int | The ID of the object
batchId | int | The ID of the batch
projectId | int | The ID of the project
attachmentName | string | Name of attachment to be deleted
file | File | Attachment file
Returned value

None.


Templates

The API methods allow you to perform the following operations on connection sessions:

GetTemplates | Get the set of Document Definitions of the project
GetBatchTypeTemplates | Returns the set of identifiers for Document Definitions attached to the batch type


GetTemplates

What it does

Gets information about all the Document Definitions of a project.

Definition

Template[] GetTemplates(int projectId);

Parameters
Name | Type | Description
projectId | int | The ID of the project
Returned value
Type | Description
Template[] | A set of records, each containing information about a document definition


GetBatchTypeTemplates

What it does

Returns the set of identifiers for Document Definitions attached to the batch type. If NULL is returned, it means either that the "Use all Document Definitions" option is enabled in batch type properties or that no Document Definition is selected.

Definition

int[] GetBatchTypeTemplates(int projectId, int batchTypeId);

Parameters
Name | Type | Description
projectId | int | The ID of the project
batchTypeId | int | The ID of the batch type
Returned value
Type | Description
int[] | Document Definitions attached to the batch type


Log

The API methods allow you to perform the following operations on the log:

WriteToLog Writes event data into the log on the Application Server


WriteToLog

What it does

Writes event data in to the log on the Application Server.

Definition

void WriteToLog(long clientTime, LogRecord [] records);

Parameters
Name | Type | Description
clientTime | long | The date and time the method was called on the workstation. Use the following methods to convert the data (C#): DateTime dtTime; long lTime; ... // conversion from DateTime to long dTime = DateTime.FromFileTime(lTime); ... // conversion from long to DateTime lTime = dTime.ToFileTime();
records | LogRecord[] | A set of records, each describing one of the events to be written in the log on the Application Server
Returned value

None.


Other

The API methods also allow you to perform the following:

GetSettingValue | Get the named parameter from the database
SetSettingValue | Save the named parameter to the database


GetSettingValue

What it does

Returns the value of the named parameter which was saved to the database by the SetSettingValue method.

Note: Identically named parameters with different values can be saved for different users/batch types/projects.

Definition

string GetSettingValue(int userId, int projectId, int batchTypeId, string settingName);

Parameters
Name | Type | Description
userId | int | The ID if the user's account
projectId | int | Project ID
batchTypeId | int | Batch type ID
settingName | string | Parameter name
Returned value
Type | Description
string | The value of the named parameter


SetSettingValue

What it does

Saves the named parameter to the database.

Note: Identically named parameters with different values can be saved separately for different users/batch types/projects. If a parameter with the specified name and set of user IDs, batch types, and project type already exists, the method will change its value.

Definition

void SetSettingValue(int userId, int projectId, int batchTypeId, string settingName, string settingValue);

Parameters
Name | Type | Description
userId | int | The ID if the user's account
projectId | int | Project ID
batchTypeId | int | Batch type ID
settingName | string | Parameter name
settingValue | string | Parameter value
Returned value

None.


Data Types

This section describes the data types used by the methods of the API.

Note: Some of the data types are extensions of data types used by the methods of the previous version of the API. However, the old methods and data types have been retained for compatibility.

Enumerators | The list of enumerators used
Batch | Batch
BatchType | The type of the batch
DetailedBatch | Extended information about the batch
Document | Information about the document (retained for compatibility with the previous versions)
DocumentEx | Information about the document
File | File
LogRecord | Record in the log
Page | Information about the page (retained for compatibility with the previous versions)
PageEx | Information about the page
ProcessingStage | Information about the processing stage
ProcessingStagesExt | Extended information about the processing stage
Project | Information about the project on the Application Server
Queue | Information about the document queue at the processing stage
RegistrationProperty | Registration parameter
RegistrationPropertyDef | Description of the registration parameter
Task | Information about the task
TaskDocument | A document of the task
TaskDocumentList | The list of documents in the task
TaskExt | Extended information about the task
TaskList | The list of tasks
TaskPage | A page of the task
Template | Information about the Document Definition
TicketInfo | Licensing ticket
User | Information about the user
UserList | The list of users
UserStatistics | Information about the number of batches, documents and pages processed by the user


Enumerators

This section describes the enumerators used in the Web Services API of the ABBYY FlexiCapture 10 Application Server.

LogRecordType | The types of events to log
ProcessingPriority | Batch, document or task processing priority
ProcessingStage | Processing stage
Role | User's role
WorkstationType | The type of the station


LogRecordType

What it does

Contains the types of events to log.

Fields
Name | Description
1 | Error message
2 | Warning message
3 | Information message


ProcessingPriority

What it does

Contains the list of processing priorities.

Fields
Name | Description
-2 | Lowest
-1 | Low
0 | Normal
1 | High
2 | Highest


ProcessingStage

What it does

Contains the list of predefined types of processing stages.

Fields
Value | Description
100 | Import
150 | Rescanning
200 | Recognition
250 | Unattended Processing
300 | Document Assembly Check
390 | Data Verification Preprocessing
400 | Data Verification
410 | Data Verification Postprocessing
490 | Verification Preprocessing
500 | Verification
510 | Verification Postprocessing
600 | Batch Integrity Check
700 | Export Confirmation
800 | Export
900 | Processed
1000 | Exceptions
-1 | Unknown stage
-2 | Processing the task failed. The next stage is defined in the routing settings.
-3 | The next processing stage
2000 | User Type


Role

What it does

Contains the list of predefined user roles.

Fields
Name | Description
1 | Scanning Operator
2 | Data Verification Operator
3 | Verification Operator
4 | Not Used
5 | Not Used
6 | Senior Verification Operator
7 | Processing Server
8 | Project Settings Editor
9 | Monitoring Operator
10 | Administrator
11 | Processing Station
12 | User station Operator
13 | Web Capture Operator


WorkstationType

What it does

Contains the list of predefined types of workstation.

Fields
Name | Description
1 | Scanning station
2 | Data Verification station
3 | Verification station
4 | Processing server
5 | Project Setup station
6 | Processing station
7 | Remote Data Verification Station
8 | Remote Verification Station
9 | Monitoring console
10 | User station
11 | Web Capture Station
12 | Web Verification Station
13 | Web Data Verification Station
14 | Web Scanning Station
-1 | Unknown


Batch

What it does

The Batch data type stores information about a batch.

Fields

Name | Type | Description
Id | int | The ID of the batch
Name | string | The name of the batch
BatchTypeId | int | The ID of the batch type. 0 corresponds to the "Default" batch type
Priority | int | Batch priority. Possible values: see ProcessingPriority.
Description | string | A description of the batch
Properties | RegistrationProperty[] | The set of registration parameters for the batch
PropertiesCount | int | The number of registration parameters


BatchType

What it does

The BatchType data type stores information about the type of a batch.

Fields

Name | Type | Description
Id | int | The ID of the batch type
Name | string | The name of the batch type
Description | string | A description of the batch type
PropertyDefs | RegistrationPropertyDef[] | The set of registration parameters for the batch type
PropertiyDefsCount | int | The number of registration parameters


DetailedBatch

What it does

The DetailedBatch data type stores extended information about a batch.

Fields

Name | Type | Description
Id | int | The ID of the batch
Name | string | The name of the batch
BatchTypeId | int | The ID of the batch type. 0 corresponds to the "Default" batch type
Priority | int | Batch priority. Possible values: see ProcessingPriority.
Description | string | A description of the batch
Properties | RegistrationProperty[] | The set of registration parameters for the batch
PropertiesCount | int | The number of registration parameters
StageExternalId | int | The ID of the processing stage in which the task is created by the CreateTask method
CreationDate | long | The date and time when the batch was created. To convert values, use the following methods (C#): DateTime dtTime; long lTime; ... // conversion from DateTime to long dTime = DateTime.FromFileTime(lTime); ... // conversion from long to DateTime lTime = dTime.ToFileTime();
DocumentsCount | int | The number of documents in the batch
RecognizedDocumentsCount | int | The number of recognized documents
AssembledDocumentsCount | int | The number of assembled documents
VerifiedDocumentsCount | int | The number of verified documents
ExportedDocumentsCount | int | The number of exported documents
PagesCount | int | The number of pages in the batch
RecognizedSymbolsCount | int | The number of recognized characters
UncertainSymbolsCount | int | The number of uncertain characters
VerificationSymbolsCount | int | The number of verified characters


Document

What it does

The Document data type stores information about a document.

Note: This data type was used in the previous version of the Web Services API. In the current version, the use of DocumentEx is recommended.

Fields

Name | Type | Description
Id | int | The ID of the document
Pages | Page [] | The set of pages in the document
PageCount | int | The number of pages in the document
IsProcessed bool A flag that shows whether the document has been processed or not:
  • True - processed
  • False - not processed
HasProcessingErrors bool A flag that shows whether there were processing errors:
  • True - some processing errors occurred
  • False - there were no errors
HasDocumentErrors bool A flag that shows whether there are errors in the document (e.g. format errors, rules errors, assembly errors):
  • True - there are errors in the document
  • False - there are no errors in the document
ErrorText | string | A description of the document processing errors


DocumentEx

What it does

The DocumentEx data type stores extended information about a document.

Note: This data type has replaced the Document data type which was used in the previous version of the Web Services API.

Fields

Name | Type | Description
Id | int | The ID of the document. Completed automatically by the Application Server.
Pages | Page [] | The set of pages in the document
PageCount | int | The number of pages in the document
IsProcessed bool A flag that shows whether the document has been processed or not:
  • True - processed
  • False - not processed

Completed automatically by the Application Server.

HasProcessingErrors bool A flag that shows whether there were processing errors:
  • True - some processing errors occurred
  • False - there were no errors

Completed automatically by the Application Server.

HasDocumentErrors bool A flag that shows whether there are errors in the document (e.g. format errors, rules errors, assembly errors):
  • True - there are errors in the document
  • False - there are no errors in the document

Completed automatically by the Application Server.

ErrorText | string | A description of the document processing errors. Completed automatically by the Application Server.
ExternalId | string | The external ID of the document. If left empty, the parameter is completed automatically by the Application Server and is the same as Id.
FileVersion | int | The version of the document file on the server
OwnerId | int | The User ID to which the document is assigned
Properties | RegistrationProperty [] | The set of registration parameters for the document
PropertiesCount | int | The number of registration parameters for the document
Priority | int | Document priority. Possible values: see ProcessingPriority


File

What it does

The File data type stores files.

Fields

Name | Type | Description
Name | string | The name of the file
Bytes | System.byte[] | The binary data of the file


LogRecord

What it does

The LogRecord data type stores error records.

Fields

Name | Type | Description
Type | int | The type of the error record. Possible values: see LogRecordType
SessionId | int | The ID of the connection to the Application Server
MachineId | string | The ID of workstation
RoleId | int | The ID of the user's role. Possible values: see Role.
TaskId | int | The ID of the task
ProjectId | int | The ID of the project
BatchId | int | The ID of batch
DocumentId | int | The ID of the document
PageId | int | The ID of the page
Comment | string | A brief description of the event
Details | string | A full description of the event
Time | long | The data and time when the event occurred on the workstation. To convert values, use the following methods (C#): DateTime dtTime; long lTime; ... // conversion from DateTime to long dTime = DateTime.FromFileTime(lTime); ... // conversion from long to DateTime lTime = dTime.ToFileTime();


Page

What it does

The Page data type stores information about a document page.

Note: This data type was used in the previous version of the Web Services API. In the current version, the use of PageEx is recommended.

Fields

Name | Type | Description
Id | int | The ID of the page
SourceFileName | string | The ID of the source image file
SourcePageNumber | string | The number of the image in the source file
ErrorText | string | A description of the page processing errors


PageEx

What it does

The Page Ex data type stores extended information about a document page.

Note: This data type has replaced the Page data type which was used in the previous version of the Web Services API.

Fields

Name | Type | Description
Id | int | The ID of the page. Completed automatically by the Application Server.
SourceFileName | string | The name of the source image file
SourcePageNumber | string | The number of the image in the source file
ErrorText | string | A description of the page processing errors. Completed automatically by the Application Server.
ExternalId | string | The external ID of the page. If left empty, the parameter is completed automatically by the Application Server and is the same as Id.
SourceDetails | string | A description of the source of the page image
PreviousPageId int The ID of the document page after which a new page must be added. You can also use the following values:
  • 0 – add a page at the start of the document
  • -1 – add a page at the end of the document


ProcessingStage

What it does

The ProcessingStage data type stores information about the processing stage.

Fields

Name | Type | Description
Id | int | The ID of the processing stage
ProjectId | int | The ID of the project
BatchTypeId | int | The ID of the batch type
Type | int | The type of the processing stage. See ProcessingStage for possible values.
Name | string | The name of the processing stage


ProcessingStagesExt

What it does

The ProcessingStagesExt data type stores extended information about the processing stage.

Fields

Name | Type | Description
Id | int | The ID of the processing stage
StageExternalId | int | The ID of the processing stage in which the task is created by the CreateTask method
ProjectId | int | The ID of the project
BatchTypeId | int | The ID of the batch type
Type | int | The type of the processing stage. See ProcessingStage for possible values.
Name | string | The name of the processing stage


Project

What it does

The Project data type stores information about a project on the Application Server.

Fields

Name | Type | Description
Id | int | The ID of the project on the Application Server.
Name | string | The name of the project on the Application Server
Guid | string | The unique ID (GUID) of the project
IsTestProject bool A flag which identifies a test project. Possible values:
  • True - this is a test project
  • False - this is a working projects


Queue

What it does

The Queue data type stores information about the document queue at the processing stage.

Fields

Name | Type | Description
Name | string | The name of the processing stage
StageType | int | The type of the processing stage. See ProcessingStage for possible values
TaskCount | int | The number of tasks at the processing stage
UserTaskCount | int | The number of tasks at the processing stage assigned to the given user
PostponedTaskCount | int | The number of tasks at the processing stage postponed by the user
IsEnabled bool A flag which shows if the processing stage is on or off. Possible values:
  • True - the processing stage is enabled
  • False - the processing stage is disabled
Id | int | The ID of the processing stage


RegistrationProperty

What it does

The RegistrationProperty data type stores information about a registration parameter of a batch or document.

Fields

Name | Type | Description
Name | string | The name of the registration parameter
Value | string | The value of the registration parameter


RegistrationPropertyDef

What it does

The RegistrationPropertyDef data type stores information about a registration parameter of a batch type.

Fields

Name | Type | Description
Id | int | The ID of the registration parameter of the batch type. Completed automatically by the Application Server.
Name | string | The name of the registration parameter of the batch type
IsRequired bool A flag that shows whether the registration parameter must be completed or not. Possible values:
  • True - the registration parameter must be completed
  • False - the registration parameter is optional


Task

What it does

The Task data type stores information about tasks.

Note: Besides records of this type, information about tasks is also stored in XML files. An XML file may describe the entire task or its separate files. See the Working with files section for information about the structure of data in files and working with files.

Fields

Name | Type | Description
BatchId | int | The ID of the batch which includes the documents of the task
BatchName | string | The name of the batch the task is associated with
Id | int | The ID of the task
ProjectId | int | The ID of the project to which the task belongs
Priority | int | Task priority. Possible values: see ProcessingStage.
StageType | int | The type of the processing stage at which the task was formed. See ProcessingStage for possible values.
Status System.UInt32 Task status. Possible values:
  • 0 - being created
  • 1 - awaits processing
  • 2 - being processed
  • 3 - processing completed
  • 4 - postponed
Flags int A set of flags which describe the status of the task. The value of a field is a combination of the values of the flags, which include:

TA_HasAttachedDataVerificationXml = 0x200 – an XML file with pre-processing data has been generated for the task

TA_HasAttachedDocumentsXml = 0x1000 – XML files with data have been generated for the task

Note: Only those flags are listed which are useful when working with the tasks and methods of the Web Services API.

CreationTime long Time of creation. To convert values, use the following methods (C#):

DateTime dtTime;

long lTime;

...

// conversion from DateTime to long

dTime = DateTime.FromFileTime(lTime);

...

// conversion from long to DateTime

lTime = dTime.ToFileTime();

CreatorId | int | The ID of the user that created the task
ModificationTime long The time when the task was last modified. Use the following methods (C#) for conversion:

DateTime dtTime;

long lTime;

...

// conversion from DateTime to long

dTime = DateTime.FromFileTime(lTime);

...

// conversion from long to DateTime

lTime = dTime.ToFileTime();

UserId | int | The ID of the user or group to whom the task has been assigned.
Comment | string | Comment to the task


TaskDocument

What it does

The TaskDocument data type stores information about a document contained in a task.

Fields

Name | Type | Description
BatchId | int | The ID of the batch that contains the document
Comment | string | Comment to the document
DocumentId | int | The ID of the document
ExternalId | string | The external ID of the document
Flags int A set of flags that describe the status of the document. The value of a field is a combination of the values of the flags, which include:

BIF_IsAnalyzed = 0x100 – the document has been analyzed

BIF_IsRecognized = 0x200 – the document has been recognized

BIF_IsVerified = 0x400 – the document has been verified

BIF_IsExported = 0x800 – the document has been exported

BIF_HasRuleErrors = 0x10000 – the document contains validation rule errors

BIF_HasRuleWarnings = 0x20000 – the document contains validation rule warnings

Note: Only those flags are listed which are useful when working with the tasks and methods of the Web Services API.

HasAssemblingErrors bool Document assembly errors:
  • True - there are assembly errors in the document
  • False - there are no assembly errors in the document
HasErrors bool Document errors:
  • True - there are errors in the document
  • False - there are no errors in the document
HasWarnings bool Document warnings:
  • True - there are warnings in the document
  • False - there are no warnings in the document
Pages | TaskPage [] | The set of pages in the document
PagesCount | int | The number of pages in the document
Priority | int | The priority of the document. See ProcessingPriority for possible values.
ProcessingStageType | int | The processing stage of the document. See ProcessingStage for possible values.
TemplateName | int | The name of the matched Document Definition
TotalSymbols | int | The total number of characters in the document
UncertainSymbols | int | The number of unreliably recognized characters in the document
VerificationSymbols | int | The number of characters to verify in the document


TaskDocumentList

What it does

The TaskDocumentList data type stores the list of documents in a task.

Fields

Name | Type | Description
Documents | TaskDocument[] | The set of records for the documents in the task
DocumentsCount | int | The number of documents in the task


TaskExt

What it does

The TaskExt data type stores extended information about tasks.

Note: Besides records of this type, information about tasks is also stored in XML files. An XML file may describe the entire task or its separate files. See the Working with files section for information about the structure of data in files and working with files.

Fields

Name | Type | Description
BatchId | int | The ID of the batch which includes the documents of the task
BatchName | string | The name of the batch the task is associated with
Id | int | The ID of the task
ProjectId | int | The ID of the project to which the task belongs
StageExternalId | int | The ID of the processing stage in which the task is created by the CreateTask method
Priority | int | Task priority. Possible values: see ProcessingStage.
StageType | int | The type of the processing stage at which the task was formed. See ProcessingStage for possible values.
Status System.UInt32 Task status. Possible values:
  • 0 - being created
  • 1 - awaits processing
  • 2 - being processed
  • 3 - processing completed
  • 4 - postponed
Flags int A set of flags which describe the status of the task. The value of a field is a combination of the values of the flags, which include:

TA_HasAttachedDataVerificationXml = 0x200 – an XML file with pre-processing data has been generated for the task

TA_HasAttachedDocumentsXml = 0x1000 – XML files with data have been generated for the task

Note: Only those flags are listed which are useful when working with the tasks and methods of the Web Services API.

CreationTime long Time of creation. To convert values, use the following methods (C#):

DateTime dtTime;

long lTime;

...

// conversion from DateTime to long

dTime = DateTime.FromFileTime(lTime);

...

// conversion from long to DateTime

lTime = dTime.ToFileTime();

CreatorId | int | The ID of the user that created the task
ModificationTime long The time when the task was last modified. Use the following methods (C#) for conversion:

DateTime dtTime;

long lTime;

...

// conversion from DateTime to long

dTime = DateTime.FromFileTime(lTime);

...

// conversion from long to DateTime

lTime = dTime.ToFileTime();

UserId | int | The ID of the user or group to whom the task has been assigned.
Comment | string | Comment to the task


TaskList

What it does

The TaskList data type stores the list of tasks.

Fields

Name | Type | Description
Tasks | Task[] | The set of task records
TasksCount | int | The number of tasks in the list


TaskPage

What it does

The TaskPage data type stores information about a page in the task.

Fields

Name | Type | Description
Comment | string | Comment to the page
Flags | int | A set of flags that describe the status of the task. The page flags that make sense in the Web Services API: static const DWORD BIF_IsAnalyzed = 0x100; // page has been analyzed static const DWORD BIF_IsRecognized = 0x200; // page has been recognized
ImageFileName | string | The name of the file that contains the page image
ImageSourceDetails | string | Information about the source of the image
ImageSourcePageNumber | int | The number of the page in the image file
ImageSourceType | int | The type of the image source
PageId | int | The ID of the page
TotalSymbols | int | The total number of characters on the page
UncertainSymbols | int | The number of unreliably recognized characters on the page
VerificationSymbols | int | The number of characters to verify on the page
Version | int | The version number of the page


Template

What it does

The Template data type stores information about a Document Definition.

Fields

Name | Type | Description
Id | int | The ID of the Document Definition.
Version | int | The version of the Document Definition
IsDisabled bool A flag which shows the state of the Document Definition in the Project Setup Station. Possible values:
  • True - the Document Definition is disabled;
  • False - the Document Definition is enabled.


TicketInfo

What it does

The TicketInfo data type stores information about the licensing ticket.

Fields

Name | Type | Description
TicketId | int | The ID of the ticket
StationType | int | The type of the station. See WorkstationType for possible values. Note: Use the WT_Verification and the WT_Validation values instead of the WT_RemoteDataVerification and the WT_RemoteVerification ones respectively.
ExpirationDate | long | The date and time when the license expires. Use the following methods for conversion (C#): DateTime dtTime; long lTime; ... // conversion from DateTime to long dTime = DateTime.FromFileTime(lTime); ... // conversion from long to DateTime lTime = dTime.ToFileTime();
ExpirationPeriod | long | The license term (starts upon license activation). Use the following methods for conversion (C#): DateTime dtTime; long lTime; ... // conversion from DateTime to long dTime = DateTime.FromFileTime(lTime); ... // conversion from long to DateTime lTime = dTime.ToFileTime();
AvailableModules | System.UInt32 | The modules available for the license
IssuedForSessionId | int | The ID of the session during which the ticket was created
Signature | string | The signature of the ticket


User

What it does

The User data type stores information about the user.

Fields

Name | Type | Description
Id | int | The ID of the user
Name | string | The name of the user
FullName | string | The full name of the user


UserList

What it does

The UserList data type stores the list of users.

Fields

Name | Type | Description
Users | User[] | The set of records about the users
UsersCount | int | The number of records about the users


UserStatistics

What it does

The UserStatistics data type stores information about the number of batches, documents and pages processed by the user. Processed batches are the batches that came to the stage in the "processed" state.

Fields

Name | Type | Description
BatchesCount | int | The number of processed batches
DocumentsCount | int | The number of processed documents
PagesCount | int | The number of processed pages


Working with Files

To exchange files with the Application Server, use a POST request.

Types of actions

With the help of POST requests the following actions can be executed:

  • Load files from server (Action = Load)
  • Save files on the server (Action = Save)
  • Append data to the end of the file (Action = Append)
  • Getting a checksum for a file from the server (checksum is calculated using the CRC32 method) (Action = Checksum)

Possible use

  1. Importing images. Loading image files, also by parts and getting the checksum.
  2. Getting original page images at any time of processing.
  3. Working with attachments of batches, documents, pages (upload / download).

Note: despite this possibility, it is recommended to use methods which are specially developed for working with attachments.

  4. Getting XML description of the verification task, modifying this document and saving changes on the server.

Request parameters

Name | Type | Description
Action string Type of action. Possible values:
  • Load – loads a file from the server
  • Save – saves a file on the server
  • Append – appends data to an existing file on the server
  • Checksum – requests a checksum for a file from the server; checksums are calculated using the CRC32 method
AppServerURL | string | The Application Server URL.
sessionId | int | Session ID
projectId | int | Project ID
batchId | int | Batch ID
objectType int Type of object on the server. Possible values
  • 0 – document
  • 1 – page
  • 8 – task description
  • 9 – document ;
  • 10 – attachment to the page;
  • 11 – attachment to the batch.

Note: despite this possibility, it is recommended to use methods which are specially developed for working with attachments.

objectId | int | Object ID (ID of a document, page, or task)
version | int | File version
streamName string The name of the Base64-encoded binary stream when saving a file to the server, or of the UrlEncode-encoded binary stream when loading a file from the server. Possible values

for pages:

  • BlackWhiteImage – the black-and-white image of the page; PNG file
  • ColorImage – the color image of the page; JPG file

for documents:

  • DocumentBody – an XML document that describes document fields. Created at the pre-processing stage for verification purposes. After verification, the changes in the document are processed. Versions are not supported, the version parameter must be set to 0. Save the document processing results to this file.
  • "Page pageId", where pageID is an ID of a page returned by the AddNewPageEx method. This stream name can be used to upload source page image before preprocessing.
  • "FileName", where FileName is a name of a file specified when creating the document by the AddNewDocumentEx method. This stream name cab be used to upload a multi-page file with document page images.

for tasks:

  • Verification – an XML document that describes a verification task. Created at the pre-processing stage for verification purposes. After verification, the changes in the document are processed. Versions are not supported, the version parameter must be set to 1. Save the task processing results to this file.
  • verificationRequest – an XML document with a request to check the validation rules on the server.
requestId | int | Unique identifier of the request. Can be obtained by using Environment.TickCount (the number of milliseconds that have elapsed since the start of the system).
blob | Binary file data (if the Action parameter is set to Save or Append)
offset | int | The offset from the start of the file after which to append the data (if the Action parameter is set to Append)

File Storage contains all files of the project. The file name contains information about the type of object, its identifier, name of the stream in the form of: <object type>-<object id >-<stream name>version.

Thus, a file with the name 1-4-BlackWhiteImage184201843 represents a file of the page (objectType = 1) with the identifier id=4, streamName=BlackWhiteImage and version=184201843.

Files of pages (objectType = 1) contain copies of images while document files (objectType = 0) contain source images. Thus, you cannot change an image using the POST request with the parameter: objectType = 1. Source images can be obtained by using the POST request with the following parameters:

Action = Load
objectType = 0
objectId = documented
version = 0
streamName = "Page pageId", where pageId is the page identifier
obtained with the
            AddNewPageEx method.

See example requests.


Examples

In the examples below, the C# language is used. In each example, the code for logging, exception handling and request displaying uses the following fuctions:

// needs initializing from the caller for logging

        static public Logging WriteLog = null;

        static private void Trace(string str)

        {

            string gap = "";

            for (int i = 0; i < deep; i++)

                gap = gap + "  ";

            if (WriteLog != null) WriteLog(gap + str);

        }

        static private int deep = 0;

private static void ExceptionHandler(WebException ex)

        {

            Trace("============ WebException ============");

            Trace(ex.Message);

        }

        private static void ExceptionHandler(SoapException ex)

        {

            Trace("============ SoapException ============");

            Trace(ex.Message);

            Trace(e(e("============ Details ============");

            Trace(ex.Detail.InnerText);

        }

        private static void ExceptionHandler(Exception ex)

        {

            Trace("============ Exception ============");

            Trace(ex.Message);

        } }

private static void Show(HttpWebRequest request, string body)

        {

            Trace("HttpWebRequest:");

            deep++;

            Trace("Credentials = " + request.Credentials);

            Trace("Method = " + request.Method);

            Trace("ContentType = " + request.ContentType);

            Trace("ContentLength = " + request.ContentLength);

            deep--;-;

        }

Loading a file from the server

To load a file, a request to the server must be formed (AppServerURL + "/FlexiCapture10/Server/WebServices.dll?Handler=FileService"). The request method is POST, the content type is application/x-www-form-urlencoded. The request body:

"Action=Load" +"&sessionId=" + session + "&objectType=" + objectType + "&projectId=" + projectId + "&batchId=" + batchId + "&objectId=" + objectId + "&version=" + version + "&streamName=" + streamName

Result must be written to a new file.

static private CredentialCache basicAuthenticationCredentialCache = null;

public static List<byte> POSTLoadFile(string AppServerURL, int session, int projectId, int batchId, int objectType, int objectId, int version, string streamName)

        {

            List<byte> result = new List<byte>();

            HttpWebResponse response = null;

            Stream responseStream = null;

            BinaryReader reader = null;

            try

            {

                // form the request

                HttpWebRequest request = (HttpWebRequest)WebRequest.Create(AppServerURL + "/FlexiCapture10/Server/WebServices.dll?Handler=FileService");

                request.Method = "POST";

                // working with authentication, specified when connecting to the web-service

                if (basicAuthenticationCredentialCache != null)

                {

                    request.Credentials = basicAuthenticationCredentialCache;

                } } }

                else

                {

                    request.UseDefaultCredentials = true;

                }

                request.ContentType = "application/x-www-form-urlencoded";

                string postData = "Action=Load" +

                    "&sessionId=" + session +

                    "&objectType=" + objectType +

                    "&projectId=" + projectId +

                    "&batchId=" + batchId +

                    "&objectId=" + objectId +

                    "&version=" + version +

                    "&streamName=" + streamName;

                StreamWriter writer = new StreamWriter(request.GetRequestStream());

                writer.Write(postData);

                writer.Close();    ;

                // show the request

                Show(request, postData);

                // get the response and analyse it

                response = (HttpWebResponse)request.GetResponse();

                responseStream = response.GetResponseStream();

                reader = new BinaryReader(responseStream);

                int responseStreamLength = 0;

                while (true)

                {

                    try

                    {

                        result.Add(reader.ReadByte());

                        responseStreamLength++;

                    }

                    catch (EndOfStreamException)

                    { { {

                        break;

                    }

                }

                reader.Close();

                responseStream.Close();

                response.Close();

                // show the response

                Trace("Out: HttpWebResponse.Stream.Length = " + responseStreamLength);

            }

            catch (WebException ex)

            {

                ExceptionHandler(ex);

            }

            catch (Exception ex)

            {

                ExceptionHandler(ex);

            }

            if (response != null) response.Close();

            if (responseStream != null) responseStream.Close();

            if (reader != null) reader.Close();

            return result;

}

Saving file on the server

You must open an existing file and read data from it (the "content" string must be obtained from a binary file by using Encoding.Default).

To load a file, a request to the server must be formed (AppServerURL + "/FlexiCapture10/Server/WebServices.dll?Handler=FileService"). The request method is POST, the content type is multipart/form-data. The request body:

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"Action\"\r\n\r\nSave" +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"objectType\"\r\n\r\n" + objectType +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"sessionId\"\r\n\r\n" + session +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"projectId\"\r\n\r\n" + projectId +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"batchId\"\r\n\r\n" + batchId +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"objectId\"\r\n\r\n" + objectId +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"version\"\r\n\r\n" + version +

"\r\n--" +
requestId + "\r\ncontent-disposition: form-data;
name=\"streamName\"\r\n\r\n" + streamNameInBase64 +
// name of binary stream in Base64

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"blob\";filename=\"filename.txt\"\r\nContent-Type: application/octet-stream\r\nContent-Transfer-Encoding: binary\r\n\r\n"+ // the "filename" parameter is formal, its value does not affect the request execution
content + //data, to be saved on the server

"\r\n--" + requestId + "--\r\n";

static private CredentialCache basicAuthenticationCredentialCache = null;

// the "content" string must be obtained from a binary file by using Encoding.Default

        public static List<byte> POSTSaveFile(string AppServerURL, int session, int projectId, int batchId, int objectType, int objectId, int version, string streamName, string content)

        {

            List<byte> result = new List<byte>();

            HttpWebResponse response = null;

            Stream responseStream = null;

            StreamReader reader = null;

            int requestId = Environment.TickCount;

            try

            {

                // form the request

                HttpWebRequest request = (HttpWebRequest)WebRequest.Create(AppServerURL + "/FlexiCapture10/Server/WebServices.dll?Handler=FileService");

                request.Method = "POST";

                // working with authentication, specified when connecting to the web-service

                if (basicAuthenticationCredentialCache != null)

                {

                    request.Credentials = basicAuthenticationCredentialCache;

                }

                else

                {

                    request.UseDefaultCredentials = true;

                }

                request.ContentType = "multipart/form-data, boundary=" + requestId;

                byte[] streamNameInBytes = Encoding.Unicode.GetBytes(streamName);

                UnicodeEncoding UTFencofing = new UnicodeEncoding();

                string postData = "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"Action\"\r\n\r\nSave" +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"objectType\"\r\n\r\n" + objectType +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"sessionId\"\r\n\r\n" + session +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"projectId\"\r\n\r\n" + projectId +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"batchId\"\r\n\r\n" + batchId +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"objectId\"\r\n\r\n" + objectId +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"version\"\r\n\r\n" + version +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"streamName\"\r\n\r\n" + Convert.ToBase64String(streamNameInBytes) +

"\r\n--" + requestId +
"\r\ncontent-disposition: form-data;
name=\"blob\";filename=\"filename.txt\"\r\nContent-Type:
application/octet-stream\r\nContent-Transfer-Encoding: binary\r\n\r\n";

                postData += content;

                postData += "\r\n--" + requestId + "--\r\n";

                StreamWriter writer = new StreamWriter(request.GetRequestStream(), Encoding.Default);

                writer.Write(postData);

                writer.Close();

                // show the request

                Show(request, postData);

                // get the response and analyse it

                response = (HttpWebResponse)request.GetResponse();

                responseStream = response.GetResponseStream();

                // show the response

                Trace("Out: ");

                reader = new StreamReader(responseStream);

                Trace("HttpWebResponse.Stream: " + reader.ReadToEnd());

                reader.Close();

                responseStream.Close();

                response.Close();

            }

            catch (WebException ex)

            {

                ExceptionHandler(ex);

            }

            catch (Exception ex)

            {

                ExceptionHandler(ex);

            }

            if (response != null) response.Close();

            if (responseStream != null) responseStream.Close();

            if (reader != null) reader.Close();

            return result;

        }

Getting a checksum

To get a checksum, a request to the server must be formed (AppServerURL + "/FlexiCapture10/Server/WebServices.dll?Handler=FileService"). The request method is POST, the content type is application/x-www-form-urlencoded. The request body:

"Action=Checksum" + "&sessionId=" + session + "&objectType=" + objectType + "&projectId=" + projectId + "&batchId=" + batchId + "&objectId=" + objectId + "&version=" + version + "&streamName=" + streamName

static private CredentialCache basicAuthenticationCredentialCache = null;

public static List<byte> POSTGetChecksum(string AppServerURL, int session, int projectId, int batchId, int objectType, int objectId, int version, string streamName)

        {

            List<byte> result = new List<byte>();

            HttpWebResponse response = null;

            Stream responseStream = null;

            BinaryReader reader = null;

            try

            {

                // form the request

                HttpWebRequest request = (HttpWebRequest)WebRequest.Create(AppServerURL + "/FlexiCapture10/Server/WebServices.dll?Handler=FileService");

                request.Method = "POST";

                // working with authentication, specified when connecting to the web-service

                if (basicAuthenticationCredentialCache != null)

                {

                    request.Credentials = basicAuthenticationCredentialCache;

                }

                else

                {

                    request.UseDefaultCredentials = true;

                }

                request.ContentType = "application/x-www-form-urlencoded";

                string postData = "Action=Checksum" +

                    "&sessionId=" + session +

                    "&objectType=" + objectType +

                    "&projectId=" + projectId +

                    "&batchId=" + batchId +

                    "&objectId=" + objectId +

                    "&version=" + version +

                    "&streamName=" + streamName;

                StreamWriter writer = new StreamWriter(request.GetRequestStream());

                writer.Write(postData);

                writer.Close();

                // show the request

                Show(request, postData);

                // get the response and analyse it

                response = (HttpWebResponse)request.GetResponse();

                responseStream = response.GetResponseStream();

                reader = new BinaryReader(responseStream);

                int responseStreamLength = 0;

                while (true)

                {

                    try

                    {

                        result.Add(reader.ReadByte());

                        responseStreamLength++;

                    }

                    catch (EndOfStreamException)

                    {

                        break;

                    }

                }

                reader.Close();

                responseStream.Close();

                response.Close();

                // show the response

                Trace("Out: HttpWebResponse.Stream.Length = " + responseStreamLength);

            }

            catch (WebException ex)

            {

                ExceptionHandler(ex);

            }

            catch (Exception ex)

            {

                ExceptionHandler(ex);

            }

            if (response != null) response.Close();

            if (responseStream != null) responseStream.Close();

            if (reader != null) reader.Close();

            return result;

        }

Loading by parts (modifying the existing file)

Data can be appended to an existing file only, so the file must be first created on the server.

To modify a file, a request to the server must be formed (AppServerURL + "/FlexiCapture10/Server/WebServices.dll?Handler=FileService"). The request method is POST, the content type is multipart/form-data. The request body:

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"Action\"\r\n\r\nAppend" +

\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"objectType\"\r\n\r\n" + objectType +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"sessionId\"\r\n\r\n" + session +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"projectId\"\r\n\r\n" + projectId +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"batchId\"\r\n\r\n" + batchId +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"objectId\"\r\n\r\n" + objectId +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"version\"\r\n\r\n" + version +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"streamName\"\r\n\r\n" + streamNameInBase64 +

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"blob\";filename=\"filename.txt\"\r\nContent-Type: application/octet-stream\r\nContent-Transfer-Encoding: binary\r\n\r\n" +

сontent + //the string is obtained the same way as in the previous paragraph

"\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"offset\"\r\n\r\n" + offset + //offset from the beginning of the file, where to append data

"\r\n--" + requestId + "--\r\n";

static private CredentialCache basicAuthenticationCredentialCache = null;

// the "content" string must be obtained from a binary file by using Encoding.Default

        // important: data can be appended to an existing file only, so you must first create a file using the POSTSaveFile method

        public static List<byte> POSTAppendFile(string AppServerURL, int session, int projectId, int batchId, int objectType, int objectId, int version, string streamName, string content, int offset)

        {

            List<byte> result = new List<byte>();

            HttpWebResponse response = null;

            Stream responseStream = null;

            StreamReader reader = null;

            int requestId = Environment.TickCount;

            try

            {

                // form the request

                HttpWebRequest request = (HttpWebRequest)WebRequest.Create(AppServerURL + "/FlexiCapture10/Server/WebServices.dll?Handler=FileService");

                request.Method = "POST";

                // working with authentication, specified when connecting to the web-service

                if (basicAuthenticationCredentialCache != null)

                {

                    request.Credentials = basicAuthenticationCredentialCache;

                }

                else

                {

                    request.UseDefaultCredentials = true;

                }

                request.ContentType = "multipart/form-data, boundary=" + requestId;

                byte[] streamNameInBytes = Encoding.Unicode.GetBytes(streamName);

                UnicodeEncoding UTFencofing = new UnicodeEncoding();

                string postData = "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"Action\"\r\n\r\nAppend" +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"objectType\"\r\n\r\n" + objectType +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"sessionId\"\r\n\r\n" + session +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"projectId\"\r\n\r\n" + projectId +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"batchId\"\r\n\r\n" + batchId +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"objectId\"\r\n\r\n" + objectId +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"version\"\r\n\r\n" + version +

                    "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"streamName\"\r\n\r\n" + Convert.ToBase64String(streamNameInBytes) +

"\r\n--" + requestId +
"\r\ncontent-disposition: form-data;
name=\"blob\";filename=\"filename.txt\"\r\nContent-Type:
application/octet-stream\r\nContent-Transfer-Encoding: binary\r\n\r\n";

                postData += content;

                postData += "\r\n--" + requestId + "\r\ncontent-disposition: form-data; name=\"offset\"\r\n\r\n" + offset;

                postData += "\r\n--" + requestId + "--\r\n";

                StreamWriter writer = new StreamWriter(request.GetRequestStream(), Encoding.Default);

                writer.Write(postData);

                writer.Close();

                // show the request

                Show(request, postData);

                // get the response and analyse it

                response = (HttpWebResponse)request.GetResponse();

                responseStream = response.GetResponseStream();

                // show the response

                Trace("Out: ");

                reader = new StreamReader(responseStream);

                Trace("HttpWebResponse.Stream: " + reader.ReadToEnd());

                reader.Close();

                responseStream.Close();

                response.Close();

            }

            catch (WebException ex)

            {

                ExceptionHandler(ex);

            }

            catch (Exception ex)

            {

                ExceptionHandler(ex);

            }

            if (response != null) response.Close();

            if (responseStream != null) responseStream.Close();

            if (reader != null) reader.Close();

            return result;

        }


Examples of API Use

This section contains demo examples which show how the API can be used.

  • Processing multiple documents in one batch


Processing Multiple Documents in One Batch

This example has been created with Microsoft Visual Studio. For the code below, it is assumed that the project contains a reference (WebReference) to a Web service and FlexiCapture has been selected as the name of the reference (the generated name space corresponds to the name). It is also assumed that a Trace function to write data to a log file has been defined (e.g. via Debug.Print).

The example below is for demonstration purposes only. A real project requires using reliable class-wrappers around the objects being opened and mechanisms similar to using in C#. It is desirable to have a mechanism for purging abandoned sessions and batches that will not be affected by power cuts or disruptions in the communications network (this can be achieved by saving the ID and closing the session as part of the recovery procedure). Non-closed sessions themselves do not cause any adverse effects. However, they can accumulate over time and cause problems in system administration. Additionally, undeleted batches will consume the server's resources, mainly the storage space for images and documents.

To execute the sample code, load the project on a newly installed server and enable unattended processing on the Workflow tab of the project properties dialog box. To load the file, the System.IO name space must be used.

public void RunSample(string serverUrl)

{

       try

       {

             // Initialize service

             FlexiCapture.FlexiCaptureWebServiceApiVersion2 service = new FlexiCaptureWebServiceApiVersion2();

// FlexiCaptureWebServiceApiVersion2 is a name of interface which is realized by Web service of
// FlexiCapture.
 // To reference version 2 of the service, the URL should be constructed as follows.
// Please notice that the resulting URL is different from that used to
// reference WSDL (which was previously used to add the web-reference)

service.Url = serverUrl + "/FlexiCapture10/Server/WebServices.dll?Handler=Version2";

// Enable transparent log-on using credentials of the current thread

service.Credentials = System.Net.CredentialCache.DefaultCredentials;

             // Open session

             int sessionId = service.OpenSession();

             try

             {

// List available projects (this can be omitted if you work with
// a fixed project, in which case the preferred method is to open
// a project by GUID)

                    FlexiCapture.Project[] projects = service.GetProjects();

                    if( projects != null )

                    {

                          foreach( FlexiCapture.Project project in projects )

                          {

                                 Trace( project.Name + " : " + project.Guid );

                          }

                    }

                    // Open the first project in the list

                    int projectId = service.OpenProject( sessionId, projects[0].Guid );

                    // List available batch types

                    FlexiCapture.BatchType[] batchTypes = service.GetBatchTypes( projectId );

                    if( batchTypes != null )

                    {

                          foreach( FlexiCapture.BatchType batchType in batchTypes )

                          {

                                 Trace( batchType.Name + " : " + batchType.Description );

                          }

                    }

                    // Create a new batch

                    FlexiCapture.Batch batch = new FlexiCapture.Batch();

                    batch.Name = "Sample API Batch";

                    int batchId = service.AddNewBatch( sessionId, projectId, batch );

                    // Load sample images (see below for definition of LoadFile)

                    FlexiCapture.File file1 = LoadFile( "Banking 1.png" );

                    FlexiCapture.File file2 = LoadFile( "Banking 2.png" );

                    FlexiCapture.File file3 = LoadFile( "Banking 3.png" );

                    // Add sample images

                    for(
int i = 0; i <
3;
i++ )

                    {

                          service.AddNewImage( sessionId, batchId, file1 );

                          service.AddNewImage ( sessionId, batchId, file2 );

                          service.AddNewImage ( sessionId, batchId, file3 );

                    }

                    // Start processing the batch

                    service.ProcessBatch( sessionId, batchId );

                    // Wait for processing to complete

                    int percentCompleted = 0;

                    while( percentCompleted < 100 )

                    {

                          percentCompleted = service.GetBatchPercentCompleted( batchId );

                          System.Threading.Thread.Sleep( 500 );

                    }

                    // Analyse results

                    FlexiCapture.Document[] documents = service.GetDocuments( batchId );

                    if( documents != null )

                    {

                          foreach( FlexiCapture.Document document in documents )

                          {

                                 FlexiCapture.File attachedFile =

service.LoadDocumentResult( document.Id, "MyResult.xml" );

                          }

                    }

                    // Clean up

                    service.DeleteBatch( sessionId, batchId );

                    service.CloseProject( sessionId, projectId );

             }

             finally

             {

                    service.CloseSession( sessionId );

             }

       }

       catch ( Exception ex )

       // Use catch ( SoapException ex ) to catch only exceptions which are raised by
       // Application Server

       {

             Trace( ex.Message );

       }

}

public FlexiCapture.File LoadFile( string fileName )

{

       FlexiCapture.File file = new FlexiCapture.File();

       using( FileStream stream = File.Open( fileName, FileMode.Open ) )

       {

             file.Name = fileName;

             file.Bytes = new byte[stream.Length];

             stream.Read( file.Bytes, 0, file.Bytes.Length );

       }

       return file;

}