Transact

⌘K
  1. Home
  2. Transact
  3. Release Notes and Softwar...
  4. 2019.1
  5. Ephesoft Cloud HyperExtender Plugin 2019.1

Ephesoft Cloud HyperExtender Plugin 2019.1

For newer versions of this plugin, refer to:

Introduction

This document describes how to configure the Ephesoft Cloud HyperExtender plugin for Ephesoft Transact.

The Ephesoft Cloud HyperExtender plugin addresses the heaviest processing needs of the Transact workflow by offloading document splitting and optical character recognition (OCR) processing to the Ephesoft Cloud. This allows the customer to manage temporary spikes in workload without having to add new hardware to on-premise or cloud computing environments.

Note: An Ephesoft Cloud account is required to use the Ephesoft Cloud HyperExtender plugin.

This document describes how to register for an Ephesoft Cloud account, how to configure Transact to connect to the Ephesoft Cloud, and how to configure Ephesoft Transact to use the Cloud HyperExtender plugin.

Technical Notes and Limitations

  • The plugin is only available in the USA.
  • Ephesoft Transact and cloud account creation must be complete, with proper licensing, to configure and use the plugin.
  • The plugin is allotted 1,000 images to be processed per month at no cost for the first 12 months after registration.
    • If further image processing per month is required, please contact our sales team at: sales@ephesoft.com.
  • PDF and TIFF are the only document formats supported.
  • EText extraction is not supported with the Ephesoft Cloud HyperExtender plugin.
  • Web services such as uploadBatch and advancedUploadBatch can be used to upload batches into batch classes that have been configured to use the Cloud HyperExtender plugin.
  • Web services that directly communicate with the OCR process (such as OcrClassify, OcrClassifyExtract, v2/ocrClassifyExtract, v2/ocrClassifyExtractBase64, initiateOcrClassifyExtract, etc.) cannot interact with a batch class that has been configured to use the Cloud HyperExtender plugin.
    For additional information about Ephesoft Transact web services, refer to the following document:

  • The plugin only supports Oracle 11g (11.2.0) and 12c (12.1.0). Configurations must be made to the property file for Oracle to work as expected. Refer to Using Cloud HyperExtender Plugin with Oracle 11g and 12c to perform this workaround. For additional information refer to Platform Configuration and Third-Party Integrations – Transact 2019.1.
  • Although the plugin configuration setting displays a list of languages under OCR Languages, the plugin only supports English documents for OCR processing.
  • The plugin only supports file sizes up to 250MB.
  • The plugin is compatible with Ephesoft Transact servers that are configured with HTTPS when manually configured for Ephesoft Transact. Refer to HTTPS Not Applied to Property Files.
  • If you’re importing a Cloud HyperExtender batch class after you’ve imported it, you must then return to the Cloud HyperExtender plugin and resave your settings.
  • The plugin only supports the following PDF types from an import workflow perspective:
    • Searchable
    • Tabbed
    • PDF/A-1B
    • PDF/A-2b
    • PDF/E
    • PDF/X-4

Registering for and Configuring Ephesoft Cloud

This section describes how to register for an account with Ephesoft Cloud, and how to configure Ephesoft Transact to use the Ephesoft Cloud.

An Ephesoft Cloud account is required to use the Cloud HyperExtender plugin. Only one Ephesoft Cloud account can be associated with an Ephesoft Transact environment, but that same Ephesoft Cloud account can be used for multiple batch classes.

Perform the following steps to configure Ephesoft Transact to use the Cloud HyperExtender plugin:

1. Log in to Transact as an administrator and hover on the menu control on the left side of the application to display the Administrator menu:

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/word-image-59.png

Administrator menu in navigation pane

2. Select System Configuration from the Administrator menu. This displays the Application navigation on the left side of the screen.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/word-image-60.png

Ephesoft Cloud component of the Application menu

3. Select and expand the Ephesoft Cloud component.

This displays the Register and Configure components.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/word-image-61.png

Ephesoft Cloud components

4. Click Register.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/word-image-62.png

Register in the Ephesoft Cloud

The Registration screen appears. Complete the registration.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/word-image-63.png

Ephesoft Cloud Registration screen

This screen has the following fields:

      • First Name — Enter your first name.
      • Last Name — Enter your last name.
      • Email Address — Enter your email address.
      • Company Name — Enter the company name on record with Ephesoft.

5. Select Register.

a. An email containing a temporary password will be sent to you.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/word-image-64.png

Click Complete Registration

b. Click the Complete Registration link in the email and follow the instructions to select a permanent password.

Note: Your new password must be at least 10 characters long, include both uppercase and lowercase letters, include at least one digit, and one special character (i.e., ^ $ * . [ ] { } ( ) ? – ” ! @ # % & / \ , > < ‘ : ; | _ ~ `).

c. After you choose a new password, an email is sent to you containing all the information necessary to configure your connection to the Ephesoft Cloud.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/word-image-65.png

Account ID, User Name and Application Key dialog

Configuring the Ephesoft Cloud Connection

Once you have received your Ephesoft Cloud credentials, perform the following steps to configure Ephesoft Transact to communicate with Ephesoft Cloud.

1. In Transact, navigate to System Configuration > Ephesoft Cloud > Configure. The Cloud Connection Details screen appears.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/word-image-66.png

Ephesoft Cloud HyperExtender Connector screen

2. Complete the fields in the Cloud Connection Details screen using the credentials sent to you via email.

Important: Note that Tenant ID may be referred to as Account ID in the email that was sent to you in the previous section.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/word-image-67.png

Ephesoft Cloud HyperExtender Connector screen (complete the fields shown)

3. Click Save.

4. Click the Edit button if additional changes are needed.

Configuring Ephesoft Transact to use the Ephesoft Cloud HyperExtender Plugin

Once you have used your Ephesoft Cloud credentials to configure your Ephesoft Transact instance to communicate with Ephesoft Cloud, you can configure Transact to use the Ephesoft Cloud HyperExtender plugin.

Important: All document types, index fields, and extraction rule configurations must be completed with the existing plugins before you configure the batch class to use the Ephesoft Cloud HyperExtender plugin.

If you want to configure additional document types, index fields or extraction rules after the Cloud HyperExtender plugin has been configured for a batch class, you will have to turn off the Cloud HyperExtender plugin from your batch class and replace the original plugins before doing any additional document type, index field or extraction rule configuration.

The Cloud HyperExtender plugin is placed in the Folder Import module and replaces the functionality from a number of existing plugins in the Folder Import and Page Processing modules. To configure a batch class to use the Cloud HyperExtender plugin, you will remove those existing plugins and replace them with the new Cloud HyperExtender plugin.

Perform the following steps to configure your batch class to work with the Cloud HyperExtender plugin:

1. Log in to Ephesoft Transact and navigate to the Batch Class Management screen.

2. Open the desired batch class for editing.

3. Edit the Folder Import and Page Process modules as follows:

a. Remove the following two plugins from the Folder Import module:

      • IMPORT_MULTIPAGE_FILES
      • IMPORT_BATCH_FOLDER

Folder Import Module plugins

b. Remove the following plugins from the Page Process module:

      • CREATE_OCR_INPUT
      • RECOSTAR_HOCR, NUANCE_HOCR or TESSERACT_HOCR (your OCR engine plugin will depend on how your batch class is configured)
      • CREATE_DISPLAY_IMAGE
      • CREATE_THUMBNAILS

Page Process Module plugins

4. Add the CLOUD_HYPEREXTENDER_PLUGIN to the Folder Import module.

CLOUD_HYPEREXTENDER_PLUGIN

5. Save and deploy your changes by clicking the Apply button, then clicking the Deploy button.

6. Select and expand the CLOUD_HYPEREXTENDER_PLUGIN node and click Configure. The Ephesoft Cloud HyperExtender configuration screen is displayed.

Ephesoft Cloud HyperExtender > Configure Screen

USA is the only option available in the Data Center list, and OCR+ is the only option available in the Product list.

English is selected by default in the OCR Languages list and is the only language supported for OCR processing despite the other languages that are displayed in this list. Once English is selected, click Save.

Note: The plugin auto-rotates images upon importing to a batch class.

Your batch class is now ready to start processing documents using the Ephesoft Transact Cloud HyperExtender plugin. Create a batch instance using this batch class and verify that the batch is processed successfully.

Optimizing Property Files

The following two properties files in Ephesoft Transact contain settings that can be adjusted to achieve higher performance and increase throughput.

Important: If you make any changes to either of these following two properties files, you must restart the Ephesoft Transact service.

Note: Ephesoft Transact contains two files by the name of application.properties. This document only discusses the application.properties file for the Cloud HyperExtender plugin.

dcma-workflows.properties File

This file is located in the following path:

<Installation Directory>/Application/WEB-INF/classes/META-INF/dcma-workflows/dcma-workflows.properties

This file contains properties that allow you to increase the number of parallel batch processing for optimizing cloud operations:

#server.instance.max.process.capacity.mode governs the calculation of server.instance.max.process.capacity value.
#0 means calculation will be dynamic that depends on system configurations and results of performance testing.
#1 means calculation will static and value will be picked from the property server.instance.max.process.capacity
server.instance.max.process.capacity.mode=0
server.instance.max.process.capacity=5

Changing the server.instance.max.process.capacity.mode from 0 (default) to 1 and setting the service.instance.max.process.capacity can increase the number of parallel batches processing that can occur.

  • For smaller batches (roughly 100 pages per batch) Ephesoft recommends setting the server.instance.max.process.capacity value between 15 and 20 for maximum performance. This number should be reduced to 5 (the default setting) when you are only processing on-premise.
  • For mid-range or larger batches (roughly 1000 pages per batch), Ephesoft recommends that you keep the default setting for server.instance.max.process.capacity.

application.properties File

This file is located in the following path:

C:\Ephesoft\JavaAppServer\webapps\ephesoft-cloud-client\WEB-INF\classes\application.properties

This properties file has the following configuration that can improve performance in cloud operations:

# Upload/Download Action
cloud.action.upload-download.thread-count=10

This value can be used to increase or decrease the number of pages or files that can be downloaded or uploaded at a time, from the cloud onto a Transact instance. If you encounter any decrease in performance, you can decrease this thread-count number to be less than 10.

Ephesoft Cloud Portal

You can log in to the Ephesoft Cloud portal (https://transact.us.ephesoftcloud.com) to view how many images you have processed with the Cloud HyperExtender plugin.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/word-image-80.png

Ephesoft Cloud Portal

Troubleshooting

Log File

The log file for the Ephesoft Cloud HyperExtender plugin is available in the following location:

<Ephesoft Installation Folder>/JavaAppServer/webapps/ephesoft-cloud-client/WEB-INF/classes/log/cloud-client.log

Incomplete Registration

If you attempt to configure the Cloud HyperExtender plugin with invalid connection details, the following error message appears:

Ephesoft Cloud registration is incomplete. Please ask your system administrator to register first.

If this problem occurs, contact your Transact system administrator.

Test Classification and Extraction

When the Ephesoft Cloud HyperExtender plugin is configured and enabled within a batch class, the Test Classification and Test Extraction actions will not work in that batch class. The following error message will be displayed:

Error occurred while breaking multipage tiff or pdf.

This error is expected, as these actions are not supported in batch classes that are configured to use the Ephesoft Cloud HyperExtender plugin.

Saving the Cloud HyperExtender Configuration

If a cloud-enabled batch fails, ensure that you have saved the Ephesoft Transact Cloud HyperExtender configuration in the respective batch class.

1. Open the batch class.

2. Navigate to Modules > Folder Import > CLOUD_HYPEREXTENDER_PLUGIN > Configure.

The Ephesoft Cloud HyperExtender configuration screen is displayed.

Ephesoft Cloud HyperExtender > Configure Screen

3. Ensure that the plugin is configured and enabled and that you click Save to retain changes.

HTTPS Not Applied to Property Files

If your Cloud HyperExtender batches fail with error message, “I/O error on POST request for “http://…” (via the Batch Execution details pane in the Batch Instance screen), and Ephesoft Transact is installed as HTTPS, perform the workaround below to correct the error and change the property files. The same error can be seen in greater detail in the dcma-all.log (located in the following path:<Transact-Installation-Folder>/Application/logs/).

  1. Open the application.properties file in the following path:

<Transact Installation Folder>/JavaAppServer/webapps/ephesoft-cloud-client/WEB-INF/classes

  1. Locate the following property: cloud.notification.transact-hybrid url.
  2. Change the property from http://localhost:8080/dcma/ws/hybridplugin/status/notify to https://localhost:<port number>/dcma/ws/hybridplugin/status/notify.
  3. Open the cloud-plugin.properties file in the following path:

<Transact Installation Folder>/Application/WEB-INF/classes/META-INF/cloud-plugin/

  1. Locate the following property: cloud.client.url
  2. Change the property from http://localhost:8080/ephesoft-cloud-client to https://localhost:<port number>/ephesoft-cloud-client.
  3. Restart the Ephesoft Transact service.
  4. If you have a multi-server environment, repeat steps 1 – 7 for all Ephesoft Transact nodes in your cluster.

Using Cloud HyperExtender Plugin with Oracle 11g and 12c

To use Cloud HyperExtender Plugin with Oracle 11g and 12c, follow the steps below to configure the applications.properties file so that the plugin works as expected.

  1. Open the properties file in the following path:

<Ephesoft_Installation_Directory>\JavaAppServer\webapps\ephesoft-cloud-client\WEB
INF\classes\application.properties

  1. Under the ## Data Source configurations section, make the following changes for the options below:
    • spring.jpa.properties.javax.persistence.schema-generation.create-source=metadata
    • spring.jpa.properties.javax.persistence.schema-generation.scripts.action=create
    • spring.jpa.properties.javax.persistence.schema-generation.scripts.create-target=$<EPHESOFT_HOME>/JavaAppServer/webapps/ephesoft-cloud-client/WEB-INF/classes/schema.sql
    • spring.datasource.initialization-mode=always
    • spring.datasource.continue-on-error=true
  1. Restart the Ephesoft Transact service.
  2. If you have a multi-server environment, repeat steps 1 – 3 for all Ephesoft Transact nodes in your cluster.