Transact

  1. Home
  2. Transact
  3. Features and Functions
  4. Administrator Role and Features
  5. Modules and Plugins
  6. Page Process Module
  7. Cloud OCR (Advanced HOCR) Plugin

Cloud OCR (Advanced HOCR) Plugin

Introduction

Applies to: Transact version 2022.1.00 or newer (Windows and Linux).

This article describes how to install and configure the Cloud OCR (ADVANCED_HOCR) plugin in Ephesoft Transact. These steps are intended for Transact administrators.

With the Cloud OCR plugin, Transact will extract OCR content from document images to create HOCR files for use with downstream extraction plugins. More specifically, this plugin enables Transact to connect to and use external OCR engines, such as Google Cloud Vision, to extract the OCR content. The Cloud OCR plugin reads the image files listed in the batch.xml file of a batch instance and generates an HOCR XML file for each page in the batch instance.

Note: See Functional Limitations for more information on what is not currently supported.

Licensing

The Cloud OCR plugin is included with the standard Transact license. Additionally, to use this plugin you will need a service account with Google for Google Cloud Vision. See Prerequisites for more information.

Prerequisites

To configure and use the Cloud OCR plugin, the following must be in place:

  • A licensed version of Ephesoft Transact 2022.1.00 or above.
  • A MariaDB or MS SQL Server relational database management system (RDBMS) with administrative credentials having GRANTS to create a database and a user.
  • A license for Google Cloud Vision must be purchased from Google.
  • A Cloud Vision service endpoint and API key will be required to configure the ADVANCED_HOCR plugin. To set up a Google Cloud Vision instance, reference: Quickstart: Setup the Vision API.

Functional Limitations

Below are functional limitations for the Cloud OCR plugin:

  • For Transact 2022.1.00, Google Cloud Vision (GCV) is the only supported OCR engine.
  • Per Google Cloud Vision, image files uploaded for processing have a limit of 20 MB per file, and image size should not exceed 75M pixels (length x width).
    • This file size limit is specific to GCV and may not apply to other OCR engines.
    • Note: This does not mean files uploaded to Transact are limited to 20 MB. When a document is uploaded, the pages are rasterized to PNG before being submitted to GCV for processing. If the raster images are greater than 20mb in size, GCV will fail to process the file.
  • Batch instances with more than 200 pages may lead to OutOfMemory errors. It is recommended to use smaller size batch instances.
  • Cloud OCR is not supported for multi-node Transact environments.
  • A Language Hint with Auto selected returns all languages that GCV supports. Refer to Transact’s Supported Languages for certified languages.
  • Handwritten dates may not extract well due to limitations of GCV.
  • The E13B font often used in checks may not extract well due to limitations of GCV.
  • Only the following web services are supported:
    • uploadBatch
    • advancedUploadBatch
    • copyBatchClass
    • exportBatchClass
    • importBatchClass
  • The following services and features are not supported:
    • EText extraction.
    • Batch class encryption.
    • Vertical text extraction.
    • Autorotation and de-skewing.
      Note: Web services that directly communicate with the OCR process (OcrClassify, OcrClassifyExtract, v2/ocrClassifyExtract, and v2/ocrClassifyExtractBase64, etc.) cannot interact with a batch class that has been configured to use ADVANCED_HOCR. For additional information about Ephesoft Transact web services, refer to Web Services Explorer.
  • HOCR coordinate precision for words may be inaccurate due to limitations of GCV.

Cloud OCR Components

The Cloud OCR plugin installer will install a plugin called the ADVANCED_HOCR plugin as well as a separate Cloud OCR Web App.

 

This plugin operates with an accompanying web app, so it operates differently from other Transact plugins. The differences are as follows:

  • Since the installer package includes the ADVANCED_HOCR plugin, there is no need to import the plugin via the Transact UI.
  • When the Transact service starts, it also starts the Cloud OCR Web App.
  • The ADVANCED_HOCR plugin UI depends on two API services located at:
    • /dcma/tcp-ocr-ui (default)
    • /dcma/advancedHocr (default)
  • The API requires a database to store plugin and web app configuration information. This can be the same database as Transact, or it can be a separate database.
  • The plugin uses the PNG files generated by either the CREATE_OCR_INPUT or CREATE_DISPLAY_IMAGE plugins as input.

Install the Cloud OCR Plugin and Web App

To install the Cloud OCR Plugin:

  1. Download the Cloud OCR plugin installer package (AdvancedHOCR_1.0.3.zip) from the Customer Support Portal.
  2. Follow the steps below according to your setup. Reference the Installer Parameters when needed.
  3. For multi-node Transact environments, the Cloud OCR plugin installer must be run on each Transact node.

Windows Installation

  1. Download the Cloud OCR plugin installer package (AdvancedHOCR_1.0.3.zip) from the Customer Support Portal.
  2. Copy the zip file to a temporary folder on your Transact server and unzip it.
  3. Open the windows-args.txt file and modify the parameter values according to your environment (see Installer Parameters). (Sample)
  4. Stop the Transact server.
  5. Open a command prompt as an Administrator.
  6. Navigate to the directory where the installer is unzipped.
  7. In the command line, run install.cmd.
    Note: Upon installation, the installer will update the workflow.deploy property in the dcma-workflows.properties file to true.
  8. Restart the Transact service.
  9. Proceed to Set Up the Cloud OCR Plugin.

Linux Installation

  1. Download the installer ZIP file from the Customer Support Portal.
  2. Copy the zip file to a temporary folder on your Transact server and unzip it.
  3. Open the linux-args.txt file and modify the parameter values according to your environment (see Installer Parameters).
  4. Stop the Transact server.
  5. Open a shell prompt as a super-user. If you are not a super-user, execute the following command to gain super-user permissions: sudo su root.
  6. Navigate to the directory where the installer is unzipped.
  7. In the shell prompt, run bash install.sh.
    Note: Upon installation, the installer will update the workflow.deploy property in the dcma-workflows.properties file to true.
  8. Restart the Transact service.
  9. Proceed to Set Up the Cloud OCR Plugin.

Installer Parameters

Parameter Name Description Required
ephesoftHome The home directory where Transact is installed. This is typically /opt/Ephesoft. Yes
ahocrDatabaseHost The database host for the Cloud OCR plugin database. Yes
ahocrDatabasePort The database host’s port number for the Cloud OCR plugin database.

The default database values are:

  • MariaDB – 3306
  • SQL Server – 1433
Yes
ahocrDatabaseName The database name of the Cloud OCR plugin database. This can be the same as Transact’s database. Yes
ahocrDatabaseType Database engine type for the Cloud OCR plugin database.

The options are:

  • mariadb
  • sqlserver

Note: For MSSQL Server, only SQL Server authentication is supported.

Yes
ahocrDatabaseRootUsername The database user credentials that will be used by the Cloud OCR installer. The user must have permission to create a database service account user, databases, and stored procedures. Yes
ahocrDatabaseRootPassword Password for ahocrDatabaseRootUsername. Yes
ahocrDatabaseRuntimeUsername The database user credentials that will be used as the service account to connect the Cloud OCR web app and the databases at runtime. Yes
ahocrDatabaseRuntimePassword Password for ahocrDatabaseRuntimePassword. Note: The dollar sign ($) character is not supported as a password character. Yes
pluginDatabaseHost The database host for the Transact database. Yes
pluginDatabasePort The database host’s port number for the Transact database. Yes
pluginDatabaseName The database name of the Transact database. This is required for installing the plugin values into the plugin* tables in Transact. Yes
pluginDatabaseType Database engine type for the Transact database.

The options are:

  • mariadb
  • sqlserver
Yes
pluginDatabaseRootUsername User with access to insert into the plugin tables in the Transact database. Yes
pluginDatabaseRootPassword Password for pluginDatabaseRootUsername. Yes
apiBaseUrlOverride Reserved for Ephesoft use only; do not change the value.

The default value is taken from the property batch.base_http_url from the dcma-batch.properties file.

No
installMode Reserved for Ephesoft use only; do not change the value.

The default value is full.

No

Note on Oracle:

With Transact 2022.1.00, Oracle is not supported as a database for the Cloud OCR feature. You may see Oracle database options in your configuration file. Do not edit any lines that reference Oracle.

Set Up the Cloud OCR Plugin

This section provides information on how to set up the ADVANCED_HOCR plugin. This plugin only needs to be configured once per batch class.

Step 1: Add the ADVANCED_HOCR Plugin to the Workflow

  1. From the Batch Class Management screen, select your batch class and click Open.
  2. In the left menu, open Modules.
  3. On the Page Process and Folder Import plugin configuration screens, remove all the following plugins (if present):
      1. RECOSTAR_HOCR
      2. NUANCE_HOCR
      3. TESSERACT_HOCR
  4. In the Page Process module, add the ADVANCED_HOCR plugin.
    1. On Windows, ADVANCED_HOCR depends on CREATE_OCR_INPUT running first.

Figure 1: Windows Plugin Configuration.

    1. On Linux, ADVANCED_HOCR depends on CREATE_DISPLAY_IMAGE running first.

Figure 2: Linux Plugin Configuration.

  1. Click Deploy.

Step 2: Configure the ADVANCED_HOCR Plugin

  1. On the ADVANCED_HOCR Plugin Configuration screen, configure the following parameter:
    1. Enabled: Yes

Figure 3: ADVANCED_HOCR Plugin Configuration.

    1. In the ADVANCED_HOCR plugin drop-down from the left navigation, click Configure.

Figure 4: Advanced HOCR Generation Engine configuration screen.

    1. In the Advanced HOCR Generation Engine configuration screen, configure the following parameters:
Configurable Property Options Description
OCR ENGINE Google Cloud Vision This field will default to Google Cloud Vision, as this is the only supported engine.
SERVICE ENDPOINT N/A The default value is https://vision.googleapis.com/.

Important: Only https://vision.googleapis.com/ has been certified. Other GCV endpoints may work to suit other requirements (e.g. regional).

API KEY N/A Enter the API Key for your Google Cloud Vision instance. The API Key enables Transact to connect to your licensed instance of Google Cloud Vision so it can send documents for OCR content extraction.

If you don’t already have it, you’ll need to generate an API key using the Google Cloud Console.

Note: Once you have entered an API Key and you leave the Configure screen and come back, you will not be able to see your API Key.

LANGUAGE HINTS
  • Auto (default)
  • Dutch
  • English
  • French
  • German
  • Italian
  • Spanish
  • Swedish
  • Polish
The Auto option tells Google Cloud Vision to auto-detect the languages in the documents.

In most cases, Auto yields the best results. In rare cases, when the language of the text in the image is known, setting a hint helps get better results (although it can be a significant hindrance if the hint is wrong).

Google Cloud Vision can process hundreds of languages using the Auto option, however, Transact certifies only the following languages: Supported Languages. For more information on GCV’s languages, refer to OCR language support.

Step 3: Test the OCR Engine Connection

  1. Click Test to check whether Transact can connect to your Google Cloud Vision instance. If it fails, refer to Troubleshooting.

Figure 5: Connection Successful message.

  1. Click Save.

Your batch class is now ready to process documents using the Cloud OCR plugin.

Define Extraction Rules for Handwritten Content

The Cloud OCR plugin will generate whole-page HOCR content for cursive, handprint, and machine print automatically for any extraction methods to use. Because of this, select the standard machine print options when configuring extraction rules.

Process a Batch Instance with Cloud OCR Plugin

  1. From the Batch Class Management screen, click Upload Batch in the left fly-out menu. Alternatively, import your documents using a different method.
  2. Upload your documents.
  3. Select the batch class and click Start Batch.
    Note: Batch classes configured to use the ADVANCED_HOCR plugin will follow the standard Transact workflow. To complete batch OCR processing, the plugin will automatically communicate with the selected external OCR engine, with no additional action required by the operator.

Import and Export a Batch Class

When importing or exporting a batch class with the Cloud OCR plugin, the system that will be using the batch class needs to have the Cloud OCR plugin and the accompanying web app installed.

Troubleshooting

The following table contains error messages that the administrator may receive if there is an issue with OCR operations.

Note on errors:

  • Errors with the Cloud OCR plugin will show up in the logs. The Cloud OCR plugin log file can be found at:
    • Windows: [Directory]\Ephesoft\Application\dcma-all.log
    • Linux: [Directory]\Ephesoft\Application\catalina.out
  • Errors during batch processing will show up on the Batch Instance Management screen in the Batch Execution Details panel.

Error Messages

 

Error Message Possible Root Cause Resolution
404 Error on ADVANCED_HOCR Plugin Configurations page UI is not running at the expected location. On the Advanced HOCR Generation Engine plugin page, confirm that the UI is running and accessible at the URL specified for “UI URL.” View Transact logs for any related Tomcat failures.
Test Connection Failure: 403 Authorization token has expired. The token expires after 30 minutes (regardless of session being active or inactive). Refresh the page to resolve.
Test Connection Failure: 400 API Key Invalid The Google Cloud Vision API Key is incorrect. Verify the key is valid in the Google Cloud Console.
Test Connection Failure: 500 Service Endpoint is missing or invalid The Service Endpoint URL is incorrect. Set the Service Endpoint URL to the GCV default.

Or, if using on-prem solution, verify the URL is accessible external to Transact.

Save Failed: 403 Authorization token has expired. The token expires after 30 minutes (regardless of the session being active or inactive). Refresh the page to resolve.
Save Failed: 500 An internal API server error occurred.

Or

The API failed to process the file submitted.

Inspect the batch instance runtime files that are being submitted to ensure it is an image within the limitations of GCV. Complex high-res images can result in PNGs that are ~20mb or larger, which will fail during processing due to GCV limits. Consider modifying IMPORT_MULTIPAGE_FILES parameters to resize documents.
Save/Test Failed: 0 API was unreachable.

Or

Plugin setting for API URL is incorrectly configured.

  • Verify the API is accessible at the expected URL (default is /dcma/advancedHocr).
  • Check Transact logs for any Tomcat failures related to “advancedHocr.”
  • Verify the plugin setting for “Advanced HOCR API URL” is correct.

API URL

If you’ve made changes to the port or DNS name for Transact, or you’ve exported the batch class from a different environment (i.e. dev, QA, prod), update the API URL for the API endpoint after the Cloud OCR plugin installer has run.

The API URL can be modified in the plugin_config_sample_value table in the Transact database. Once the batch class is configured with the Advanced_HOCR plugin, the API URL can be modified in the batch_class_plugin_config table for the configured batch class. Note: You do not need to restart Transact after editing the file.

API Key

The web app database stores the API Key as an encrypted value. The encryption key is hard-coded into the API. Here is an example: YjpQ*KuTw!Z67Yg_m!cy7*YJikRtK4.

Was this article helpful to you? Yes No