9.1

Edit

OCR Release 8.4.0

Overview

  • trainPattern, processImage and processDocument are affected: patternName is passed by content, not by file name.
  • processImage and processDocument are affected: instead of patternName=default should use useDefaultPattern=true.
  • jwt authentication is used instead of basic authentication.

Configuration

This section provides information on configuration changes in 8.4.0, 8.4.1 and 8.4.1.1 versions of OCR for SPA.

Sample application.properties files

These are fragments of application.properties files for ocr-rest and ocr-worker modules, respectively. They contain only properties, related to changes in 8.4.0, 8.4.1, 8.4.1.1 . Some comments for the properties are included. More details you can find in the following subsections.

application.properties for ocr-rest

# Active profiles specification
# Exactly one profile per one of the three groups should be specified: *-auth, *Queue, *-storage .
# mongo-task and abbyy are mandatory for SPA
spring.profiles.active=basic-and-jwt-auth,mongoDbQueue,gridfs-storage,mongo-task,abbyy

# Properties for JWT authentication, is used with basic-and-jwt-auth and jwt-auth profiles. The secret should match the one in WorkFusion configs.
jwt.secret=your_secret
jwt.expiration.minutes=60
jwt.issuer=workfusion

# Properties for Basic authentication, is used with basic-and-jwt-auth or basic-auth profiles.
spring.security.username=your_username
spring.security.password=your_password

# Root folder to keep task input and output files (either in GridFS or in S3, depending on the active file storage profile).
ocr.tasks.abbyy.storage.folder=abbyy_tasks
# S3 bucket name to store input and putput files.
ocr.bucket=your_bucket

# Engine configuration was moved from ocr-worker to ocr-task, otherwise it is configured as previously.
ocr.task.sn=SWAT-....
ocr.task.engine.dll.folder=/opt/ABBYY/FREngine11/Bin
ocr.task.engine.data.folder=/opt/ocr/tmp-engine
ocr.task.engine.temp.folder=/opt/ocr/tmp-engine

# Default timeout for single recognition task in seconds: 3 hours. Can be overridden by timeout parameter of processImage request.
ocr.process.timeout=10800

# Command to be used to retrieve ABBYY FREngine license information.
ocr.rest.command=["java","-Xmx1024m","-classpath","ocr-rest.jar","-Dloader.main=com.wf.ocr.LicenseApplication","org.springframework.boot.loader.PropertiesLauncher","$CONFIG"]
# Timeout for the LicenseApplication process
ocr.rest.timeout=5
# Number of retries for the LicenseApplication process
ocr.rest.retries=2

application.properties for ocr-worker

# In contrast with ocr-rest, *-auth and mongo-task profiles are not needed.
# Authenitcation is inapplicable and mongo-task is applied by default.
# Other profiles should match those in ocr-rest.
spring.profiles.active=mongoDbQueue,gridfs-storage,abbyy

# Root folder to keep task input and output files (either in GridFS or in S3, depending on file storage profile).
# Should match the one in ocr-rest.
ocr.tasks.abbyy.storage.folder=abbyy_tasks

# S3 bucket name to store input and putput files.
# Should match the one in ocr-rest.
ocr.bucket=your_bucket

# JSON representation of a command to be used to start ocr-task.
ocr.task.command=["java","-Xmx3072m","-jar","ocr-task.jar","$CONFIG"]

Profiles

You need to configure profiles for OCR Service. In 8.4.0 (8.4.1) number of required profiles changed from 2 to 4 (5). Consider the following set of profiles as a basis for your changes:

spring.profiles.active=basic-and-jwt-auth,mongoDbQueue,gridfs-storage,mongo-task,abbyy

You specify profiles in spring.profiles.active property in application.properties of both ocr-rest and ocr-worker modules. There are five groups of profiles for OCR Service. There should be specified exactly one profile per group. So for version 8.4.1+ there should be always specified five profiles. For version 8.4.0, there should be specified the same groups except authentication.

The profile groups are:

  • Authentication type (since 8.4.1+ only)
  • Queue backend
  • File storage backend
  • Task storage and processing strategy
  • OCR backend (abbyy only)
note

ocr-worker and ocr-rest should be set up consistently: they should have the same queue, file storage and task storage profiles. ocr-worker does not require authentication type and task storage and processing strategy profiles to be configured.

Authentication type profiles

Supported starting from version 8.4.1. For 8.4.0 jwt-auth is the only available option. The profile is specified in application.properties for ocr-rest. ocr-worker does not require authentication type profile specified.

There are four profiles that define an authentication type to apply:

  • disabled-auth: authorization is not done for OCR Service, all resources are accessible anonymously (without authentication).
  • basic-auth: basic authentication is done, some resources are accessible anonymously, the others require authentication.
  • basic-and-jwt-auth: both basic and JWT authentication are available, some resources are accessible anonymously, the others require authentication. (version 8.4.1.1+ only, see OCR-188).
  • jwt-auth: JWT authentication is done, all resources require authentication (except for the root path: /).

Basic authentication additionally requires user name and password to be configured in application.properties of ocr-rest:

spring.security.username=your_username
spring.security.password=your_password

JWT authentication additionally requires JWT secret, issuer and token expiration time to be configured in application.properties of ocr-rest:

jwt.secret=your_jwt_secret
jwt.expiration.minutes=60
jwt.issuer=workfusion

Queue backend profiles

There are two profiles that define queue backend:

  • mongoDbQueue: MongoDB is used to store message queue. MongoDB connection configuration properties should be specified.
  • rabbitmqQueue: RabbitMQ is used to store message queue. RabbitMQ connection configuration properties should be specified.

The profile and the properties should be specified for ocr-rest and ocr-worker consistently.

File storage backend profiles

In 8.4.0, a new backend for file storage, S3, was introduced.

There are two profiles that specify a file storage backend to use, a technology to store OCR input and output payload:

  • gridfs-storage: files will be stored in MongoDB. MongoDB connection configuration properties should be specified.

  • s3-storage: files will be stored in Amazon S3. ocr.bucket property should be specified additionally.

Example for S3 for ocr-rest:

spring.profiles.active=basic-and-jwt-auth,mongoDbQueue,s3-storage,mongo-task,abbyy
# Root folder to keep task input and output files (either in GridFS or in S3, depending on the active file storage profile).
ocr.tasks.abbyy.storage.folder=abbyy_tasks
# S3 bucket name to store input and putput files.
ocr.bucket=your_bucket

The profile and the properties should be specified for ocr-rest and ocr-worker consistently.

Task storage and processing profile

These are two profiles that specify how OCR tasks are stored and processed:

  • mongo-task: task metadata is stored in MongoDB and tasks are processed asynchronously. It must be always specified for SPA. This is a mode how OCR Service operated prior to 8.4.0. MongoDB connection configuration properties should be specified. File storage and queue profiles are required. It should be explicitly activated in ocr-rest, and it's optional in ocr-worker.
  • in-memory-task: tasks are stored in memory of ocr-rest process together with payload and are process synchronously. It must be always specified for RPA Express. File storage and queue profiles are not needed. This is a newly added mode in version 8.4.0.

OCR backend profile

Currently, the only supported OCR backend is ABBYY FREngine. You must activate it with abbyy profile in both ocr-rest and ocr-worker.

FREngine parameters

The following engine parameters were excluded from ocr-worker/application.properties and added to ocr-rest/application.properties:

ocr.task.sn=SWAT-....
ocr.task.engine.dll.folder=/opt/ABBYY/FREngine11/Bin
ocr.task.engine.data.folder=/opt/ocr/tmp-engine
ocr.task.engine.temp.folder=/opt/ocr/tmp-engine

OCR task execution and timeouts

Previously ocr-task process was started by appropriate shell script. Starting with version 4.8.0 the command to start process is defined in ocr.task.command property as a JSON array: a java command and its arguments. The path to the input file is marked as "$CONFIG". This value is replaced at run-time by ocr-rest. The property is defined in application.properties for ocr-worker:

ocr.task.command=["java","-Xmx3072m","-jar","ocr-task.jar","$CONFIG"]

The executable file lookup (java) is done according to normal rules for a file. By default it's done according to $PATH. If the path contains slashes, it will be considered relative or absolute, appropriately. You need to be sure that the java version on $PATH is 8.

Timeout is defined in application.properties in ocr-rest. In properties defined only the default timeout. It can be overridden in processImage or processDocument requests by timeout parameter.

application.properties for ocr.rest:

ocr.process.timeout=10800

LicenseApplication execution and timeouts

To improve stability of retrieval of ABBYY FREngine license information was extracted to a separate process in 8.4.0. The process is configured in a similar manner to ocr-task:

# Command to be used to retrieve ABBYY FREngine license information. 
ocr.rest.command=["java","-Xmx1024m","-classpath","ocr-rest.jar","-Dloader.main=com.wf.ocr.LicenseApplication","org.springframework.boot.loader.PropertiesLauncher","$CONFIG"] 
# Timeout for the LicenseApplication process 
ocr.rest.timeout=5 
# Number of retries for the LicenseApplication process 
ocr.rest.retries=2

The difference from ocr.task.command is that LicenseApplication class is started indirectly by PropertiesLauncher because we use nested jars. Additionally, you can configure process execution timeout and number of retries in a case of failure. 2 retries means that there will be totally 3 attempts to run the process before propagating the failure to the response. There overall execution time will be 5 * 3 seconds.

Logs are written to the rest/ocr-license.log file with rotation. Logging configuration is analogous to that of ocr-task and is separate from the rest logging of ocr-rest.

Maven configuration

SPA version should be built with a Linux profile in Maven:

mvn clean package -DskipTests=true -Plinux
← PreviousNext →