Last Updated on

Ephesoft Transact OpenAPI-Compliant Web Services

Ephesoft Transact’s OpenAPI-Compliant web services provide a simple method for real-time integration and exposure of Ephesoft Transact capabilities to external applications, allowing developers to embed advanced capture features in their own solutions without having to display the Transact user interface.

Ephesoft provides over 60 Transact web services to perform advanced capture actions in your custom application. These web services perform tasks that range from simple actions like determining which batch instances can be seen by an individual user, to performing complete OCR/classification/extraction procedures on a collection of documents.

Ephesoft Transact web services support the self-documenting feature of the OpenAPI Specification v2.4.0 (formerly known as the Swagger Specification). This means that tools like Swagger UI can be used to browse the collection of web services and view detailed documentation for each web service. The Swagger UI tool is bundled with Ephesoft Transact, and can be accessed by navigating to the following URL in your Transact instance:

http://<server_name>:<port>/dcma/rest/swagger-ui.html

Navigating to this URL will take the user to the Ephesoft Transact Web Services Explorer, as shown below. This interface lists all Ephesoft Transact web services on a single page, allowing both seasoned developers and “citizen developers” to browse and navigate through the Ephesoft Transact web services available within their server.

Ephesoft Web Services Documentation Screen

This interface also allows the user to review detailed information about each web service. Clicking a web service in the Web Services Explorer allows you to drill further into the web service to view additional details, as shown below.

Ephesoft Web Services Implementation Notes

The overall Ephesoft Transact OpenAPI-compliant web services definition file for all API endpoints is represented in JSON format. This definition file can be found at the following location in your Transact instance: http://<server_name>:<port>/dcma/rest/v2/api-docs.json

Click here for the Ephesoft Transact web services wiki page to see a listing of Ephesoft Transact Web Services: https://wiki.ephesoft.com/transact-web-service-definitions

Ephesoft Transact Web Services Optimized for Workflow Engines

All Ephesoft Transact web services support the self-documenting capabilities of the OpenAPI Specification, but only two Ephesoft Transact web services, v2/ocrClassifyExtract and v2/ocrClassifyExtractBase64, provide simplified JSON responses, allowing them to be embedded into workflow engines like Nintex and Microsoft Flow. These minimized JSON responses have a smaller footprint and improved interoperability. An example of this minimized JSON response is shown below.

Minimized JSON Example

These two web services have been optimized specifically for advanced workflow engines. Here are descriptions of each of those web services.

v2/ocrClassifyExtract

The v2/ocrClassifyExtract web service was designed to work with the Nintex workflow engine. It performs OCR, classification and extraction on the supplied input documents. Classification is based only on the first page of each file before extracting the index fields defined in the corresponding batch class.

Classification and extraction are performed based on the plugins configured in the corresponding batch class, with two exceptions: 1) The PAGE_PROCESS_SCRIPTING_PLUGIN plugin will not be executed; and 2) Table extraction will be performed if the plugin is turned on, but extracted table data will not be returned in the response.

This web service supports all input file types that are supported by Ephesoft Transact (https://wiki.ephesoft.com/supported-file-types). Only one file can be supplied as input, but multiple files can be processed at one time by combining them in a zip file and submitting the zip file to the web service (however, remember that each physical file inside the zip file will be treated as a single logical file, and will be classified based on the contents of the first page only – no separation will occur within the individual files).

The v2/ocrClassifyExtract web service returns a minimized JSON response.

The following table summarizes additional information about this web service.

URL /dcma/rest/v2/ocrClassifyExtract
Request Type POST
Input Type Multipart/form-data
Output Type application/json

v2/ocrClassifyExtractBase64

The v2/ocrClassifyExtractBase64 web service performs the same functionality as the v2/ocrClassifyExtract web service, but it uses a Base64-encoded string as input. Many cloud technologies today (such as Box, Salesforce, and Microsoft Flow) stream data using Base64 encoding. By supporting a Base64-encoded input format, this web service can provide greater flexibility to integrate Ephesoft Transact advanced capture capabilities into users’ custom solutions.

The v2/ocrClassifyExtractBase64 web service performs OCR, classification and extraction on the supplied input documents. Classification is based only on the first page of each file before extracting the index fields defined in the corresponding batch class.

Classification and extraction are performed based on the plugins configured in the corresponding batch class, with two exceptions: 1) The PAGE_PROCESS_SCRIPTING_PLUGIN plugin will not be executed; and 2) Table extraction will be performed if the plugin is turned on, but extracted table data will not be returned in the response.

This web service supports all input file types that are supported by Ephesoft Transact (https://wiki.ephesoft.com/supported-file-types). Only one file can be supplied as input, but multiple files can be processed at one time by combining them in a zip file and submitting the zip file to the web service as a Base64 encoded string (however, remember that each physical file inside the zip file will be treated as a single logical file, and will be classified based on the contents of the first page only – no separation will occur within the individual files).

The v2/ocrClassifyExtractBase64 web service returns a minimized JSON response.

Here’s an example of a JSON input file for the v2/ocrClassifyExtractBase64 web service:

{

“batchClassIdentifier”: “BC6”,

“fileName”: “Filename.pdf”,

“fileContent”: “<Base64-Encoded String>

}

The following table summarizes additional information about this web service.

URL /dcma/rest/v2/ocrClassifyExtractBase64
Request Type POST
Input Type application/json
Output Type application/json

Using Ephesoft Transact Web Services with Workflow Engines

Because they support minimized JSON responses, the v2/ocrClassifyExtract and v2/ocrClassifyExtractBase64 web services can be fully integrated into advanced workflow engines such as Nintex or Microsoft Flow. These tools allow users to develop complex workflows that can integrate different products and services together, enabling decision-making processes with or without human intervention.

For example, a workflow can easily be constructed to monitor Box to look for any new invoices created in the “Incoming” folder. When a new invoice is created in that folder, the v2/ocrClassifyExtract web service can extract the invoice amount from the invoice and feed that data into a decision tree. Invoices with amounts of $1000 or less can be approved automatically and routed to a “Processed” folder in Box. Invoices with amounts greater than $1000 can trigger a notification for an employee to review and approve the invoice before releasing it to the “Processed” folder.

The following document provides detailed information on how the new v2/ocrClassifyExtract web service can be integrated into complex workflow designs using Nintex:

https://wiki.ephesoft.com/web-services-integrating-Nintex

 

Note: Currently we support only basic authentication for Transact web services (base 64 encoded user name and password). Token-based authentication usually used with SAML, OAuth and other Single Sign-On authentication frameworks is not supported.

 

Was this article helpful to you?

Vincent Francis