T-Plan Robot Enterprise Integration With ABBYY Fine Reader
Contents
1. Overview
3. ABBYY Fine Reader installation
2. 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. There is no way to get the software through 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:
- 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
- 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:
- Open the Script->Compareto
Command window in Robot's GUI.
- Set on the Comparison method
check box and select abbyy in the
drop down.
- 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"