Kofax RPA supports connection to and interaction with 3270, 5250, 6530, and stream-based (vt2xx) 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 Desktop Automation 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 10.4.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, use one of the following connection strings:

For a Telnet connection:

tn6530://<host>[:<port>][?<options>]

For an SSH connection:

ssh6530://[<cred>@]<host>[:<port>][?<options>]

Where host is the host name or IP address, port is the terminal connection port number, and options is a list of connection options in the form of key =value pairs, separated by an ampersand (&) character. The optional cred provides credentials for the SSH connection.

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

The connection string is in generic URI format and can contain percent (%) escape characters.

The tn6530: connection string connects to the Telnet service (port 23) unless another port is explicitly specified.

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: connection string connects to the SSH service (port 22) unless another port is explicitly specified.

SSH login credentials in the URI can be specified as either <user>@ or <user>:<password>@ prefix to the hostname, or through the URI options.

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@host part of the URI. If no user is specified, the robot is prompted interactively.

• SSHPassword=<password>

  SSH password. 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=<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 URI 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.

tn5250 Terminals

To connect to 5250 terminals, use the following connection string:

tn5250://<hostname>:<portnumber>?env.TERM=<terminal type>.

Where hostname is the terminal name or IP address, portnumber is the terminal connection port number, and 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 Step.

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

See Basic Terminal Tutorial for information on how to connect to and extract information from a 5250 terminal.

Character Encoding

To specify character encoding of the host, add a charset query parameter to the URI. For example:

tn5250://hostname:port?LineCodePage=cp838

Kofax RPA supports the following character sets for tn5250 terminals:

Character name	Host codepage
US/Canada	cp037 (default)
Multinational	cp500
Thai	cp838
Japanese	cp930
Simplified Chinese	cp935
Korean	cp933

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> query parameter to the URI. For example, to connect to the DEVROBOT device on the iSeries host:

tn5250://iSeries:port?env.TERM=IBM-3477-FC&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 URI. For example:

tn5250://hostname:port?LineCodePage=500&enhanced=on

This setting enables support for continued-entry fields.

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

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

• 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 query parameter to the URI. For example:

tn3270://hostname:port?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

SSH / Telnet Settings (vt2xx)

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 parameters to the connection URL.

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. 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.
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, append them to the URI when you enter the value into the Open step.

ssh://<username>@<hostname>?TermWith=160&TermHeight=48&LineCodePage=UTF-16

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.

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 connection URL. The connection URL could look like the following.

   ssh://<username>@<hostname>?PublicKeyFile=<path to key file>

   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 connection URL. 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 having them already in your environment when 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, open either stn3270 or stn5250 terminal in the open step of the Desktop Automation Workflow. For example, stn3270://hostname:2023. Note that Kofax RPA does not verify the certificate presented by the server.