Automate terminal emulators

Kofax RPA supports connection to a host by a terminal emulator. Configure a terminal emulator based on the host system platform.

To automate a terminal emulator, select from the following list of configurations based on the platform.

Set Command timeouts

Set the command timeout for automating terminals in one of the following ways.

On the Desktop Automation tab of the Design Studio Settings window for executing the workflow in Design Studio.
In the Automation Device section on the Security tab of the RoboServer Settings window for RoboServer execution.

See Runtime > Security in the Kofax RPA Administrator's Guide.

Get fonts

Kofax RPA provides fonts for the terminals to render their screens.

C:\Program Files\Kofax RPA 11.5.0\nativelib\hub\windows-x32\{nnn}\fonts

Where {nnn} is a three-digit number for internal purposes.

If a terminal connection is established with a host that uses characters not in the available fonts, the characters render as squares on the screen. Fix this by adding the path to a TrueType font in fontlist.txt in the same Kofax RPA font directory.

Example: C:\TerminalFonts\MyTerminalFont.ttf

Set SSH authenticate options

When automating applications using the secure shell (SSH) protocol, authenticate users in one of four ways.

Have the SSH client prompt for a password. Enter the password using Enter Text step followed by a Press Key action.
Place an unencrypted private key on the file system of Design Studio and your RoboServers. Add the PublicKeyFile=<path to key> line to the Options field in the Terminal step.
It is important that the key file is PuTTY formatted. On Linux, use puttygen to transform an open-ssh private key.
Place an encrypted private key on the file system of Design Studio and your RoboServers. Add the PublicKeyFile=<path to key> in the Options field. The SSH client prompts for a password. To enter the password, use the Enter Text step followed by a Press Key action.
Use Pageant on Windows and SSH-agent on Linux with an encrypted key on the local file system.
- On Windows, run Pageant as the same user running the RoboServer and add the key.
- On Linux, run ssh-agent and ssh-add.
- Copy the SSH_AUTH_SOCK and SSH_AGENT_PID environment variables to the RoboServer and Design Studio environment.
- Either add the following lines to RoboServer.conf and DesignStudio.conf.
  - set.SSH_AUTH_SOCK=<value as outputted from ssh-agent>
  - set.SSH_AGENT_PID=<value as outputted from ssh-agent>
  Or set the environment variables before starting the RoboServer and Design Studio.

The previous authentication methods are listed from least secure to most secure as follows.

Anyone who reads the robot can extract the password and log onto the system.
An attacker would need the private key from your file system. (If an attacker obtains the robot from a Management Console, it is not enough to gain access.)
An attacker would need both the robot and the private key file.
An attacker would need to obtain the password for the private key to gain access.

Configure Unix, Linux, and Windows (vt100 series and ANSI) terminals

To connect as a stream-based terminal, select Connect (SSH) for the emulator in the Terminal step. The SSH protocol offers both encryption and authentication.

The underlying Kofax RPA SSH client is based on PuTTY and can be configured to access any system that PuTTY can access. Configure all the same parameters as with a PuTTY session, but instead of requiring the PuTTY client to define sessions, define the session settings by adding optional parameters to the Options field.

Connection options

The terminal does not automatically detect a code page on the server. To send and receive non-ASCII characters, you must specify the code page to use for character encoding and decoding. If you do not specify a code page, the robot assumes the server's locale is set to UTF-8.

Specify the code page by using the LineCodePage parameter in the Options field of the robot step.

The Kofax RPA terminal is built using "libicu" for character encoding. Use the libicu converter explorer at http://demo.icu-project.org/icu-bin/convexp?s=ALL to inspect code pages and their aliases. The supported character sets are based on the ICU library. See the ICU documentation for more information.

The following is a list of commonly used parameters for stream-based terminals.

Parameter	Description
TermWidth	Sets the terminal width (default is 80).
TermHeight	Sets the terminal height (default is 24).
AutoWrap	Controls automatic line wrapping (default is N). Set to Y to enable line wrapping. This parameter applies to vr100 (Unix vt100) terminals only.
TerminalType	Sets the terminal type (default is xterm).
LineCodePage	Specifies the code-page to use for character encoding and decoding (default is UTF-8).

To set the parameters on your session, enter them in the Options field for the Terminal step. Separate options with ampersands (&).

The following connection options are supported.

Parameter	Description
SessionFile	Configures the default PuTTY configuration file. If this option is omitted, the session.plink file in the bin directory is used.
PublicKeyFile	Provides an SSH key file for authentication. This file must be in PuTTY private key format.
SSHUser	Overrides the username in the user@host part of the URI. If no user is specified, the robot is prompted interactively.
SSHPassword	Overrides the password in the user:password@host part of the URI. If this option is omitted, the robot is prompted interactively.
SSHHostKey	Configures the SSH host key identifying the host. If this setting is used and the value does not match the host key sent by the host, the connection is rejected. If this setting is omitted and there are no host keys configured through the PuTTY configuration file, the robot is prompted interactively and the robot must handle this dialog to accept the key. Note that the robot ignores settings in the Windows Registry and does not store host keys.
SSHLog	Enables SSH-level logging for troubleshooting purposes.
NetworkTrace	Creates a trace file containing all data exchanged with the host.

Application actions

The Application Action menu is available when you right-click the terminal tab in the Recorder View. The menu includes the following action for stream-based terminals, such as the vt100 series.

Action	Description
Close	Closes the terminal window.

Configure mainframe (tn3270) terminals

To connect as a tn3270 terminal, insert the Terminal step, select Mainframe (tn3270), and specify all necessary parameters, such as host name, connection type, and connection options. Mainframe tn3270 terminals are based on the IBM zSeries platform.

Instead of SSH, tn3270 terminals support SSL and TLS protocols. These protocols encrypt the connection without authentication.

Keyboard support

Kofax RPA by default emulates a 3279-4 color 80x43 terminal, which is the default for the underlying terminal emulator. The legacy tn3270 terminal had a keyboard with special keys that are not available on a standard keyboard. To recreate these keys in a robot, use the following keys in Press Key Calculated Key actions.

VK_RETURN
VK_TAB
VK_BACKTAB
VK_Up
VK_Down
VK_Left
VK_Right
VK_F1
VK_F2
VK_F3
VK_F4
VK_F5
VK_F6
VK_F7
VK_F8
VK_F9
VK_F10
VK_F11
VK_F12
VK_F13
VK_F14
VK_F15
VK_F16
VK_F17
VK_F18
VK_F19
VK_F20
VK_F21
VK_F22
VK_F23
VK_F24
VK_ATTENTION
VK_BACKSPACE
VK_CLEAR
VK_DELETE
VK_DUPLICATE
VK_HOME
VK_INSERT
VK_PA1
VK_PA2
VK_PA3

Character encoding

To specify character encoding for the host, add a charset parameter to the Options field.

Example: charset=cp930

Kofax RPA supports the following character sets for tn3270 terminals.

Character set name	Host code page parameter
belgian	500
belgian-euro	1148
bracket	037
brazilian	275
chinese-gb18030	1388
cp1047	1047
cp870	870
finnish	278
finnish-euro	1143
french	297
french-euro	1147
german	273
german-euro	1141
greek	423
hebrew	424
icelandic	871
icelandic-euro	1149
italian	280
italian-euro	1144
japanese-kana	930
japanese-latin	939
norwegian	277
norwegian-euro	1142
russian	880
simplified-chinese	935
slovenian	870
spanish	284
spanish-euro	1145
swedish	278
swedish-euro	1143
thai	1160
traditional-chinese	937
turkish	1026
uk	285
uk-euro	1146
us-euro	1140
us-intl	037

Terminal emulation

To emulate a different terminal, add a model parameter to the Options field.

Example: model=3279-5

Kofax RPA supports the following terminal models.

Terminal model	Dimensions
3279-2	80x24
3279-3	80x32
3279-4	80x43 (default)
3279-5	132x27

Specify wait time

To specify the wait time for the driver when the host is temporarily unavailable (if the host is unreachable or the connection fails), add the connecttimeout parameter to the Options field, indicating the timeout in seconds.

Example: connecttimeout=5

If this parameter is omitted, the default timeout is 20 seconds.

If the connection fails for reasons that cannot be resolved or the connection attempt cannot be retried, the driver fails immediately.

Application actions

The Application Action menu is available when you right-click the terminal tab in the Recorder View. The menu includes the following actions for tn3270 terminals.

Action	Description
Close	Closes the terminal window.
Go To (row or column)	Moves the cursor to the specified location based on the row or column coordinates used in the application tree. Parameters are optional to allow easy horizontal and vertical movement.

Configure iSeries (tn5250) terminals

To connect as a tn5250 terminal, insert the Terminal step, select iSeries (tn5250), and specify all necessary parameters such as host name, connection type, and connection options. The tn5250 terminals are based on the IBM iSeries platform.

Instead of SSH, the tn5250 terminals support SSL and TLS protocols. These protocols encrypt the connection without authentication.

To use a different port than the default, specify a port in the Host field, such as TerminalHost:11625.

Kofax RPA supports terminals in both 80x24 and 132x27 mode.

Connection options

Connection options are specified in the Options field in the Terminal step. Separate options with ampersands (&). The option string can contain percent (%) escape characters.

The value env.TERM is the client terminal type after the mode is switched by the URL. The default terminal type is "IBM-3179-2." Note that the env.TERM parameter is valid for the tn5250 terminal only.

Kofax RPA supports the following terminal types.

"IBM-3477-FC"
"IBM-3477-FG"
"IBM-3180-2"
"IBM-3179-2" (Default)
"IBM-3196-A1"
"IBM-5292-2"
"IBM-5291-1"
"IBM-5251-11"
"IBM-5555-B01" (DBCS enabled)
"IBM-5555-C01" (DBCS enabled)

Character encoding

To specify character encoding for the host, add a LineCodePage parameter to the Options field.

Example: LineCodePage=cp838

For tn5250 terminals, Kofax RPA supports all EBCDIC code pages supported by the ICU library. The LineCodePage setting must match the code page setting of the terminal emulator used to connect to the host or the value of the QCHRID property of the terminal session.

Frequently used code pages are listed in this table.

Character set name	Host code page parameter
US/Canada	cp037 (default)
Multinational	cp500
Thai	cp838
Japanese	cp930, cp939
Simplified Chinese	cp935
Korean	cp933
EBCDIC 273 with the euro currency update	cp1141

Device assignment

By default the 5250 host either assigns the first available device that is compatible with the requested terminal type or tries to create a new device. If the robot needs to connect to a specific device, add an env.DEVNAME=<device> parameter to the Options field.

Example: To connect to the DEVROBOT device on the iSeries host, add the parameter env.DEVNAME=DEVROBOT

If the requested device does not exist, does not support the terminal type, or is not available (either in use or in a varied off state), the connection fails.

Enhanced interface support

To enable the enhanced interface for non-programmable workstations on the host, add the enhanced=on query parameter to the Options field.

This setting enables support for continued-entry fields.

The DirectDraw Surface windows and graphical features are not supported when the enhanced interface is enabled.

Keyboard support

The legacy 5250 terminal had a keyboard with special keys that are not available on a standard keyboard. To recreate these keys in a robot, use the following keys in Press Key Calculated Key actions.

VK_RETURN
VK_ENTER
VK_TAB
VK_BACKTAB
VK_UP
VK_DOWN
VK_LEFT
VK_RIGHT
VK_CLEAR
VK_BACKTAB
VK_F1
VK_F2
VK_F3
VK_F4
VK_F5
VK_F6
VK_F7
VK_F8
VK_F9
VK_F10
VK_F11
VK_F12
VK_F13
VK_F14
VK_F15
VK_F16
VK_F17
VK_F18
VK_F19
VK_F20
VK_F21
VK_F22
VK_F23
VK_F24
VK_ROLLDN
VK_ROLLUP
VK_BACK
VK_HOME
VK_END
VK_INSERT
VK_DELETE
VK_RESET
VK_PRINT
VK_HELP
VK_SYSREQ
VK_CLEAR
VK_REFRESH
VK_FIELDEXIT
VK_TESTREQ
VK_TOGGLE
VK_ERASE
VK_ATTENTION
VK_DUPLICATE
VK_FIELDMINUS
VK_FIELDPLUS
VK_PREVWORD
VK_NEXTWORD
VK_PREVFLD
VK_NEXTFLD
VK_FIELDHOME
VK_EXEC
VK_MEMO
VK_COPY_TEXT
VK_PASTE_TEXT
VK_NEWLINE
VK_ERASE_EOF
VK_KANJI

For more information, see the manufacturer's 5250 terminal documentation.

To facilitate automation, Kofax RPA provides the following keys.

VK_VIRTUAL_FIELDEXIT

This key functions as VK_FIELDEXIT, but only if the cursor is not in the first position of a field. Use this key either to exit if the field is incomplete or to suppress the exit if the cursor has moved to the next field.
VK_DBCS_SPACE

Types a DBCS space.

Application actions

The Application Action menu is available when you right-click the terminal tab in the Recorder View. The menu includes the following actions for tn5250 terminals.

Action	Description
Close	Closes the terminal window.
Go To (row or column)	Moves the cursor to the specified location based on the row or column coordinates used in the application tree. Parameters are optional to allow easy horizontal and vertical movement.
Enter Field (text)	Enters the specified text in a field and proceeds to the next field using the FieldExit key.

Configure NonStop (tn6530) terminals

To connect as a tn6530 terminal, insert the Terminal step, select Nonstop (tn6530) and specify parameters such as connection type, credentials, and connection options. The tn6530 terminals are based on the Hewlett-Packard Enterprise (HPE) NonStop platform.

Use this configuration only when the host is running on an HPE NonStop platform. For Unix, Linux, and Windows platforms, see Configure Unix, Linux, and Windows (vt100 series and ANSI) terminals.

Kofax RPA emulates a TN6530-8 terminal with an 80x24 display. The terminal starts in conversational mode.

Connection options

Specify connection options in the Options field for the Terminal step. Separate options with ampersands (&). The option string can contain percent (%) escape characters.

Example: NetworkTrace=MyLogfile.log&LineBuffer=2048

The tn6530 Connect action connects to the Telnet service (port 23) unless another port is explicitly specified in the Host field, such as TerminalHost:11625.

The following options are supported.

NetworkTrace=<logfile>

Creates a trace file containing all data exchanged with the host.
ColorMap=<color-map>

Sets the terminal to color support and optionally provides the default color map.
LineBuffer=<lines>

Sets the number of buffered lines for the terminal. These lines are available for paging and scrolling. Valid numbers are 24 to 65536. If not specified, the terminal keeps a buffer of 1024 lines (conversational mode only).

The ssh6530 Connect (SSH) action connects to the SSH service (port 22), unless another port is specified in the Host field, such as TerminalHost:11625. Specify SSH login credentials using the Credentials option in the Terminal step.

The following options are supported.

SessionFile=<template>

Configures the default PuTTY configuration file. If this option is omitted, the default session.plink file in the bin directory is used.
PublicKeyFile=<file>

Provides an SSH key file for authentication. This file must be in PuTTY private key format.
SSHUser=<user>

Overrides the username in the User Name field of the robot step. If no user is specified, the robot is prompted interactively.
SSHPassword=<password>

Overrides the password in the Password field of the step. If this option is omitted, the robot is prompted interactively.
SSHHostKey=<hostkey>

Configures the SSH host key identifying the host. If this setting is used and the value does not match the host key sent by the host, the connection is rejected.

If this setting is omitted and there are no host keys configured through the PuTTY configuration file, the robot is prompted interactively and the robot must handle this dialog to accept the key. Note that the robot ignores settings in the Windows Registry and does not store host keys.
SSHLog=<logfile>

Enables SSH-level logging for troubleshooting purposes.
NetworkTrace=<logfile>

Creates a trace file containing all data exchanged with the host.
ColorMap=<color-map>

Sets the terminal to support color and optionally provides the default color map.
LineBuffer=<lines>

Sets the number of buffered lines for the terminal. These lines are available for paging and scrolling. Valid numbers are 24 to 65536. If not specified, the terminal keeps a buffer of 1024 lines (conversational mode only).

Other options substitute settings in the SessionFile template. Options that are not set in the SessionFile template are ignored.

When creating a log file, the logfile parameters perform the substitutions listed in the following table.

Pattern	Replacement	Example
$P	PID of the process running the robot (value is platform dependent)	12928
$T	UTC time in Unix epoch format	1524649335
$D	Local time in ISO 8601 format	20180425T114215
$H	IP address of the host	127.0.0.1
$P	Port of the host	22
$$	A single dollar sign ($)	$

Keyboard support

The following 6530 keys are supported in protected block mode.

Return, Shift+Return, Ctrl+Return
Home, Ctrl+Home
End
Backspace
Tab, Shift+Tab
Insert, Alt+Insert, Ctrl+Insert
Delete, Alt+Delete, Ctrl+Delete
Alt+2, Shift+Alt+2
Cursor keys
Function keys F1-F16. (For compatibility Alt+F1-F6 are mapped to F11-F16 as well)
6530 function keys: Alt+Up, Alt+Down, PgUp, Alt+PgUp, PgDn, Alt+PgDn

Kofax RPA supports the following 6530 keys in conversational mode.

Return, Shift+Return
Function keys F1-F16. (For compatibility, Alt+F1-F6 are mapped to F11-F16)

In addition, the following keys are supported in Press Key Calculated Key actions.

VK_CLOSE

This key terminates the session and closes the tn6530 terminal.
VK_F11 - VK_F16

These keys provide an alternative to the 6530 Alt+F1 – Alt+F6 key combinations mapped to the F11 – F16 function keys.

Color support

The ColorMap= setting switches the terminal from monochrome to non-configurable color mode. The host can update the color map by sending escape codes. Set up the initial color map in the connection string by providing a string of 32 bytes in hexadecimal format specifying the color mapping for the 32 attribute combinations. For a description of the attribute-to-color mapping scheme, see the manufacturer's 6530 documentation.

Known issues and limitations

Support for conversational mode and unprotected block mode is limited.
Enhanced color support and EM3270 mode are not available.
Commands that perform local operations on a terminal are not supported.

Unsupported escape sequences and keys are tracked through the **ERRORS: marker in the message line.

Application actions

The Application Action menu is available when you right-click the terminal tab in the Recorder View. The menu includes the following actions for tn6530 terminals.

Action	Description
Close	Closes the terminal window.
Go To (row or column)	Moves the cursor to the specified location based on the row/col coordinates used in the application tree. Parameters are optional to allow easy horizontal and vertical movement.