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.

You do not need to install the Desktop Automation Service on your remote computer or create a device mapping in the Management Console when automating a terminal device.

The terminals do not support mouse operations even though the Move Mouse and Click steps can be inserted. The terminals must be operated using keyboard keys.

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.