Last Updated on
With Ephesoft Transact release 184.108.40.206, 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.
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.
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.
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:
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:
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.
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.
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.
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.
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.
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.
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.
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:
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 firstname.lastname@example.org 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.
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.
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.
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.
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.
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.
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.
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:
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.
Jsonpath.com is very helpful tool to help with parsing the json data returned from the ephesoft 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.