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. infoRPA for MuleSoft is a simple automation connector that runs directly inside MuleSoft app and simulates green screen user actions such as 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 MuleSoft 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

License

infoRPA for Mulesoft is offered under GPL 2 open source license.

How does it work?

Infoview's infoRPA is a simple Mulesoft plug-in 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.

The connector works entirely within Mulesoft application and does not require any other software to execute.

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 connector operation executes the script (a series of keystrokes, macro executions etc) then passess the resulting variables back to the Mule flow.

Mulesoft and IBM i requirements

The connector is available for Mulesoft Enterprise and Community (Kernel) editions
Minimal supported Mulesoft runtime version is 4.2.0
Any IBM i OS version is supported

Installation

infoRPA for Mulesoft is distributed as a Maven dependency. In order to add connector to Mulesoft project, add the following dependency and repository to the project's pom.xml file

Dependency section

<dependencies>
    ...
    <dependency>
        <groupId>com.infoview.as400</groupId>
        <artifactId>mule-rpa-connector</artifactId>
        <version>1.0.2</version>
        <classifier>mule-plugin</classifier>
    </dependency>
</dependencies>

Repository definition

<repositories>
    ...
    <repository>
        <id>repo</id>
        <url>https://pkgs.dev.azure.com/infoviewsystems/repo/_packaging/public/maven/v1</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

After the changes above are saved, Anypoint Studio will automatically download and install the connector into the project.

Connection Configuration

Property	Description	Required
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 connector will print the screen after each keystroke is executed.
Reconnection Attempts	Number of retries the connector will perform the reconnection, defaults to 1
Time Between Attempts (ms)	Number of milliseconds between refresh, default to 300

Execute Script 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
Input 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
Macro Output Parameters	Name and value of the output variables passed from Macro script

Key names

Below is a list of standard key codes and descriptions supported by the connector. 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 Mule flow 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 section of the connector operation as a list of name and value pairs, for example the value of that variable is mapped to Mule flow value of customerId coming from the HTTP request:

#[{"uri":attributes.uriParams.customerId}]

Example

The detailed walk-through of this example is available at infoRPA for Mulesoft Demo Video

The complete source code for this example is available at infoRPA Mulesoft Demo Source Code

Connector configuration XML

    <as400-rpa-connector:execute-script doc:name="Execute script" doc:id="5948925f-c53b-4a07-a5db-0b5b0d571500" config-ref="Config_TLS" 
        inputParameters='#[{"uri":attributes.uriParams.customerId}]' fileName="addItems.py" macroInputParameters='#[{"items": payload.Items}]'>

        <as400-rpa-connector:key-string >
            <![CDATA[call cdcordcmtc,[enter],[SET_INFIELD 29 10],:<uri>,[enter],[enter],[pf6],[MACRO],[pf10],[GET_SCREEN 15 4 8 1 orderNum],[GET_SCREEN 2 24 13 1 orderStatus],[pf12],[pf3]]]>
        </as400-rpa-connector:key-string>

    </as400-rpa-connector:execute-script>

Python script example

    from org.tn5250j.framework.tn5250 import Rect

    print "--------------- tn5250j add items script start -------------"

    textBox = Rect()
    i = 9

    for item in items:
        field = _session.getScreen().getScreenFields().findByPosition(i-1, 2)
        field.setString(str(item["ItemNo"]))
        field = _session.getScreen().getScreenFields().findByPosition(i-1, 14)
        field.setString(str(item["ItemName"]))
        field = _session.getScreen().getScreenFields().findByPosition(i-1, 46)
        field.setString(str(item["Quantity"]))
        field = _session.getScreen().getScreenFields().findByPosition(i-1, 53)
        field.setString(str(item["UnitPrice"]))
        i = i + 1


    _session.getScreen().sendKeys("[enter]") 
    _session.getScreen().sendKeys("[enter]")

    print "---------------- tn5250j add items script end -------------"

Connector executes a call to the order maintenance program and presses Enter.
Connector sets the cursor to col 29 row 10, and types the value of the variable uri then presses Enter twice.
Connector sends F6 key event to navigate to new screen
Once on the new screen, the connector executes Python macro, passing the Items object coming in the API request body, and for each line item types the data into appropriate input fields on the Add Order lines subfile and presses Enter
After the order is entered, press F10 to create new order in the system
Retrieve newly generated order ID and status from the specified screen positions
Return back to the Work with Orders screen to prepare for the next transaction