Automate Terminals

Kofax RPA supports connection to and interaction with 3270, 5250, 6530, and stream-based (vt100 and ANSI) terminals.

Command timeout for automating terminals is set either on the Desktop Automation tab of the Design Studio Settings window for executing the workflow in Design Studio, or 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.

Fonts

Kofax RPA bundles several fonts for the terminals to render their screens. They are located at:

C:\Program Files\Kofax RPA 11.3.0\nativelib\hub\windows-x32\XXX\fonts

Where XXX is a three-digit number for internal purposes.

If a terminal connection is established with a host that uses characters that are not found in the bundled fonts, the characters render as squares on the screen. This can be fixed by adding the path to a Truetype font in the fontlist.txt file found in the same Kofax RPA font directory. For example:

C:\TerminalFonts\MyTerminalFont.ttf

tn6530 terminals

To connect to 6530 terminals, insert the Terminal step, select Nonstop (tn6530) and specify all necessary parameters, such as connection type, credentials, and connection options.

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

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 as well)

In addition, the following Calculated Keys are supported:

• 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.

Connection options

Connection options are specified in the Options field of the Terminal step. Options are divided by ampersand (&). The option string can contain percent (%) escape characters.

For 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/scrolling. Accepted values are between 24 and 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 explicitly specified in the Host field, such as TerminalHost:11625. SSH login credentials can be specified 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 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>

  SSH user. This setting overrides the username in the User Name field of the step. If no user is specified, the robot is prompted interactively.

• SSHPassword=<password>

  SSH password. This setting 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>

  Enable 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 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/scrolling. Accepted values are between 24 and 65536. If not specified, the terminal keeps a buffer of 1024 lines (conversational mode only).

Any other options are used to substitute settings in the SessionFile template. Options that are not set in the SessionFile template are ignored.

The logfile parameters perform the following substitutions when creating a log file:

Pattern	Replacement	Examples
$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 ($).	$

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. The initial color map can be set up in the connection string by providing a string of 32 bytes in hexadecimal format specifying the color mapping for the 32 attribute combinations. See the 6530 documentation for a description of the attribute-to-color mapping scheme.

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 the 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 items for the tn6530 terminals.

Action	Description
Close	Closes the terminal window.
Go To(row, col)	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.

tn5250 Terminals

To connect to 5250 terminals, insert the Terminal step, select iSeries (tn5250), and specify all necessary parameters, such as host name, connection type and connection options. To use a port different from default, specify it in the Host field, such as TerminalHost:11625.

Connection options

Connection options are specified in the Options field of the Terminal step. Options are divided by ampersand (&). The option string can contain percent (%) escape characters.

env.TERM is the value of the client terminal type after the mode is switched by the URL. The default terminal type is "IBM-3179-2". Note that 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)

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

The 5250 terminal used a special keyboard with many keys that are not available on present day PC keyboards. To enter such keys, use the following calculated keys in the Press Key.

• 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

See the 5250 terminal documentation for more information.

To facilitate automation, Kofax RPA has added the following keys:

• VK_VIRTUAL_FIELDEXIT

  This key functions as VK_FIELDEXIT, but only if the cursor is not at the first position of a field. This can be used to exit a field if it is not completely filled, but suppress the FieldExit if the cursor has just wrapped to the next field.

• VK_DBCS_SPACE

  Types a DBCS space.

Character Encoding

To specify character encoding of the host, add a LineCodePage parameter to the Options field. For example: LineCodePage=cp838

For tn5250 terminals, Kofax RPA supports all EBCDIC codepages 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.

Some frequently used code pages are listed in this table.

Character set	Host codepage
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 assigns the first available device that is compatible with the requested terminal type or try to create a new device. If the robot needs to connect to a specific device add a env.DEVNAME=<device> parameter to the Options field. For example, to connect to the DEVROBOT device on the iSeries host:

env.DEVNAME=DEVROBOT

If the requested device does not exist or does not support the terminal type, or if the device is varied off/in use, the connection fails.

Enhanced 5250 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.

Application actions

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

Action	Description
Close	Closes the terminal window.
Go To(row, col)	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.
Enter Field(text)	Enters the specified text in a field and proceeds to the next field using the [FieldExit] key.

3270 Terminals

Kofax RPA supports 3279-4 color 80x43 terminal, which is the default of the underlying terminal emulator.

The 3270 terminal used a special keyboard with some keys that are not available on present day PC keyboards. To enter such keys, the following calculated keys may be used in the Press Key.

• 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 of the host, add a charset parameter to the Options field. For example:

charset=cp930

Kofax RPA supports the following character sets for tn3270 terminals:

Character name	Host codepage
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

connecttimeout

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

connecttimeout=5

When this parameter is omitted, the driver waits for 20 seconds.

If the connection fails for reasons that cannot be resolved or the connection attempt cannot be retried (that is the host name cannot be resolved), 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 items for the tn3270 terminals.

Action	Description
Close	Closes the terminal window.
Go To(row, col)	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.

SSH / Telnet Settings (vt100 and ANSI)

To use SSH connection, select Connect (SSH) for the emulator in the Terminal step. The underlying Kofax RPA SSH client is based on PuTTY and can potentially be configured to access any system that PuTTY can access. You can configure all the same parameters as you can with a PuTTY session, but instead of requiring the actual PuTTY client to define sessions, you can define session settings by adding optional parameters to the Options field.

The headless terminal does not automatically detect the code page on the server. This is why sending and receiving non-ASCII characters requires you to 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. You can specify the code page by using the LineCodePage parameter in the Options field of the 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 list of supported character sets equals that of ICU (International Components for Unicode) library. See ICU documentation for details.

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

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 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 of the Terminal step. Options are divided by ampersand (&).

The following connection options are supported.

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	This setting overrides the username in the user@host part of the URI. If no user is specified, the robot is prompted interactively.
SSHPassword	This setting 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	Enable 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 items for the vt100 terminals.

Action	Description
Close	Closes the terminal window.

SSH Authentication and Security Guide

When automating applications using SSH, the user can be authenticated in four different ways.

1. The underlying ssh client will prompt for a password. Enter the password using "Enter Text" step followed by a "Press Key" step (return).
2. An unencrypted private key can be placed on the file system of Design Studio and your RoboServers. Add the PublicKeyFile=<path to key> line to the Options field of the Terminal step.

   It is important that the key file is PuTTY formatted. On Linux you can use puttygen to transform an open-ssh private key.

3. An encrypted private key can be placed on the file system of Design Studio and your RoboServers. Add PublicKeyFile=<path to key> to the Options field. The underlying ssh client should prompt for a password upon connection. To enter the password, use "Enter Text" step followed by a "Press Key" step (return).
4. 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 and copy the SSH_AUTH_SOCK and SSH_AGENT_PID environment variables to the RoboServer and Design Studio environment. You can do it by appending the lines to RoboServer.conf and DesignStudio.conf as follows.

     • set.SSH_AUTH_SOCK=<value as outputted from ssh-agent>
     • set.SSH_AGENT_PID=<value as outputted from ssh-agent>

     Or by setting the environment variables before starting the RoboServer and Design Studio.

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

1. Anyone able to read the robot can extract the password and log onto the system.
2. The attacker would have to have the private key from your file system, so obtaining the robot from a Management Console is not enough.
3. The attacker would need both the robot and the private key file.
4. The attacker would need to obtain the password for the private key to gain access.

Use TLS/SSL

Kofax RPA supports TLS/SSL communication in terminals. To use TLS/SSL, use either stn3270 or stn5250 terminal in the Terminal step, specify the host name or IP address with an appropriate port number and select Secure Connection. Note that Kofax RPA does not verify the certificate presented by the server.