Skip to content

User Guide

Overview

Companies running their core Systems of Record on IBM i (formerly known as AS400 or iSeries) platform often find themselves at the mercy of their application vendors when it comes to integrating these applications or automating manual user actions. InfoConnect Hub RPA is a simple automation application that operates directly as a standalone application within the InfoConnect Hub environment, simulating user actions on a green screen, including navigation, data entry, and screen capture.

Use Cases

There are several options for integrating and automating IBM i based applications. Robotic Process Automation (RPA) is a good fit for companies that only have access to the application via green screen UI and have limited capabilities integrating directly at application program or DB level. If users have to manually key in the data into legacy system this is a good opportunity to automate this step.

Another often overlooked scenario where RPA can help a lot is test automation. In many cases companies have to run through manual feature and regression testing every time the change is introduced. Automating this regression testing step could help improve the quality of the releases and reduce a risk of introducing the unintended changes in system behavior.

Product Features

  • Automates manual green screen operations and easily exposes legacy IBM i applications as modern APIs
  • Simulates green screen user actions directly from applications
  • Focuses on one simple thing: automating user screen navigation and data entry for IBM i screen (tn5250) applications
  • Supports simple python based script language for more advanced screen navigation logic
  • Supports TLS (encrypted) connections

How does it work?

Infoview's InfoConnect Hub RPA is a simple application that opens IBM i telnet (5250) session, executes a sequence of user actions to navigate the screens, type the data into display fields, press function keys, read sections of the screen into the variables, etc.

InfoConnect Hub RPA works as a standalone open-source application.

The connection configuration includes the credentials and initial set of keystrokes that every session will execute to get to the starting point in the screen navigation (for example navigate to Order Entry screen)

The executeScript operation executes the script (a series of keystrokes, macro executions etc) then passess the resulting variables back to the application.

IBM i requirements

  • Any IBM i OS version is supported.

Quick Start Guide

  1. Contact Infoview to get the RPA hub distribution package or launch the RPA hub from the participating marketplaces such as AWS Marketplace

  2. Download and run the RPA hub on any Java supported on-prem or cloud infrastructure. Note the RPA hub must be able to reach the target IBM i ports.

java -Djasypt.encryptor.password=password -jar info_connect_rpa_hub-3.0.0.jar

  1. Once the RPA hub instance is running, and security rule allows access to port 8082 of the newly launched instance, use Postman or CURL or any other REST API client to configure and test the IBM i scripts, referencing the API documentation below. The default API authentication is a basic auth.

  2. Verify that the instance is running, using GET http://<host>:<port>/rpa/admin/connections. You should receive an empty array of connections (as no connections have been configured yet).

  3. Configure new IBMi (AS400, iSeries) connection using POST http://<host>:<port>/rpa/admin/connections with the sample request similar to below:


{
   "connectionName" : "test",
   "host":"your-as400-host",
   "port":"your-as400-port",
   "userName":"username",
   "userNameXPosition":"X coordinates of the cursor to enter username",
   "userNameYPosition":"Y coordinates of the cursor to enter username",
   "password":"encrypted-password",
   "passwordXPosition":"X coordinates of the cursor to enter password",
   "passwordYPosition":"Y coordinates of the cursor to enter username",
   "initialKeyString": "addlible apanda,[enter],[enter],addlible infocdccom,[enter],[enter]",
   "sslType":"TLS",
   "reconnectionAttempts":"1",
   "timeBetweenAttempts":300,
   "debugMode":"true"
}
  1. Verify the connection is successful by GET http://<host>:<port>/rpa/admin/connections - now it should show the connection details for the newly created connection, with the status OPEN.

RPA Call definitions

Endpoint root: /admin/rpa-calls

Method Path Notes
POST /admin/rpa-calls Register a new RPA Call definition
PUT /admin/rpa-calls/{rpaCallDefinitionName} Update an existing definition
DELETE /admin/rpa-calls/{rpaCallDefinitionName} Delete definition
GET /admin/rpa-calls/{rpaCallDefinitionName} Get one definition
GET /admin/rpa-calls List all definitions

Minimal create example

{
  "connectionName": "connectionName",
  "rpaCallDefinitionName": "rpaCallDefinitionName",
  "uri": "uri",
  "keyString": "keyString",
  "rpaCallParameters": {
    "params": [
        {
            "parameterName": "orderId",
            "sourceFieldName": "orderId",
            "length": 8
        },
        {
            "parameterName": "items",
            "sourceFieldName": "items",
            "length": 2,
            "macroParameter": true,
            "dataStructureElements": [
            {
                "parameterName": "ItemNo",
                "sourceFieldName": "ItemNo",
                "length": 35
            },
            {
                "parameterName": "ItemName",
                "sourceFieldName": "ItemName",
                "length": 11
            },
            {
                "parameterName": "Quantity",
                "sourceFieldName": "Quantity",
                "length": 14
            },
            {
                "parameterName": "UnitPrice",
                "sourceFieldName": "UnitPrice",
                "length": 14
            }
            ]
        }
        ]
    },
  "macroTransportConfig": {
    "macroFileName": "macroFileName.py",
    "macroFileProtocol": "FILE",
    "transportConfig": {
      "FILE": { "filePath": "filePath" }
    }
  }
}

RPA Call Operation

Property Description Required Default Value
Key String Sequence of key strokes, functional keys, literals, variables, or special commands, that represents the user actions on the screen. For a list of valid commands and keys please reference a detailed section below Required
RPA Call Parameters Mapping for the input parameters Required Default Value
Macro File Name of the Macro file (Python script)
Macro Input Parameters Name and value of the input variables passed into Macro script. It should be added to the RPA Call parameters with "macroParameter": true.

Execute a Registered RPA Call

When an RPA Call is registered with e.g. uri = "orderStatus", the hub automatically exposes it under the same relative path.

POST /orderStatus

{ "orderStatus": "Picked" }

Returns the values captured by [GET_SCREEN … orderStatusNew] in the definition.

Macro Transport Options

Protocol Required fields in transportConfig
FILE filePath – absolute or relative path on the hub host
S3 s3Bucket, s3Region, s3AccessKey, s3SecretKey
FTP ftpHost, ftpDirPath, ftpUserName, ftpPassword
HTTP httpUrl, httpDirPath, httpUserName, httpPassword

Typical Workflow

  1. Encrypt secrets with /admin/encryption.
  2. Create a connection (/admin/connections).
  3. Create an RPA Call (/admin/rpa-calls).
  4. Trigger it via its generated endpoint (e.g. /orderStatus).

Product Setup and Operations

Security Hardening

InfoConnect Hub RPA by default is bundled with pre-defined credentials, HTTP listener.

  • The default authentication for Admin APIs is Basic Auth with user ID = Admin and pwd = Password

  • The default authentication for Functional API is Basic Auth with user ID = User and pwd = Password@123

As part of the product evaluation, likely the most basic security settings and non-secure IBM i connection are created. Below is a security hardening checklist to execute early in the trial / evaluation process:

  1. Configure HTTPS protocol for the API / HTTP listener

  2. Change the encryption key used to encrypt sensitive properties

  3. Encrypt all credentials and other sensitive API properties using Admin encryption API

  4. Change the default Admin and Functional API user ID and password

  5. Restrict access to APIs to specific allowed source IPs only

  6. Add rate limiting and other security policies to protect the functional APIs and

How to change the default user ID and password for admin and functional users

  1. To change the default user ID and password we should go to application.properties file which is located in /opt/rpa-hub/config directory. Make sure that you update the userID and password in 'application.properties' at the path '/opt/info-connect-hub/config' too.

  2. We need to find a section for Basic Authentication.

  3. If you want to change credentials, then use the User section for Functional operations, and the Admin section for Admin operations.

  4. If you want to change user ID then find userName field and change the value.

Connection Configuration

Property Description Required Default Value
User Name User ID true
Username X Position User ID field starting column on the login screen true
Username Y Position User ID row on the login screen true
Password Password true
Password X Position Password field starting column on the login screen true
Password Y Position Password row on the login screen true
Initial Key String Static set of keys, menu option navigation etc that must be executed when the new session starts
Host IBM i IP or server name true
Port Telnet port true
SSL Type Encryption and certificate type. Valid values include NONE (default, no encryption), SSL and TLS true
Debug Mode Optional setting, when defined as true, the application will print the screen after each keystroke is executed.
Reconnection Attempts Number of retries the application will perform the reconnection, defaults to 1
Time Between Attempts (ms) Number of milliseconds between refresh, default to 300

Key names

Below is a list of standard key codes and descriptions supported by the application. The keys must appear exactly as they are defined below, and each key or literal or variable or special command must be separated by the comma

Key Code Description
[backspace] Back Space
[backtab] Back Tab
[up]
[down] Cursor Down
[left] Cursor Left
[right] Cursor Rignt
[delete] Delete
[tab] Tab
[eof] End of Field
[eraseeof] Erase EOF
[erasefld] Erase Field
[insert] Insert
[home] Home
[keypad0] Keypad 0
[keypad1] Keypad 1
[keypad2] Keypad 2
[keypad3] Keypad 3
[keypad4] Keypad 4
[keypad5] Keypad 5
[keypad6] Keypad 6
[keypad7] Keypad 7
[keypad8] Keypad 8
[keypad9] Keypad 9
[keypad.] Decimal
[keypad,] Comma
[keypad-] Keypad minus
[fldext] Field Exit
[field+] Field Plus
[field-] Field Minus
[bof] Beginning of Field
[enter] Enter
[pf1] F1
[pf2] F2
[pf3] F3
[pf4] F4
[pf5] F5
[pf6] F6
[pf7] F7
[pf8] F8
[pf9] F9
[pf10] F10
[pf11] F11
[pf12] F12
[pf13] F13
[pf14] F14
[pf15] F15
[pf16] F16
[pf17] F17
[pf18] F18
[pf19] F19
[pf20] F20
[pf21] F21
[pf22] F22
[pf23] F23
[pf24] F24
[clear] Clear
[pgup] Page Up
[pgdown] Page Down
[rollleft] Roll Left
[rollright] Roll Right

Special commands

[MACRO] - execute Macro file. The Macro file name must be specified in the Macro File parameter.

[SET_INFIELD x y] - positions the cursor to the input field at column x, row y

[GET_SCREEN x y length height variable-name] - reads screen area rectangle starting with column x / row y, with the horizontal size of characters, and vertical size of characters. The output will be stored into the variable-name and passed back into application or script.

Parameter Mapping

To set the value of the input fields dynamically, use the pattern : in the script, for example the below snippet positions the cursort to col 29 row 10, then inserts the content of variable "uri", then sends Enter key. 

[SET_INFIELD 29 10],:<uri>,[enter]

The variables must be defined in the Input Parameters variable in request body, for example:


"inputParameter":{

        "uri":"1230045" 

    },