Introducing OpenAPI-Compliant Intelligent Capture Web Services

With Ephesoft Transact release, Ephesoft has introduced a new concept in our APIs:

All current APIs are now compliant with the OpenAPI (Swagger) standard.

  • Two new APIs have been introduced that provide simplified responses in JSON (Instead of XML).
  • These features were built with certain markets in mind, especially RPA and workflow technologies that rely on OpenAPI standards for ease of integration.
  • The two new APIs are OCRClassifyExtract and OCRClassifyExtractBase64.

Many of the current cloud technologies on the market (Box, Salesforce, Flow, etc) stream files using Base64 encoding, and this was previously accomplished with our web services through a custom translation wrapper.

What is OpenAPI?

From the OpenAPI Initiative:

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how REST APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor neutral description format. The Swagger Specification was donated directly to the OAI as the basis of this Open Specification.

APIs form the connecting glue between modern applications. Nearly every application uses APIs to connect with corporate data sources, third party data services or other applications. Creating an open description format for API services that is vendor neutral, portable and open is critical to accelerating the vision of a truly connected world.

Essentially, the standard provides a structured method to document your REST APIs. These standards also include a definition format that can be discovered or imported into other apps to auto-configure integration.

Why Swagger in Ephesoft?

As we continue our growth and expansion into new markets, one thing is clear: enhanced documentation on our APIs is required to expand usage. Also, there is a movement in the market towards simplified APIs that can be used by Citizen Developers, or tech savvy business users. Products like Nintex, K2 and Flow allow you to upload a Swagger Definition File, and they auto-configure the API integration for you. This allows organizations to quickly enable capture in existing environments.

Enhanced Documentation

With Open API compliance, documentation is standardized and some new, core pages are produced. The Swagger UI page provides an outline of all available services, and details on how they can be used. In addition, they can all be tested, without code, through this central service repository page.

Swagger Root Documentation Page for Ephesoft APIs

ocrClassifyExtract Implementation Notes

Easy Testing and Demos — Simplified Response + JSON

In the APIv2, there were two other critical requirements:

JSON responses and simplified structure. All the modern platforms today utilize JSON (JavaScript Object Notation) as a standard. Our current APIs use XML, which required complex customizations to adapt.

In addition, our original APIs were quite complex from a response perspective, and required extensive parsing and logic to get what you required.

Below is our latest simplified response:

Simplified response

APIv2 Simplified Response

You can see we only return the absolute minimum required:
Type (Document Type)

  • Type Confidence
  • Fields and Confidence Levels

Note: In the two new APIs, there is no concept of separation. We assume every document contains a single document type and perform classification based on the first page.

How Can the New APIs be Utilized?

Modern cloud applications have removed the complexities of writing code for integration. With OpenAPI compliant services, just upload your Swagger Definition File (JSON), and that’s it. Below are two examples of how the swagger definition can be used in Nintex Workflow Cloud and Microsoft Flow.

Nintex Extension Configuration (Just Upload Ephesoft Swagger Definition)

Microsoft Flow Configuration (Swagger Definition Upload)

Once the connector is automatically built, you can now use Ephesoft Actions within the application designers as shown below.

Flow/Nintex Designers with Ephesoft API Actions

Flow/Nintex Designers with Ephesoft API Actions

Through mid-process calls to add document intelligence to any process, incremental automation can take place, making workflows more intelligent and further reducing the requirement for human intervention.

Note: APIv2 can also be used by software developers to develop custom applications or integrate other systems with Ephesoft.

Creating a New Nintex Connector for Ephesoft Transact

Before you can create a Nintex workflow that takes advantage of Ephesoft Transact web services, you’ll need to create a new connector in the Nintex Xtensions framework using the appropriate Ephesoft Transact Swagger definition file.

To take full advantage of the sample workflow explained in this document, you will need the following:

  • A Nintex account
  • A Box developer’s account
  • Existing Box connection defined in Nintex

Downloading Supporting Files

Download the following zip file and extract it on your local PC:

This zip file will contain the following items:

  • Swagger definition file for the OCR Classify Extract web service
  • Image file containing the Ephesoft logo to be used in Nintex
  • Wealth Management batch class for Transact
  • Sample document files for the Wealth Management batch class

Import the Sample Batch Class

Import the Wealth Management batch class into your Transact system. Make note of the batch class ID – you’ll need it later on in this document.

Editing the Swagger Definition File

Open the OcrClassifyExtractSwaggerDefinition.json file file for editing, and change the host value to point to your Nintex endpoint:


Save your changes and close the file.

Creating the Connector

Log in to Nintex, then click the Xtensions option in the left navigation bar.

Create Workflow

This will open the Nintex Xtensions page. Nintex Xtensions is a framework that allows you to create connectors to extend the Nintex Workflow Platform. Click the symbol near the top right corner to create a new connector.

Private connector list

This will take you to the first step of a multi-step procedure to add your new connector.

Private connector list — Connector definition

Click the Choose a file button and upload the updated “OcrClassifyExtractSwaggerDefinition.json” file that you extracted from the downloaded zip file.

OpenAPI specification file

Click the Next button to go to the Configure Security step.

Configure security

Accept the default value of Basic Authentication, then click the Next button to move to the Publish step.

Accept the default values for Name and Description.

Click the Choose a file button to upload the Ephesoft logo that you extracted from the zip file downloaded earlier.

Publish settings

Click the Publish button.

Your connector will appear in your Private connector list with a green triangle and check mark to indicate that it’s a new connector.

Private connector list

The new connector is now available to you for building and editing workflows.

Creating a New Connection

Now that you’ve defined a new connector, you need to use that connector to create a connection. This connection will define the communication path between Nintex and your environment.

Click the Connections option in the panel on the left.

Create Workflow

Then, click the Add new button near the top right of the screen.

Add new button

This will open the Add a new connection window. Choose the connector that you defined in the previous section and click the Connect button.

Add a new connection

This will open the following window:

Ephesoft JSON OcrClassifyExtract connection

Enter a value for the Connection Name field. This is the name of the connection that will be used to configure the workflow later on in this document. Enter a valid username and password for an account in your Transact environment.

Click the Connect button to test your connection. If your connection is successful, the following message will appear:

Connection created

Requesting a Sample Nintex Workflow from Ephesoft

We’ve created a sample workflow to help get you started. This workflow will execute when files are dropped into a predefined location in Box. The files will be processed using the OCR Classify Extract web service, then a series of logical operations will take place to determine how different individuals should be notified of the results. This sample workflow is explained in the following video:

Send an email to requesting the sample workflow, and we’ll reply with a workflow key that you can use to import this workflow into your own environment.

Please note that once the key is generated, you will have 72 hours in which to use the key to import the workflow into your environment. The workflow will continue to work after that 72-hour period, but the key will no longer be valid for new imports.

Importing the Sample Nintex Workflow from Ephesoft

After receiving the workflow key, click the Import button at the top right of the screen.

Click the Import button

Paste the workflow key that you received from Ephesoft into the Workflow key field, enter a unique name for your workflow, and click the Import button.

Import workflow

The new workflow will appear in your Workflows list with a green triangle and check mark to indicate that it’s new.


Note that the imported workflow has a status of “Draft” right now. Do not publish the imported workflow at this point. Several additional steps must be followed to make the workflow unique for your individual use.

Editing Your New Nintex Workflow

The imported workflow contains connection and configuration information that won’t apply to your environment. This section tells you how to configure the workflow to work within your environment.

Click the name of the workflow to open it for editing (or, click the Edit command from the drop-down list under the button).

Editing the Box Connection

Click the Start event: Box – New file button:

Box – New file

This will open the Start event configuration window.

Start event configuration

Select an existing connection to Box (or create a new Box connection), then click the subfolder button on the right to select a folder path from that connection.

Subfolder button

The workflow will be triggered when files are dropped into that folder.

Edit the OCR Classify Extract Parameters.

Click the Ocr Classify Extract JSON button:

Ocr Classify Extract JSON button

This will open a panel on the right side of the screen.

Classify Extract JSON

Choose a value for the Connection field that represents the end point of your Ephesoft Transact server. This is the connection that you created earlier in this document.

Enter the batch class identifier of the Wealth Management batch class that you imported into your Transact environment earlier.

Accept the default value of “File variable” for the Input File field. In this workflow, this parameter represents the files passed in from the “Box – New File” event.

Editing the Email Recipients

Please note that the following task appears in multiple locations in the workflow. Edit each instance accordingly.

Click the Send an email button.

Send an email

This will open the following panel:

Send an email settings

Enter one or more email addresses in the Recipient email addresses field. When the workflow executes this task, an email will be sent to these email addresses.

Editing the Task Properties

Please note that this task appears in multiple locations in the workflow. Edit each instance of this task accordingly.

Click the Assign a task button.

Assign a task

This will open the following panel:

Assign a task settings

Enter the email address of the individual who will be assigned this task.

Edit the Box Connection and Path for the generated files.

Click the Store a file button.

Store a file

This will open the following panel:

Store a file settings

Choose the name of your existing Box connection.

Accept the default value of File variable for the File field. In this workflow, this parameter represents the processed files generated by Ephesoft Transact.

Choose a path to a folder in your Box instance for the Path field.

When the workflow executes this task, the file will be stored in this folder in Box.

Execute the Workflow

Once all of the appropriate parameters have been configured, publish the workflow by clicking the Publish command in the command banner near the top of the screen.

Publish command in menu

To test the workflow, copy some of the wealth management sample files (from the zip file downloaded earlier in this document) into the Box folder identified in the Start Event task.

Examining the Ephesoft JSON Response

When consuming the Ephesoft extension, three fields are required. Below is an example of a completely configured extension:

Example of an extension configuration

Batch Class Identifier:

In the demo Ephesoft instance, this is BC6 for the Wealth Management demo.

Input File:

This file contains the document that will be examined by Ephesoft. Ingestion is usually completed by a previous start event (Box, SharePoint, Email,…). In the demo Ephesoft instance, this file was passed on by a “Box – New File” start event. The pointer to this file is the variable “File variable”.


This is just a regular Nintex text variable that will contain the JSON response from Ephesoft. In this example, the text variable is “EphesoftResponse”.

Adding a Log to Instance Details node, immediately after the Ephesoft extension, will record the JSON response in the instance screen.

Log to instance details

To view the JSON response, navigate to the instance screen and select your specific instance you would like to examine:

Create workflow

Instance activities

Example: Parse the JSON Response to Determine Document Type

JSON parsing example

Parsing the JSON response exposes the various insights into the document such as various confidence values, extracted metadata, and document type.

To parse the response, add a Query JSON node after the Ephesoft Extension. This is under the Integration section:


The Query JSON node configuration requires the text variable that contains the JSON response from the Ephesoft extension result. In this example, result is stored in Ephesoft Response:

Sample JSON example result

Configure the JSON source to be the same text variable.


In the above example, the JSON path expression will return the Document Type, and store in a Text Variable called EphesoftDocType. is very helpful tool to help with parsing the json data returned from the ephesoft action.

Using the Upload Batch Action

The Ephesoft Nintex integration also has the ability to push images to a batch process within Ephesoft using the Upload batch API.

Below are some steps that you can used to leverage this action.

Using the Upload a Batch controls

Note: The result field should not be mapped to any variable. The upload batch API returns XML as the response body. Nintex does not support xml responses.

Was this article helpful to you?

Vincent Francis