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.
- Get the RPA Hub distribution package from Infoview, or launch the RPA Hub from a participating marketplace such as AWS Marketplace.
-
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(.batand.ps1on Windows). They read the encryption word (ENCRYPTION_WORD) and the API credentials fromstart-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/.envThe 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.
-
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. -
Verify that the RPA Hub is running:
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. -
Encrypt the IBM i password. The response contains the encrypted value to use in the connection request.
-
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" } -
Verify the connection with
GET /admin/connections. The response shows the new connection with the statusACTIVE. - Register an RPA Call that uses the connection with
POST /admin/rpa-calls, see RPA Call definitions. - Run the RPA Call through its generated endpoint, for example
/orders/status, or/rpa/orders/statusthrough the InfoConnect Hub. See Executing RPA Calls. - 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 |

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 asmessage.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"
}
}
}
}

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:
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:
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: trueis available as a variable named likeparameterName. JSON objects arrive as Python dictionaries and JSON arrays as lists. - Every parameter with
usage: OUTandmacroParameter: truereturns the macro variable of that name inscriptOutputafter 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.
# 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:
_sessionandorderIdare provided by the RPA Hub.orderStatusandmessageare ordinary variables. The RPA Hub returns them because the RPA Call defines them asOUTmacro 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. setStringfills the field, andsendKeys("[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 inmessageinstead.
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:
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 |
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.

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:
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 | 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}/closecloses the session and sets the connection toINACTIVE. - POST
/admin/connections/{connectionName}/reopenopens a new session and sets the connection toACTIVE. - RPA Calls that use an
INACTIVEconnection 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:
| 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
Adminand passwordPassword. - Functional API: Basic authentication with user ID
Userand passwordPassword@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
- Open the
application.propertiesfile of the RPA Hub in theinfo-connect-rpa-hub/configdirectory of the distribution. - Find the section for Basic authentication. The User section is for Functional operations and the Admin section is for Admin operations.
-
Change the value of the property that you want to update:
Purpose RPA Hub property InfoConnect Hub property Functional user userUsername,userPasswordrpa.userUsername,rpa.userPasswordAdmin user adminUsername,adminPasswordrpa.adminUsername,rpa.adminPassword -
Set the same user ID and password in the
application.propertiesfile of the InfoConnect Hub ininfo-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:
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 |