ABBYY Fine Reader

T-Plan Robot Enterprise Integration With ABBYY Fine Reader

Contents:

1. Overview
2. ABBYY Fine Reader installation
3. Plugin installation and configuration
4. Using ABBYY Fine Reader in Robot

1. Overview

T-Plan Robot Enterprise version 2.3 introduces an optional feature which exposes OCR capabilities of the ABBYY Fine Reader Engine v9.0 in Robot's native scripts. ABBYY Fine Reader Engine (http://finereader.abbyy.com/) is a highly accurate OCR (optical character recognition) software for text recognition.

Robot integrates on the file level with a properly installed and configured Fine Reader Engine v9 installation which is on the same machine as Robot. As the Fine Reader software supports just Microsoft Windows, it can be only integrated with T-Plan Robot Enterprise on Windows. 

2. ABBYY Fine Reader installation

Get the ABBYY Fine Reader Engine v9 software from ABBYY and install it. The software is not available via T-Plan at the moment. Save the Fine Reader serial number for later configuration in Robot. 

3. Plugin installation and configuration

Plugin installation

Unless you already have T-Plan Robot Enterprise version 2.3 or higher, get it from T-Plan and install it. The plugin will not work with versions prior to release 2.3. 

The plugin is distributed in form of a ZIP file which contains two files, abbyy.jar and ABBYY.dll which must be always in the same folder. There are two ways to install the plugin:

  1. Save both files to the <Robot_install_path>/plugins folder (the Robot install path is the folder containing robot.jar). If the plugins/ folder doesn't exist, create it. This will make Robot load the plugin automatically on start up. No installation is necessary. As the plugin will be visible just to this particular Robot installation, this way is recommended for environments which host multiple Robot installations and/or versions. To uninstall the plugin simply remove the file from the plugins/ folder.

or

  1. Extract the files to a permanent location. Then select Tools->Plugins in Robot's GUI, switch to the "Available Plugins" tab, select the "Add JAR, ZIP Or Classpath" button and navigate to abbyy.jar. When the window displays the ABBYY Fine Reader OCR plugin in the table, select it and hit Install. Then restart Robot to apply the changes. 

Be aware that this approach creates an entry in the user plugin map (<user_home>/PluginMap.xml) which is shared across all Robot instances running on the same machine. As prior Robot versions (2.2 and older) can not handle the plugin, they may crash on an attempt to load it. This may be fixed by uninstallation of the plugin through the Plugins window or by deleting the <user_home>/PluginMap.xml file. If you plan on having multiple Robot versions on a single machine, use the first install way described above.

Plugin configuration

To configure the Fine Reader plugin start Robot's GUI, select Edit->Preferences, navigate to Plugins->Image Comparison Modules->ABBYY Fine Reader OCR and configure at least the following settings:

  • The Path to the FREngine.dll file field must be populated with path to FREngine.dll which is typically located in the bin/ folder of ABBYY Fine Reader Engine installation.
  • The Serial Number field must be populated with the ABBYY Fine Reader Engine serial number. It is typically a 20-char sequence like "CCCC-DDDD-DDDD-DDDD-DDDD" where C is a letter and D is a digit.                                                         

It is further recommended to set on the debug mode. This makes Robot print out debug messages into the Windows command prompt which allows to debug eventual issues.

To test whether the plugin is properly configured and works correctly with the ABBYY Fine Reader Engine installation perform the following steps:

  1. Open the Script->Compareto Command window in Robot's GUI.
  2. Set on the Comparison method check box and select abbyy in the drop down.
  3. Review contents of the Language drop down. If it is empty or it contains just the [Not Available] item, the plugin failed to retrieve supported language names from the ABBYY Fine Reader. If you set on the debug mode in the plugin preferences, the Robot's console (command prompt) window will contain a stack trace with the error description and additional details.

4. Using ABBYY Fine Reader in Robot

The Fine Reader OCR capabilities are visible to Robot scripts as a new image comparison method called "abbyy" available with any image comparison command such as CompareTo, WaitFor match/mismatch or Screenshot. The recognized text is then made available to the script in form of variables:

  • _ABBYY_TEXT stores the recognized text (all lines).
  • _ABBYY_LINE_COUNT stores number of recognized text lines.
  • _ABBYY_LINE<number> contains text of the line of the specified number. Numbering starts from 1 (one). For example _ABBYY_LINE1 will contain text of the very first recognized text line.
  • _ABBYY_ERROR  stores text of eventual error message thrown by ABBYY on misconfiguration or an I/O error.

The "abbyy" method accepts a few specific parameters:

  • The "language" parameter specifies the text recognition language. It must be a valid language name recognized by ABBYY. This parameter is optional and defaults to "English" if it is omitted.
  • The "text" parameter allows to specify text to be searched for. When it is specified the plugin searches the recognized text for the specified string and returns success (the exit code of 0) if it is found or fail (non-zero exit code) otherwise.
  • The "pattern" parameter is similar to the "text" one save that the parameter value is handled as a java.util.regex.Pattern compliant regular expression.

If neither "text" nor the "pattern" parameter is present in the command, it returns success (the exit code of 0) if the OCR was executed successfully (even though no text was recognized at all). A non-zero exit code typically indicates a misconfiguration or an internal error. This mechanism may be used to test functionality of the ABBYY integration in a script. An example of such a usage is in the Compareto example below.

Examples:

// Recognize text from the whole screen and record it to the result XML as a step.
// If OCR fails for misconfiguration, record the error and exit the script.
Compareto method="abbyy" language="English"
if ({_EXIT_CODE} == 0) {
  Step "OCR" pass actual="Recognized text: {_ABBYY_TEXT}"
} else {
  Step "OCR" fail actual="OCR failed: {_ABBYY_ERROR}"
 Exit 1 
}

...

// Wait max 10 seconds until the specified screen rectangle contains the "OK" button.
Waitfor match method="abbyy" cmparea="x:65,y:12,w:100,h:100" text="OK" timeout="10s"