Integrating Transact Web Services with Nintex

Two Transact web services, v2/ocrClassifyExtract and v2/ocrClassifyExtractBase64, have been optimized specifically to work with advanced workflow engines. This document provides an example of how to integrate these web services with the Nintex workflow engine.

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.

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. Please note that in these two web services, there is no concept of separation – we assume every document contains a single document of a single document type and perform classification based on the first page.

What Makes these Web Services Different?

Other Transact web services use XML for input and output.  These web services use simplified JSON inputs and return simplified JSON responses. Following is an example of a simplified JSON response:

Simplified JSON Response

As shown above, the JSON reply only contains a minimal amount of data:  document type name and confidence score, plus index field names, values and confidence scoresation based on the first page.

How Can the New Web Services be Utilized?

Modern cloud applications have removed the complexities of writing code for integration. With OpenAPI-compliant web services, uploading a JSON Swagger definition file into the workflow tool allows you to access the web services’ capabilities almost immediately. Below are two examples of how the Swagger definition can be used in the Nintex Workflow Cloud and Microsoft Flow.

Nintex Extension Configuration

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.

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

Download Supporting Files

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

https://drive.google.com/file/d/1a-Gy4Sz1WD7oqH1qDSO3ycH2YH9EcG4b/view?usp=sharing

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.

Edit 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.

Create 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.

Create 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 Notification

Request 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:

https://www.youtube.com/watch?v=icaIuvvkD-0

Send an email to sales.support@ephesoft.com 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.

Import 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 Options

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

Workflows List

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.

Edit 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).

Edit the Box Connection

Click the Start event: Box – New file button:

Box – New file Button

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 Settings

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.

Edit 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 Button

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.

Edit 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 Button

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 Button

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.

Examine 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”.

Result:

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 Node

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:

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.

GetDocType Options

In the above example, the JSON path expression will return the document type, and store in a text variable called EphesoftDocType.

Jsonpath.com is very helpful tool to help with parsing the JSON data returned from the Ephesoft action.

http://jsonpath.com/

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 web service.

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 web service returns XML as the response body. Nintex does not support XML responses.