Share via


IA-Connect Mainframe (Preview)

IA-Connect is a Robotic Process Automation (RPA) platform which adds RPA functionality from the Cloud to on-premises virtual machines or over Citrix or Microsoft Remote Desktop (RDS) connections. This is the module for automating 5250 and 3270 Mainframe sessions using Terminal Emulation applications that support the HLLAPI API.

This connector is available in the following products and regions:

Service Class Regions
Logic Apps Standard All Logic Apps regions except the following:
     -   Azure Government regions
     -   Azure China regions
     -   US Department of Defense (DoD)
Power Automate Premium All Power Automate regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Power Apps Premium All Power Apps regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Contact
Name Ultima Labs
URL https://www.ultima.com/ultima-labs
Email IAConnect@ultima.com
Connector Metadata
Publisher Ultima Labs
Website https://www.ultima.com/ultima-labs
Privacy policy https://www.ultima.com/privacy-policy
Categories IT Operations;Productivity

IA-Connect is a Robotic Process Automation (RPA) platform which adds RPA functionality from Power Automate Cloud Flows to on-premises virtual machines or over Citrix or Microsoft Remote Desktop (RDS) connections. The IA-Connect Connectors provide over 650 actions, allowing you to automate every type of on-premise application directly from a Power Automate Cloud Flow. All IA-Connect actions are available directly from your Power Automate Cloud Flow providing easy integration between Cloud based and on-premises applications, the ability to leverage existing Power Automate conditions, loops, dynamic content, expressions and exception handling in your RPA processes. Utilising the IA-Connect Connectors also provides full execution history and auditability from the Flow run history whilst also removing the need to have a separate application/console/studio for developing your RPA processes.

Prerequisites

To use any of the IA-Connect Connectors, you must install the IA-Connect software. This is free to test for 30 days, following which you will require an IA-Connect license.

The IA-Connect software consists of two main components:

  • The IA-Connect Orchestrator, which is an Azure WebApp which you would host in your own Azure tenant. This handles the routing and security of RPA Flows to one or more on-premises or cloud-based virtual machines.

  • The IA-Connect Agent and Director, which is installed onto the virtual machines where the software you wish to automate is accessible. Additionally, the IA-Connect Agent can run inside a Citrix or Microsoft Remote Desktop Services (RDS) session, where the RPA commands are passed down a virtual channel into the remote session for execution. The IA-Connect Agent can be run from a network share and does not require installation.

Available IA-Connect Connectors

The available IA-Connect Connectors are:

  • IA-Connect Dynamic Code
  • IA-Connect Java
  • IA-Connect Mainframe
  • IA-Connect Microsoft Office
  • IA-Connect SAP GUI
  • IA-Connect Session
  • IA-Connect UI
  • IA-Connect Web Browser

How to get credentials

In order to receive your license and begin your 30-day free trial, please submit a request on our website (https://www.ultima.com/IA-Connect/Power-Automate).

Once a trial request is received, we will contact you via the email address provided to assist with setting up the IA-Connect software and to provide you with the trial license. This is a fully featured trial and will enable you to test any of the 650 actions across all 8 IA-Connect Connectors within your own environment during the trial period.

Get started with your connector

After submitting a trial request for IA-Connect, you will be able to download a ZIP file containing the IA-Connect software and documentation covering the installation and setup. We will also contact you to offer support and guidance through the installation process as required.

Support

During the trial period, you can contact Ultima Labs (IAConnect@ultima.com) for support and assistance.

Upon purchasing IA-Connect licenses you will receive support tokens which can be redeemed for bespoke training or support from Ultima's UK-based Technical Service Centre (TSC).

Known issues, common errors and FAQs

Our Knowledge Base contains a number of articles covering any known issues, common errors that may occur when using the IA-Connect Connectors and frequently asked questions. This is accessible at https://support.ultima.com/ultimalabs and an account to access these resources is provided during the IA-Connect trial and upon purchasing an IA-Connect license.

Creating a connection

The connector supports the following authentication types:

Default Parameters for creating connection. All regions Not shareable

Default

Applicable: All regions

Parameters for creating connection.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Name Type Description Required
API Key securestring The API Key for this api True
IA-Connect Orchestrator address string Specify the IA-Connect Orchestrator address without the HTTP(S) component True

Throttling Limits

Name Calls Renewal Period
API calls per connection 100 60 seconds

Actions

Connect to terminal emulation session

Connects any running IA-Connect HLLAPI subsystem (IA-HLLAPI) to the specified connected Mainframe session Id. The session Id is an Id assigned by the terminal emulator you are using for Mainframe connections. The Mainframe session must be running before you connect to it using this action.

Disconnect from terminal emulation session

Disconnects the running IA-Connect HLLAPI subsystem (IA-HLLAPI) from a specified connected Mainframe session Id. The session Id is an Id assigned by the terminal emulator you are using for Mainframe connections.

Dispose of terminal emulation HLLAPI DLL

Shuts down any running IA-Connect HLLAPI subsystem (IA-HLLAPI).

Get is terminal emulation keyboard unlocked

Returns whether the terminal emulator is reporting that the keyboard is unlocked. The output of this action is dependent on how the specific emulator has implemented HLLAPI and the output may vary from emulator to emulator.

Get terminal emulation connection status

Returns the current terminal emulation connection state within the specified session.

Get terminal emulation cursor position

Gets the current cursor position in a Mainframe session.

Get terminal emulation Operator Information Area (OIA)

Returns the Operator Information Area displayed by the terminal emulator. This is the line at the bottom of the terminal emulator screen and commonly indicates status information such as whether the system is waiting or is in an invalid input state.

Query terminal emulation session status

Returns information about the connected Mainframe session. Some terminal emulators may not return values for all outputs.

Read terminal emulation screen at cursor position

Reads the specified number of characters from the Mainframe session, starting at the specified cursor position.

Read terminal emulation screen rows

Reads the screen rows from a specified Mainframe session. This action is commonly used to read larger quantities of data which can then be filtered if necessary.

Reset terminal emulation session

Resets the current Mainframe session. The action disconnects IA-Connect Agent from the session and undoes any session parameters that have been set. After calling this action you will need to re-connect to the session by using the 'Connect to Session' action in order to continue interacting with it.

Search for string in terminal emulation session

Searches for a specified string in the current display of the terminal emulator. If the string is found, it's position and index will be returned.

Send password to terminal emulation session

Sends a password to a Mainframe session at the current cursor position. If you wish to send a password to a specific cursor position, you can use the action 'Send password to terminal emulation session at position' instead.

Send password to terminal emulation session at position

Sends a password to a Mainframe session at the specified cursor position.

Send reset key to terminal emulation session

Sends a reset key to the terminal emulator session. This will reset all input and will clear an invalid input state.

Send string to terminal emulation session

Sends a string to a Mainframe session at the current cursor position. If you wish to send a string to a specific cursor position, you can use the action 'Send string to terminal emulation session at position' instead.

Send string to terminal emulation session at position

Sends a string to a Mainframe session at the specified cursor position.

Set session parameter in terminal emulation session

This action sets an advanced HLLAPI session parameter. This action should only be used if you are familiar with HLLAPI session parameters.

Set terminal emulation cursor position

Sets the current cursor position in a Mainframe session to the specified position.

Set terminal emulation HLLAPI DLL

Starts the IA-Connect HLLAPI subsystem (IA-HLLAPI) and connects it to the specified Terminal Emulator HLLAPI DLL (a component of the terminal emulation software being used to connect to Mainframe sessions).

Wait for string in terminal emulation session

Waits for a specified string to be displayed in the terminal emulator session. This action can be used when moving between screens to validate that you are on the correct screen.

Wait for terminal emulation keyboard unlocked

Waits for the terminal emulator to report that the keyboard is unlocked. The output of this action is dependent on how the specific emulator has implemented HLLAPI and the output may vary from emulator to emulator.

Wait for terminal emulation system ready

Waits for the terminal emulator to report that the system is ready. The output of this action is dependent on how the specific emulator has implemented HLLAPI and the output may vary from emulator to emulator.

Connect to terminal emulation session

Connects any running IA-Connect HLLAPI subsystem (IA-HLLAPI) to the specified connected Mainframe session Id. The session Id is an Id assigned by the terminal emulator you are using for Mainframe connections. The Mainframe session must be running before you connect to it using this action.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Disconnect from terminal emulation session

Disconnects the running IA-Connect HLLAPI subsystem (IA-HLLAPI) from a specified connected Mainframe session Id. The session Id is an Id assigned by the terminal emulator you are using for Mainframe connections.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Dispose of terminal emulation HLLAPI DLL

Shuts down any running IA-Connect HLLAPI subsystem (IA-HLLAPI).

Parameters

Name Key Required Type Description
Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Get is terminal emulation keyboard unlocked

Returns whether the terminal emulator is reporting that the keyboard is unlocked. The output of this action is dependent on how the specific emulator has implemented HLLAPI and the output may vary from emulator to emulator.

Parameters

Name Key Required Type Description
Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
Keyboard is unlocked
KeyBoardIsUnlocked boolean

Returns true if the terminal emulator is reporting that the keyboard is unlocked.

Get terminal emulation connection status

Returns the current terminal emulation connection state within the specified session.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
Connected to session
ConnectedToSession boolean

Returns true if you are connected to the specified session ID, or false if not.

System busy
SystemBusy boolean

Returns true if the Mainframe system is reporting that it is currently busy, or false if not.

Keyboard locked
KeyboardLocked boolean

Returns true if the Mainframe session is reporting that the keyboard is currently locked, or false if not.

Session in use by another HLLAPI application
SessionInUseByAnotherHLLAPIApplication boolean

Returns true if the Mainframe session is currently in use by another HLLAPI application, or false if not.

HLLAPI thread ID
HLLAPIThreadID integer

Reports the HLLAPI thread ID within IA-Connect. This output is for diagnostic purposes only.

COM thread ID
COMThreadID integer

Reports the COM thread ID within IA-Connect. This output is for diagnostic purposes only.

Call count
CallCount integer

Reports the number of HLLAPI actions performed by IA-Connect in this session. This output is for diagnostic purposes only.

Get terminal emulation cursor position

Gets the current cursor position in a Mainframe session.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
Cursor row index
CursorRowIndex integer

The current cursor row index.

Cursor column index
CursorColIndex integer

The current cursor column index.

Cursor position
CursorPos integer

The absolute cursor position. For example, assuming a 24 row by 80 column session, the first column of the first row would be position 1 and the first column of the second row would be position 81.

Get terminal emulation Operator Information Area (OIA)

Returns the Operator Information Area displayed by the terminal emulator. This is the line at the bottom of the terminal emulator screen and commonly indicates status information such as whether the system is waiting or is in an invalid input state.

Parameters

Name Key Required Type Description
Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
OIA format
OIAFormat string

The Operator Information Area (OIA) format, for example PC400.

System wait
SystemWait boolean

Returns true if the terminal emulator is reporting that the system is currently waiting for an action to complete, or false if not.

CAPS
CAPS boolean

Returns true if the terminal emulator is reporting that the CAPS key is currently pressed, or false if not.

Shift key
ShiftKey boolean

Returns true if the terminal emulator is reporting that the SHIFT key is currently pressed, or false if not.

Subsystem ready
SubsystemReady boolean

Returns true if the terminal emulator is reporting that the subsystem is ready, or false if not.

Insert mode
InsertMode boolean

Returns true if the terminal emulator is reporting that insert mode is currently enabled, or false if not.

Invalid input
InvalidInput boolean

Returns true if the terminal emulator is reporting that the Mainframe session is currently in an invalid input state, or false if not.

Input type
InputType string

The Mainframe session input type. This can be either APL, Katakana, Alphanumeric, Hiragana or Double-byte.

Query terminal emulation session status

Returns information about the connected Mainframe session. Some terminal emulators may not return values for all outputs.

Parameters

Name Key Required Type Description
Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
Session long name
SessionLongName string

The Mainframe session long name, for example SessionA.

Session type
SessionType string

The Mainframe session type, for example 3270 or 5250.

Number of rows
NumberOfRows integer

The number of rows in the display.

Number of columns
NumberOfCols integer

The number of columns in the display.

Code page
CodePage integer

The code page, indicating the character encoding being used.

Read terminal emulation screen at cursor position

Reads the specified number of characters from the Mainframe session, starting at the specified cursor position.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Cursor row index
CursorRowIndex True integer

The current cursor row index.

Cursor column index
CursorColIndex True integer

The current cursor column index.

Number of characters to read
ReadScreenLength True integer

The number of characters to read from the Mainframe session.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
Screen contents
ScreenContents string

The screen contents that was read from the Mainframe session.

Read terminal emulation screen rows

Reads the screen rows from a specified Mainframe session. This action is commonly used to read larger quantities of data which can then be filtered if necessary.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Start row index
StartRowIndex True integer

The start row index to begin reading from.

End row index
EndRowIndex True integer

The end row index to stop reading at.

Number of rows in session
NumberOfRowsInSession integer

The number of rows being displayed by the session. If set to 0, IA-Connect will query the session to retrieve the number of rows.

Number of columns in session
NumberOfColumnsInSession integer

The number of columns being displayed by the session. If set to 0, IA-Connect will query the session to retrieve the number of columns.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
Screen rows JSON
ScreenRowsJSON string

The rows read from the Mainframe session, in JSON format.

Reset terminal emulation session

Resets the current Mainframe session. The action disconnects IA-Connect Agent from the session and undoes any session parameters that have been set. After calling this action you will need to re-connect to the session by using the 'Connect to Session' action in order to continue interacting with it.

Parameters

Name Key Required Type Description
Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Search for string in terminal emulation session

Searches for a specified string in the current display of the terminal emulator. If the string is found, it's position and index will be returned.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Search string
SearchString True string

The string to be searched for.

Search entire screen
SearchEntireScreen boolean

Should the entire screen be searched? If set to false then the 'Search start row index' and 'Search start column index' inputs can be used to restrict the search area.

Search start row index
SearchStartRowIndex integer

The row index at which to start searching for the specified string, starting from 1. This value will only be used if 'Search entire screen' is set to false.

Search start column index
SearchStartColIndex integer

The column index at which to start searching for the specified string, starting from 1. This value will only be used if 'Search entire screen' is set to false.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
String found
StringFound boolean

Returns true if the specified string was found.

String found position
StringFoundPosition integer

If the string was found, this parameter holds the absolute position of the first character in the search string. For example, assuming a 24 row by 80 column session, the position would be returned as 321 if the string was found in the first column of the fifth row as the fifth row would contain positions 321 to 400.

String found row index
StringFoundRowIndex integer

If the string was found, this parameter holds the row index of the first character in the search string.

String found column index
StringFoundColIndex integer

If the string was found, this parameter holds the column index of the first character in the search string.

Send password to terminal emulation session

Sends a password to a Mainframe session at the current cursor position. If you wish to send a password to a specific cursor position, you can use the action 'Send password to terminal emulation session at position' instead.

Parameters

Name Key Required Type Description
Input password
InputPassword True password

The password to be input. This supports a full set of keyboard symbols, for example '@E' for enter.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Send password to terminal emulation session at position

Sends a password to a Mainframe session at the specified cursor position.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Cursor row index
CursorRowIndex True integer

The current cursor row index.

Cursor column index
CursorColIndex True integer

The current cursor column index.

Input password
InputPassword True password

The password to be input. This supports a full set of keyboard symbols, for example '@E' for enter.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Send reset key to terminal emulation session

Sends a reset key to the terminal emulator session. This will reset all input and will clear an invalid input state.

Parameters

Name Key Required Type Description
Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Send string to terminal emulation session

Sends a string to a Mainframe session at the current cursor position. If you wish to send a string to a specific cursor position, you can use the action 'Send string to terminal emulation session at position' instead.

Parameters

Name Key Required Type Description
Input string
InputString True string

The string to be input. This supports a full set of keyboard symbols, for example '@E' for enter.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Send string to terminal emulation session at position

Sends a string to a Mainframe session at the specified cursor position.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Cursor row index
CursorRowIndex True integer

The current cursor row index.

Cursor column index
CursorColIndex True integer

The current cursor column index.

Input string
InputString True string

The string to be input. This supports a full set of keyboard symbols, for example '@E' for enter.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Set session parameter in terminal emulation session

This action sets an advanced HLLAPI session parameter. This action should only be used if you are familiar with HLLAPI session parameters.

Parameters

Name Key Required Type Description
Parameter
Parameter True string

The HLLAPI parameter(s) to set. Multiple parameters can be separated by commas or spaces.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Set terminal emulation cursor position

Sets the current cursor position in a Mainframe session to the specified position.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Cursor row index
CursorRowIndex True integer

The cursor row index at which to set the cursor.

Cursor column index
CursorColIndex True integer

The cursor column index at which to set the cursor.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Set terminal emulation HLLAPI DLL

Starts the IA-Connect HLLAPI subsystem (IA-HLLAPI) and connects it to the specified Terminal Emulator HLLAPI DLL (a component of the terminal emulation software being used to connect to Mainframe sessions).

Parameters

Name Key Required Type Description
HLLAPI DLL filename
DLLFilename True string

The full file path to the HLLAPI DLL provided by the emulator.

IA-HLLAPI filename
IAHLLAPIPath string

The optional location of the IA-HLLAPI 32bit COM DLL used as a COM interface to the specified HLLAPI DLL (only if the HLLAPI DLL is 32bit). This is typically not required as IA-Connect has a built-in HLLAPI DLL named 'IA-HLLAPI.DLL' which is used to setup the COM interface to the emulator's HLLAPI DLL. By default, IA-Connect extracts this to the '%TEMP%\IA-Connect' directory in the user's profile.

Entry point name
EntryPointName string

The DLL entry point name. This varies depending on the emulator software being used and if left blank then IA-Connect will try the following common entry points: hllapi, HLLAPI, HLLAPI32, EHLLAPI, EHLLAPI32.

Is enhanced interface
IsEnhancedInterface boolean

This parameter should be set to true if the DLL uses the HLLAPI enhanced interface.

Is 64bit HLLAPI DLL
Is64BitHLLAPIDLL boolean

This parameter should be set to true if the HLLAPI DLL you are trying to load is 64bit.

Use COM for 64bit HLLAPI DLL
UseCOMFor64BitHLLAPIDLL boolean

Set to true if the HLLAPI DLL you are trying to load is 64bit and you want to run it via an out-of-process COM DLLSurrogate instead of calling directly (in memory) from IA-Connect.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Wait for string in terminal emulation session

Waits for a specified string to be displayed in the terminal emulator session. This action can be used when moving between screens to validate that you are on the correct screen.

Parameters

Name Key Required Type Description
Session ID
SessionID True string

The single character Mainframe session ID, for example A.

Search string
SearchString True string

The string to wait for.

Search entire screen
SearchEntireScreen boolean

Should the entire screen be searched? If set to false then the 'Search start row index' and 'Search start column index' inputs can be used to restrict the search area.

Search start row index
SearchStartRowIndex integer

The row index at which to start searching for the specified string, starting from 1. This value will only be used if 'Search entire screen' is set to false.

Search start column index
SearchStartColIndex integer

The column index at which to start searching for the specified string, starting from 1. This value will only be used if 'Search entire screen' is set to false.

Seconds to wait
SecondsToWait True double

The maximum number of seconds to wait for the specified string to be displayed.

Delta seconds to wait
DeltaSecondsToWait double

The number of seconds between each search for the specified string.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
String found
StringFound boolean

Returns true if the specified string was found before the maximum wait period.

String found position
StringFoundPosition integer

If the string was found, this parameter holds the absolute position of the first character in the search string. For example, assuming a 24 row by 80 column session, the position would be returned as 321 if the string was found in the first column of the fifth row as the fifth row would contain positions 321 to 400.

String found row index
StringFoundRowIndex integer

If the string was found, this parameter holds the row index of the first character in the search string.

String found column index
StringFoundColIndex integer

If the string was found, this parameter holds the column index of the first character in the search string.

Wait for terminal emulation keyboard unlocked

Waits for the terminal emulator to report that the keyboard is unlocked. The output of this action is dependent on how the specific emulator has implemented HLLAPI and the output may vary from emulator to emulator.

Parameters

Name Key Required Type Description
Seconds to wait
SecondsToWait True double

The maximum number of seconds to wait for the terminal emulator to report that the keyboard is unlocked.

Delta seconds to wait
DeltaSecondsToWait double

The number of seconds between each query to the terminal emulator to check the keyboard unlock status.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
Keyboard is unlocked
KeyBoardIsUnlocked boolean

Returns true if the terminal emulator is reporting that the keyboard is unlocked.

Wait for terminal emulation system ready

Waits for the terminal emulator to report that the system is ready. The output of this action is dependent on how the specific emulator has implemented HLLAPI and the output may vary from emulator to emulator.

Parameters

Name Key Required Type Description
Seconds to wait
SecondsToWait True double

The maximum number of seconds to wait for the terminal emulator to report that the system is ready.

Delta seconds to wait
DeltaSecondsToWait double

The number of seconds between each query to the terminal emulator to check the system status.

Workflow
Workflow True string

Add the following expression here: workflow()

Returns

Name Path Type Description
System is ready
SystemReady boolean

Returns true if the terminal emulator is reporting that the system is ready.