Skip to content

RPA Hub User Guide

InfoConnect Hub RPA (the RPA Hub) automates user actions on IBM i green screens and surfaces them as REST APIs, called RPA Calls. This guide is for administrators and developers who connect applications to IBM i systems that offer no other integration option.

Overview

Companies that run their core systems of record on IBM i (formerly known as AS400 or iSeries) often depend on their application vendors to integrate those applications or automate manual user actions. InfoConnect Hub RPA is an automation application that runs as a standalone application within the InfoConnect Hub environment. It simulates user actions on a green screen: navigation, data entry and screen capture.

Use cases

  • Integration. Robotic Process Automation (RPA) fits companies that reach the application only through the green screen and cannot integrate at program or database level. If users key data into a legacy system by hand, automate that step.
  • Test automation. Many organizations test features and regressions manually whenever the application changes. Automated tests improve release quality, reduce manual effort and lower the risk of unintended changes.

Features

  • Automates manual green screen operations and surfaces legacy IBM i applications as modern APIs
  • Simulates green screen user actions directly from applications
  • Automates screen navigation and data entry for IBM i screen (tn5250) applications
  • Supports a Python-based script language for advanced screen navigation logic
  • Supports TLS (encrypted) connections
  • Supports RPA Calls with the HTTP verbs GET, POST, PUT, PATCH and DELETE, with parameters taken from the request body, query string, URI path variables and headers
  • Validates request parameters before the screen is touched
  • Generates OpenAPI definitions for RPA Calls
  • Supports Basic and OAuth 2.0 authentication
  • Restricts direct access to localhost or to an IP allow-list
  • Stores definitions in a local H2 file or in an external IBM i (Db2) or MySQL database

How it works

The RPA Hub:

  • opens an IBM i telnet (5250) session
  • runs a sequence of user actions to navigate screens
  • types data into display fields
  • presses function keys
  • reads sections of the screen into variables

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

A connection holds the credentials and the initial keystrokes that every new session runs to reach the starting screen, for example the Order Entry screen. An RPA Call runs its key string (keystrokes, macro runs and screen reads) and returns the values read from the screen and the macro output variables as a JSON object.

IBM i requirements

Any IBM i OS version is supported.

Quick start

Before you start, make sure that:

  • you have a host (on-premises or cloud) that runs Java and can reach the telnet port of the IBM i system
  • you have an IBM i user ID for the connection, and you know the screen coordinates of the user ID and password fields on the sign-on screen

Paths in this guide are relative to the RPA Hub base URL http://<host>:<port>. The RPA Hub listens on port 8082 by default.

  1. Get the RPA Hub distribution package from Infoview, or launch the RPA Hub from a participating marketplace such as AWS Marketplace.
  2. Download and run the RPA Hub on a host that can reach the target IBM i ports.

    The distribution contains start scripts, for example start-scripts/solo-start/rpa/start-rpa-only.sh (.bat and .ps1 on Windows). They read the encryption word (ENCRYPTION_WORD) and the API credentials from start-scripts/config/.env. To start the jar manually, run:

    java -Djasypt.encryptor.password=<encryption-word> \
         -Dpython.home=info-connect-rpa-hub/executable-jars/jython-standalone-2.7.4.jar \
         --add-opens java.base/java.io=ALL-UNNAMED \
         -Djdk.tls.client.protocols=TLSv1.2 \
         -jar info-connect-rpa-hub/executable-jars/info_connect_rpa_hub-<version>.jar \
         --spring.config.location=info-connect-rpa-hub/config/application.properties \
         --spring.config.additional-location=optional:file:start-scripts/config/.env
    

    The configuration file of the RPA Hub is info-connect-rpa-hub/config/application.properties.

    Warning

    The encryption word is the key that encrypts the passwords stored by the RPA Hub. Keep it secret and do not change it after connections have been created.

  3. Open a REST client such as Postman or cURL. The default API authentication is Basic authentication, see Default credentials and hardening.

    By default, the RPA Hub binds to 127.0.0.1 and accepts requests only from the local machine, for example from an InfoConnect Hub on the same host. Other clients receive 403 Access denied. To allow other machines, see Network access.

  4. Verify that the RPA Hub is running:

    GET /admin/connections
    

    The response is an empty array, because no connections exist yet. Through the InfoConnect Hub the same call is GET http://<hub-host>:8080/rpa/admin/connections, see RPA Hub and InfoConnect Hub paths.

  5. Encrypt the IBM i password. The response contains the encrypted value to use in the connection request.

    POST /admin/encryption
    
    {
      "password": "my-ibmi-password"
    }
    
  6. Create an IBM i connection with POST /admin/connections, using a request like the following sample. For the meaning of each field, see Connection fields.

    Sample connection request
    {
      "connectionName": "test",
      "host": "<ibmi-host>",
      "port": "<telnet-port>",
      "userName": "<user-name>",
      "userNameXPosition": "<column of the user name field>",
      "userNameYPosition": "<row of the user name field>",
      "password": "<encrypted-password>",
      "passwordXPosition": "<column of the password field>",
      "passwordYPosition": "<row of the password field>",
      "initialKeyString": "addlible apanda,[enter],[enter],addlible infocdccom,[enter],[enter]",
      "sslType": "TLS",
      "reconnectionAttempts": "1",
      "timeBetweenAttempts": "300",
      "debugMode": "true",
      "status": "ACTIVE"
    }
    
  7. Verify the connection with GET /admin/connections. The response shows the new connection with the status ACTIVE.

  8. Register an RPA Call that uses the connection with POST /admin/rpa-calls, see RPA Call definitions.
  9. Run the RPA Call through its generated endpoint, for example /orders/status, or /rpa/orders/status through the InfoConnect Hub. See Executing RPA Calls.
  10. Optionally, assign the RPA Call to a user group in the InfoConnect Hub to control who may run it.

You can also create connections and RPA Calls in the Hub web UI, see Connections and RPA Call in the Web UI Guide.

RPA Hub and InfoConnect Hub paths

The RPA Hub (port 8082) serves its endpoints directly, for example /admin/connections. The InfoConnect Hub (port 8080) proxies the same operations under the /rpa prefix and authenticates callers with its own credentials. This guide shows the RPA Hub paths. The table lists the matching InfoConnect Hub paths.

Operation RPA Hub (port 8082) InfoConnect Hub (port 8080)
Create connection POST /admin/connections POST /rpa/admin/connections
List connections GET /admin/connections GET /rpa/admin/connections
Get connection GET /admin/connections/{connectionName} GET /rpa/admin/connections/{connectionName}
Delete connection DELETE /admin/connections/{connectionName} DELETE /rpa/admin/connections/{connectionName}
Close connection POST /admin/connections/{connectionName}/close POST /rpa/admin/connections/{connectionName}/stop
Reopen connection POST /admin/connections/{connectionName}/reopen POST /rpa/admin/connections/{connectionName}/start
Register RPA Call POST /admin/rpa-calls POST /rpa/admin/rpa-calls
List RPA Calls GET /admin/rpa-calls GET /rpa/admin/rpa-calls
Get RPA Call GET /admin/rpa-calls/{name} GET /rpa/admin/rpa-calls/{name}
Delete RPA Call DELETE /admin/rpa-calls/{name} DELETE /rpa/admin/rpa-calls/{name}
Activate RPA Call GET /api/{name}/activate GET /rpa/admin/rpa-calls/{name}/activate
Deactivate RPA Call GET /api/{name}/deactivate GET /rpa/admin/rpa-calls/{name}/deactivate
OpenAPI of one RPA Call GET /rpa/openapi/{name}/json or /yaml GET /rpa/admin/openapi/{name}/json or /yaml
OpenAPI of all RPA Calls GET /rpa/openapi/all/json or /yaml GET /rpa/admin/openapi/all/json or /yaml
Update connection PUT /admin/connections/{connectionName} PUT /rpa/admin/connections/{connectionName}
Update RPA Call PUT /admin/rpa-calls/{name} PUT /rpa/admin/rpa-calls/{name}
Execute RPA Call /<uri> (also /api/<uri>) /rpa/<uri>

To encrypt a value, call POST /admin/encryption on the RPA Hub directly.

Connections

A connection holds the IBM i host, the user, and the keystrokes that bring a new session to its starting screen. All calls that use the same connection run one after another, because a connection has a single IBM i session.

Connection fields

All values are sent as JSON strings. A request with a missing or invalid value returns HTTP 400 that lists the problems.

Field UI label Description Required Default
connectionName Connection Name Unique name of the connection Yes
host Host IBM i IP address or server name Yes
port Port Telnet port Yes
userName User Name IBM i user ID Yes
userNameXPosition Username X Position Column where the user ID field starts on the login screen Yes
userNameYPosition Username Y Position Row of the user ID field on the login screen Yes
password Password Password, encrypted with /admin/encryption Yes
passwordXPosition Password X Position Column where the password field starts on the login screen Yes
passwordYPosition Password Y Position Row of the password field on the login screen Yes
initialKeyString Initial Key String Keys and menu navigation that every new session runs, see Key string commands Yes
sslType SSL Type Encryption type: NONE (no encryption) or TLS Yes
debugMode Debug Mode When true, the RPA Hub prints the screen after each keystroke Yes
reconnectionAttempts Reconnection Attempts Number of reconnection attempts, for example 1 Yes
timeBetweenAttempts Time Between Attempts (ms) Milliseconds between attempts, for example 300 Yes
status Status ACTIVE opens the session. INACTIVE saves the connection without a session No ACTIVE

Create Screen Automation Connection form in the Hub UI

Connection endpoints

Method Path Notes
POST /admin/connections Create a connection and open the session
GET /admin/connections List all connections
GET /admin/connections/{connectionName} Get one connection (the password is never returned)
PUT /admin/connections/{connectionName} Replace a connection. The password value ENCRYPTED keeps the stored password
DELETE /admin/connections/{connectionName} Close the session and delete the connection
POST /admin/connections/{connectionName}/close Close the session. The status becomes INACTIVE
POST /admin/connections/{connectionName}/reopen Open a new session. The status becomes ACTIVE

RPA Call definitions

An RPA Call definition links a URI to a connection and a key string. When you register it, the RPA Hub surfaces the URI as a REST endpoint.

Definition fields

Field Description Required Default
rpaCallDefinitionName Unique name of the RPA Call. Letters, digits and hyphens only Yes
connectionName Name of an existing connection that is not INACTIVE (checked on registration) Yes
uri Path under which the RPA Call is available, for example orders/status, see URI rules Yes
keyString Sequence of keys, function keys, literals, variables and special commands that represent the user actions, see Key string commands Yes
programDescription Free text shown in the generated OpenAPI definition No
supportedHttpVerbs List of GET, POST, PUT, PATCH, DELETE. A request with any other verb is rejected with HTTP 400 No empty (all verbs allowed)
rpaCallParameters Mapping of request values to key string variables and macro variables, see Parameters and mapping No
macroTransportConfig Name, protocol and location of the macro file (Python script) used by [MACRO], see Macro transport options No
schemaValidationEnabled When true, request parameters are validated before the RPA Call runs, see Request validation No false
status ACTIVE, INACTIVE or FAILED, see RPA Call and connection status No ACTIVE
executionErrorMessage Read-only. Short description of the last failure, filled in when the status becomes FAILED No
queryOnly Informational flag that marks an RPA Call that does not change data on the IBM i No false

URI rules

  • A leading / is added. Register the URI without a trailing /.
  • Variables in braces, for example orders/{orderId}, match one path segment. Read them as message.uriParams.orderId. A variable named {id} matches digits only.
  • A static URI wins over a template.
  • On registration, a URI that another definition already uses is rejected.

Registering an RPA Call

Register a definition with POST /admin/rpa-calls. The connection must exist and must not be INACTIVE. A successful registration returns HTTP 200 with {"message": "RPA Call Definition has been registered for '<name> script'"}.

Sample RPA Call definition
{
  "connectionName": "test",
  "rpaCallDefinitionName": "orderItems",
  "programDescription": "Add items to an order",
  "uri": "orders/items",
  "supportedHttpVerbs": ["POST"],
  "keyString": "[SET_INFIELD 29 10],:<orderId>,[enter],[MACRO],[GET_SCREEN 15 4 8 1 orderNum],[GET_SCREEN 2 24 13 1 orderStatus],[pf3]",
  "rpaCallParameters": {
    "params": [
      {
        "parameterName": "orderId",
        "sourceFieldName": "orderId",
        "usage": "IN",
        "dataType": "STRING",
        "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
          }
        ]
      },
      {
        "parameterName": "total",
        "usage": "OUT",
        "macroParameter": true
      }
    ]
  },
  "macroTransportConfig": {
    "macroFileName": "addItems.py",
    "macroFileProtocol": "FILE",
    "transportConfig": {
      "FILE": {
        "filePath": "/opt/rpa-macros"
      }
    }
  }
}

Create RPA Call form in the Hub UI

RPA Call endpoints

Method Path Notes
POST /admin/rpa-calls Register a new RPA Call definition
PUT /admin/rpa-calls/{name} Update an existing definition
DELETE /admin/rpa-calls/{name} Delete a definition
GET /admin/rpa-calls/{name} Get one definition
GET /admin/rpa-calls List all definitions
GET /api/{name}/activate Activate the RPA Call
GET /api/{name}/deactivate Deactivate the RPA Call
GET /rpa/openapi/{name}/json OpenAPI definition of one RPA Call (/yaml for YAML)
GET /rpa/openapi/all/json OpenAPI definition of all RPA Calls (/yaml for YAML)

Parameters and mapping

rpaCallParameters.params is a list of parameters. Nested parameters are listed in dataStructureElements.

Parameter fields

Field Description Required Default
parameterName Name of the variable. Used as :<parameterName> in the key string, or as the Python variable name in a macro Yes
sourceFieldName Where the value is read from in the request, see Parameter mapping Yes, for usage IN
parameterValue Default value, used when the request does not contain the field No empty
parameterDescription Description of the parameter No
usage IN parameters receive values from the request. OUT together with macroParameter: true returns a macro variable in the response. OUT parameters are not validated No IN
macroParameter When true, the value is passed to the macro as a Python variable named parameterName instead of being substituted into the key string No false
dataType IBM i data type used for validation: BIGINTEGER, BINARY, BYTEARRAY, DATE, FLOAT, INTEGER, PACKED, STRING, STRUCTURE, SHORT, TIME, TIMESTAMP, UNSIGNEDBINARY, ZONED No
length Maximum length of the value. 0 means unlimited No 0
decimalPositions Number of decimal positions for PACKED, ZONED and FLOAT values No 0
dataStructureElements Child parameters of a structure or of a list of rows passed to a macro No

Parameter mapping

To set an input field dynamically, use the pattern :<variable-name> in the key string. The following snippet moves the cursor to column 29, row 10, types the value of the variable orderId, then sends Enter:

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

The variable must stand on its own between commas (or spaces) in the key string. It must be defined as a parameter of the RPA Call, with parameterName equal to the variable name. The RPA Hub reads the value from the request according to sourceFieldName:

sourceFieldName Value is read from
message.body.<field> The JSON request body
message.queryParams.<field> The query string
message.uriParams.<field> A path variable of the uri, for example {orderId}
message.headers.<field> An HTTP request header
<field> (no prefix) The JSON body, then the query string, then the headers

Nested body fields use dots, for example message.body.customer.id. When the request does not contain the field, parameterValue is used.

Example: an RPA Call with uri set to orders/{orderId} and supportedHttpVerbs set to ["GET"] defines this parameter:

{
  "parameterName": "orderId",
  "sourceFieldName": "message.uriParams.orderId",
  "dataType": "STRING",
  "length": 8
}

The call GET /orders/1230045 fills :<orderId> with 1230045. For a POST call, send the same value in the body and set sourceFieldName to message.body.orderId:

{
  "orderId": "1230045"
}

Key string commands

A key string is a comma-separated list of key codes, special commands, variables and literals. Key codes must appear exactly as listed. Text that is not a key code or a special command is typed into the current input field. Spaces around the commas are ignored.

Key codes

Key code Description
[enter] Enter
[clear] Clear
[pf1] to [pf24] F1 to F24
[backspace] Back Space
[backtab] Back Tab
[tab] Tab
[up] Cursor Up
[down] Cursor Down
[left] Cursor Left
[right] Cursor Right
[delete] Delete
[insert] Insert
[home] Home
[eof] End of Field
[bof] Beginning of Field
[eraseeof] Erase EOF
[erasefld] Erase Field
[fldext] Field Exit
[field+] Field Plus
[field-] Field Minus
[pgup] Page Up
[pgdown] Page Down
[rollleft] Roll Left
[rollright] Roll Right
[keypad0] to [keypad9] Keypad 0 to Keypad 9
[keypad.] Decimal
[keypad,] Comma
[keypad-] Keypad minus

Special commands

Command Description
[MACRO] Runs the macro file defined in macroTransportConfig.macroFileName of the RPA Call, see Macros
[SET_INFIELD x y] Moves the cursor to the input field at column x, row y. The text that follows is typed into this field
[GET_SCREEN x y length height variable-name] Reads a screen rectangle that starts at column x, row y and spans length characters by height lines. The result is stored under variable-name and returned in screenOutput as an array with one string per screen line

Macros

A macro is a Python script (Jython 2.7 syntax) that the [MACRO] command runs for advanced screen navigation logic. In a macro:

  • The IBM i session is available as the variable _session.
  • Every parameter with macroParameter: true is available as a variable named like parameterName. JSON objects arrive as Python dictionaries and JSON arrays as lists.
  • Every parameter with usage: OUT and macroParameter: true returns the macro variable of that name in scriptOutput after the macro finishes. Text, numbers, dictionaries, lists, tuples and objects are supported.
# items is a macroParameter input; total is an OUT macroParameter
total = 0
for item in items:
    total = total + float(item["Quantity"]) * float(item["UnitPrice"])

Example: read an order status

This macro types an order number into an input field, presses Enter, waits for the host and reads the status from the screen. Save it as orderStatus.py in the directory that you set in filePath of the macro transport.

orderStatus.py
# Looks up the status of an order on an order inquiry screen.
#
# Macro parameters:
#   orderId      IN   the order number to look up
#   orderStatus  OUT  the status shown on the screen, empty if the order was not found
#   message      OUT  "OK", or the message that the application shows on the message line

import time

# Screen layout of the example application. Rows and columns start at 1.
ORDER_ROW, ORDER_COL = 10, 29
STATUS_ROW, STATUS_COL, STATUS_LENGTH = 12, 29, 10
MESSAGE_ROW = 24

screen = _session.getScreen()


def wait_for_host(timeout=10):
    # Wait until the host accepts input again.
    deadline = time.time() + timeout
    while screen.getOIA().getInputInhibited() == 1:
        if time.time() > deadline:
            raise Exception("The host did not respond within %d seconds" % timeout)
        time.sleep(0.1)


def read_text(row, col, length):
    # Read the whole row and cut out the part that starts at col.
    chars = screen.getData(row - 1, 0, row - 1, screen.getColumns() - 1, 10)
    line = "".join(chars).replace("\x00", " ")
    return line[col - 1:col - 1 + length].strip()


# 1. Type the order number into the input field.
field = screen.getScreenFields().findByPosition(ORDER_ROW - 1, ORDER_COL - 1)
if field is None:
    raise Exception("No input field at row %d, column %d" % (ORDER_ROW, ORDER_COL))
field.setString(str(orderId))

# 2. Press Enter and wait for the answer.
screen.sendKeys("[enter]")
wait_for_host()

# 3. Read the result. The application shows an error on the message line
#    when the order does not exist.
message = read_text(MESSAGE_ROW, 1, 79)
if message:
    orderStatus = ""
else:
    orderStatus = read_text(STATUS_ROW, STATUS_COL, STATUS_LENGTH)
    message = "OK"

How it works:

  • _session and orderId are provided by the RPA Hub. orderStatus and message are ordinary variables. The RPA Hub returns them because the RPA Call defines them as OUT macro parameters.
  • The screen API counts from 0 and takes the row first: findByPosition(row - 1, column - 1). The key string commands [SET_INFIELD x y] and [GET_SCREEN x y ...] take the column first and count from 1. The macro subtracts 1 so that you can use the numbers that you see on the screen.
  • setString fills the field, and sendKeys("[enter]") sends the key. The key names are the ones in Key codes.
  • The wait loop checks the input-inhibited indicator of the terminal. Without it, the macro could read the screen before the host has answered.
  • If the macro raises an exception, for example because the field is not found, the call returns HTTP 400 with the message and the RPA Call gets the status FAILED, see RPA Call and connection status. A missing order is an expected result, so the macro returns it in message instead.

Register the RPA Call. The key string runs the macro and then returns to the previous screen with F3. The connection must start on the order inquiry screen, for example with its initial keystrokes.

{
  "connectionName": "test",
  "rpaCallDefinitionName": "orderStatus",
  "programDescription": "Read the status of an order",
  "uri": "orders/status",
  "supportedHttpVerbs": ["POST"],
  "keyString": "[MACRO],[pf3]",
  "rpaCallParameters": {
    "params": [
      {
        "parameterName": "orderId",
        "sourceFieldName": "orderId",
        "usage": "IN",
        "dataType": "STRING",
        "length": 8,
        "macroParameter": true
      },
      {
        "parameterName": "orderStatus",
        "usage": "OUT",
        "macroParameter": true
      },
      {
        "parameterName": "message",
        "usage": "OUT",
        "macroParameter": true
      }
    ]
  },
  "macroTransportConfig": {
    "macroFileName": "orderStatus.py",
    "macroFileProtocol": "FILE",
    "transportConfig": {
      "FILE": {
        "filePath": "/opt/rpa-macros"
      }
    }
  }
}

Call it and read the result from scriptOutput:

POST /orders/status
Content-Type: application/json

{
  "orderId": "1042"
}
{
  "scriptOutput": [
    {
      "orderStatus": "SHIPPED",
      "message": "OK"
    }
  ]
}

To adapt the example to your application, change the screen layout constants at the top of the script. To find the positions, run the connection with debugMode set to true and read the screen dumps in the log, see Logs.

Macro transport options

Set the protocol in macroFileProtocol and fill the matching block in transportConfig. Encrypt the secrets s3AccessKey, s3SecretKey, ftpPassword and httpPassword with /admin/encryption.

Protocol Required fields in transportConfig
FILE filePath: absolute path of the directory on the RPA Hub host that contains the file in macroFileName
CLASSPATH none; the file in macroFileName is read from the application classpath
S3 s3Bucket, s3Region, s3AccessKey, s3SecretKey
FTP ftpHost, ftpDirPath, ftpUserName, ftpPassword
HTTP httpUrl, httpDirPath, httpUserName, httpPassword

The RPA Hub checks the macro file name and the transport when you register or update the RPA Call. For FILE, the directory and the file must exist.

Executing RPA Calls

Request

When you register an RPA Call with, for example, uri set to orders/status, the RPA Hub surfaces it under the same relative path and also under /api/orders/status. Through the InfoConnect Hub the path has the prefix /rpa.

Where Call
RPA Hub (port 8082) POST http://<host>:8082/orders/status
InfoConnect Hub POST http://<hub-host>:8080/rpa/orders/status
POST /orders/status
Content-Type: application/json

{
  "orderStatus": "Picked"
}

Send the header Content-Type: application/json with every verb, including GET and DELETE, as a User or an Admin. The body is optional for GET and DELETE, where it is ignored. The verb must be listed in supportedHttpVerbs of the definition. All verbs are allowed when the list is empty.

Execute RPA Call form in the Hub UI

Response

The response is a JSON object with up to two parts. Empty parts are omitted.

Part Content
screenOutput One entry per [GET_SCREEN ... name] command. The value is an array with one string per screen line read
scriptOutput A list with one object per [MACRO] run. The object holds the macro variables defined as parameters with usage: OUT and macroParameter: true
{
  "scriptOutput": [
    { "total": 125.5 }
  ],
  "screenOutput": {
    "orderNum": ["03122147"],
    "orderStatus": ["Order Created"]
  }
}

For a definition whose key string contains [GET_SCREEN 38 10 10 1 orderStatusNew] and no macro, the response is:

{
  "screenOutput": {
    "orderStatusNew": ["Picked"]
  }
}

Request validation

Before the RPA Hub runs the key string, it resolves the parameter values and validates them when schemaValidationEnabled is true (disabled by default). If a value is invalid, nothing is sent to the IBM i. The call returns HTTP 400 with all problems in one message, separated by ;:

{
  "message": "Parameter 'orderId' exceeds maximum length 8 (actual length 11)."
}
Message Cause
Parameter '<name>' exceeds maximum length <n> (actual length <m>). The value is longer than length
Parameter '<name>': value is incompatible with type <TYPE> (got <value>). The value does not match dataType
Parameter '<name>': value <v> has <n> fractional digit(s) but at most <d> allowed (decimalPositions). Too many decimal digits for PACKED, ZONED or FLOAT
Parameter '<name>': value <v> exceeds maximum <max> for <TYPE> (length <l>, decimalPositions <d>). The number is larger than length and decimalPositions allow
Parameter '<name>' is required but was not provided. A STRUCTURE parameter or one of its elements is missing
Parameter '<name>': nested STRUCTURE must be a JSON object or a JSON array of objects; received <Type>. A structure parameter has the wrong JSON shape
RPA Call <name> does not support <VERB> method The verb is not listed in supportedHttpVerbs

Without dataType, only the maximum length is checked. Names of nested values are shown as structure[0].field.

The registration request is validated too. A failed registration (POST) returns HTTP 400 with the list of problems, for example {"message": ["Field 'uri': URI for program call is required"]}. An update (PUT) and the connection endpoints return {"message": "Errors: \n1: SSL Type is required\n"}.

RPA Call and connection status

Status Meaning
ACTIVE The RPA Call can be executed. This is the default for new definitions
INACTIVE The RPA Call was deactivated. Requests return HTTP 404. The definition is kept
FAILED The last execution failed and executionErrorMessage holds a short description. The RPA Call can still run. The next successful run sets it to ACTIVE

A failure while running the key string or the macro sets the status of the RPA Call to FAILED.

To deactivate or activate an RPA Call, call GET /api/{name}/deactivate or /api/{name}/activate. Through the InfoConnect Hub use /rpa/admin/rpa-calls/{name}/deactivate and /activate. The response is {"message": "<name> deactivated successfully."} or {"message": "<name> activated successfully."}.

Connections have their own status:

  • POST /admin/connections/{connectionName}/close closes the session and sets the connection to INACTIVE.
  • POST /admin/connections/{connectionName}/reopen opens a new session and sets the connection to ACTIVE.
  • RPA Calls that use an INACTIVE connection return HTTP 400.

OpenAPI definitions

The RPA Hub generates an OpenAPI definition from the registered RPA Calls. The IN parameters become request fields, or path, query and header parameters, depending on the sourceFieldName prefix. The OUT parameters become response fields.

Endpoint Result
GET /rpa/openapi/{name}/json OpenAPI definition of one RPA Call (JSON)
GET /rpa/openapi/{name}/yaml OpenAPI definition of one RPA Call (YAML)
GET /rpa/openapi/all/json OpenAPI definition of all RPA Calls (JSON)
GET /rpa/openapi/all/yaml OpenAPI definition of all RPA Calls (YAML)

Any authenticated user can call these endpoints. If the definition cannot be generated, they return HTTP 400 with an error field. The InfoConnect Hub offers the same definitions under /rpa/admin/openapi/.... The RPA Hub also serves the OpenAPI definition and Swagger UI of its own administration API at /v3/api-docs and /swagger-ui.html.

Errors

Error responses

Errors are returned as JSON with a message field:

{
  "message": "Connection: 'test' is closed"
}
Status Meaning
400 Invalid request (see Request validation), unsupported HTTP verb, closed connection, duplicate name or URI, or a failure while the key string or macro ran (for example IBM i not reachable, field not found, macro error). The message describes the failure
401 Missing or invalid credentials
403 The user is not allowed to call the endpoint, or the client IP address is not allowed (plain text Access denied)
404 The RPA Call definition or connection does not exist, or the RPA Call is INACTIVE
500 Unexpected error in an administration call

Security and configuration

Default credentials and hardening

The built-in configuration of the RPA Hub jar has predefined credentials and an HTTP listener:

  • Admin API: Basic authentication with user ID Admin and password Password.
  • Functional API: Basic authentication with user ID User and password Password@123.

In the distribution, you set the credentials in start-scripts/config/.env with change-default-creds. Make sure that the rpa.* credentials in the InfoConnect Hub configuration match.

During an evaluation, the RPA Hub typically runs with these basic security settings and a non-secure IBM i connection. Complete the following hardening checklist early in the evaluation:

  • Configure HTTPS for the API listener, see HTTPS.
  • Change the encryption key that encrypts sensitive properties.
  • Encrypt all credentials and other sensitive API properties with the Admin encryption API.
  • Change the default Admin and Functional API user IDs and passwords, see Changing the default credentials.
  • Restrict API access to specific source IP addresses with server.access.allowed-ips, and keep the list short, see Network access.
  • Add rate limiting and other security policies to protect the Functional APIs.

Changing the default credentials

  1. Open the application.properties file of the RPA Hub in the info-connect-rpa-hub/config directory of the distribution.
  2. Find the section for Basic authentication. The User section is for Functional operations and the Admin section is for Admin operations.
  3. Change the value of the property that you want to update:

    Purpose RPA Hub property InfoConnect Hub property
    Functional user userUsername, userPassword rpa.userUsername, rpa.userPassword
    Admin user adminUsername, adminPassword rpa.adminUsername, rpa.adminPassword
  4. Set the same user ID and password in the application.properties file of the InfoConnect Hub in info-connect-hub/config, because the InfoConnect Hub uses them to call the RPA Hub.

In the distribution, the RPA Hub file reads the values from start-scripts/config/.env. Run start-scripts/change-default-creds.sh (change-default-creds.bat on Windows) to set them.

Authentication and roles

The property auth.type selects the authentication of the RPA Hub: basic (default) or oauth.

Role Allowed endpoints
Admin /admin/** (connections, RPA Call definitions, encryption) and the Functional endpoints
User Functional endpoints: executing, activating and deactivating RPA Calls

The OpenAPI endpoints /rpa/openapi/** are open to any authenticated user.

To use OAuth 2.0, set auth.type=oauth and configure the token issuer. The RPA Hub validates tokens against the issuer and the audience. It does not start with auth.type=oauth when the audience is empty.

auth.type=oauth
spring.oauth.resource.server.issuer-uri=<issuer-uri>
spring.oauth.resource.server.audience=<audience-of-this-api>
spring.oauth.resource.server.authority.admin=ROLE_admin
spring.oauth.resource.server.authority.user=ROLE_user
spring.oauth.resource.server.authority.claim=role

The issuer must be one of the providers configured in spring.oauth.resource.server.issuer-uri_OKTA, _AWS, _SALESFORCE, _AZURE or _BUILT_IN. Each value of the token claim named in authority.claim becomes the role ROLE_<value>. The claim is role by default (cognito:groups for AWS, roles for Azure). The InfoConnect Hub authenticates to the RPA Hub with the properties rpa.auth.type and rpa.oauth.*.

Network access

By default, the RPA Hub binds to 127.0.0.1 and answers only requests from the local machine. Any other client receives 403 Access denied. To open the RPA Hub to other hosts, list the allowed client addresses in application.properties and restart:

server.access.allowed-ips=192.168.1.10,10.0.0.0/24

The list accepts single IP addresses and CIDR ranges. Localhost is always allowed. When the list is not empty, the RPA Hub binds to all network interfaces, unless server.address is set. In the distribution the property is a commented line. Uncomment it and set RPA_ALLOWED_CLIENT_IPS in start-scripts/config/.env, or replace the placeholder with the list.

The InfoConnect Hub reaches the RPA Hub with the properties rpa.host (default localhost) and rpa.port (default 8082). When the InfoConnect Hub runs on another machine, add its address to server.access.allowed-ips.

HTTPS

To serve the RPA Hub over HTTPS, configure a key store in application.properties. The key store password can be an encrypted value ENC(...).

server.port=9443
server.ssl.enabled=true
server.ssl.key-store=file:./HTTPS/<keystore-file-name>.p12
server.ssl.key-store-password=<keystore-password>
server.ssl.key-store-type=PKCS12
server.ssl.key-alias=<keystore-alias>

On the InfoConnect Hub, set rpa.secure=true, rpa.port and the trust store (trust.store.path, trust.store.pass) so that it trusts the RPA Hub certificate.

Configuration database

The RPA Hub stores connections and RPA Call definitions in a database. By default, it is a local H2 file, info-connect-rpa-hub/config-db (files config-db.*), relative to the directory the RPA Hub is started from. Back up this file. When you upgrade an installation that stored its data in another location, copy the H2 file to this location to keep existing connections and RPA Calls.

To store the data in an external database (IBM i Db2 or MySQL), create the tables with the DDL script that Infoview provides for your database, and change the data source in application.properties. Example for IBM i:

spring.datasource.url=jdbc:as400://<ibmi-host>/INFOCONNECT_RPA;secure=true;naming=sql
spring.datasource.username=<user>
spring.datasource.password=<password>
spring.datasource.driver-class-name=com.ibm.as400.access.AS400JDBCDriver
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.DB2400Dialect
spring.jpa.hibernate.ddl-auto=none
spring.jpa.properties.hibernate.default_schema=INFOCONNECT_RPA
Property Description Default
spring.jpa.hibernate.ddl-auto update creates the tables of the local H2 file. Use none with an external database; create the tables with the DDL script update
hibernate.physical_naming_strategy.table_prefix Prefix for the table names (CONNECTION, RPACALLS, RPACALL_HTTP_VERBS, ACTIVITYLOG), for example V1_. Use it to run a second RPA Hub in the same schema empty
db.sync.enabled When true, the RPA Hub checks the shared database every 60 seconds and loads connections and RPA Calls that another RPA Hub instance on the same database changed false

Other settings

Property Description Default
server.port Port of the RPA Hub 8082
as400.connection.screen-await-delay-ms Milliseconds the RPA Hub waits for the IBM i Sign On screen before the login and between login retries. Increase it for slow IBM i systems or networks 300

Logs

The RPA Hub writes log/info_connect_rpa_hub.out.log and log/info_connect_rpa_hub.err.log in the directory it is started from. Each file rolls over at 10 MB and 10 files are kept. When the RPA Hub starts in the background together with other modules, the start scripts also redirect the console output to log/infoConnectRpaHub.out.log and log/infoConnectRpaHub.err.log. Passwords, secrets, keys and tokens are masked in the logged requests and responses. A connection with debugMode set to true prints the screen after every keystroke.

Troubleshooting

Symptom Likely cause and action
403 Access denied from another machine The client address is not allowed. Add it to server.access.allowed-ips and restart, see Network access
401 response The credentials are missing or invalid. See Authentication and roles
404 when running an RPA Call The RPA Call does not exist or is INACTIVE. Activate it, see RPA Call and connection status
400 with Connection: '<name>' is closed The connection is INACTIVE. Reopen it with POST /admin/connections/{connectionName}/reopen
400 with a validation message A request value is invalid. See Request validation
The RPA Call status is FAILED Read executionErrorMessage of the definition. Set debugMode to true on the connection to see the screen after each keystroke
The login fails on a slow IBM i system or network Increase as400.connection.screen-await-delay-ms, see Other settings
Connections and RPA Calls disappear after an upgrade Copy the old H2 file to info-connect-rpa-hub/config-db, see Configuration database