Terminal Session

UiPath.Terminal.Activities.TerminalSession

A container that connects to a terminal and enables you to perform multiple actions within it. Once the activity is dragged into the workflow designer, the Configure Connection window is opened. If closed, it can be reopened by using the Configure Connection... button in the body of the activity.

Once a connection is set up, the Start Recorder button can be used to connect to the terminal and record the necessary actions. The button is placed in the body of the activity.

Properties

Common

• Continue on error - Specifies if the automation should continue even when the activity throws an error. This field only supports Boolean values (True, False). The default value is False. As a result, if the field is blank and an error is thrown, the execution of the project stops. If the value is set to True, the execution of the project continues regardless of any error.

  Note: If this activity is included in Try Catch and the value of the Continue on error property is True, no error is caught when the project is executed.
• DisplayName - The display name of the activity.

Misc

• Private - If selected, the values of variables and arguments are no longer logged at Verbose level.

New Session

• Connection String - The string that contains the connection details. This field supports only strings and String variables.
• Output Connection - The established connection, stored in a TerminalSession variable. This variable can be passed on to other Terminal Session activities in the Existing Connection property field if you want to reuse the connection that is already established. This field supports only TerminalSession variables.

Options

• DelayMS - Delay time (in milliseconds) before the activity begins performing any operations. The default value is 1000 milliseconds (1 second).
• TimeoutMS - Specifies the amount of time (in milliseconds) to wait for the activity to run before an error is thrown. The default value is 50000 milliseconds (50 seconds).

SSH Connection Properties

• SSH Password - The SecureShell password used to connect to the specified terminal, stored in a SecureString variable. This field supports only SecureString variables.
• SSH Username - The SecureShell username used to connect to the specified terminal, stored in a String variable. This field supports only strings and String variables.

Use Existing Connection

• Close Connection - If this check box is selected, the existing connection is closed after the activity stops execution. By default, this check box is selected. Please note that this property is ignored if the Output Connectionproperty is set.
• Existing Connection - Supplying a TerminalSession variable in this property field uses the connection stored in the variable to connect to a terminal. This field supports only TerminalSession variables.

The Configure Connection window

The Configure Connection window contains various configuration options that vary depending on the type of provider chosen for making the connection to the terminal environment.

Properties independent of the chosen provider:

• Show Client Application - If checked, displays a view of the terminal screen at runtime.

The Direct Connection provider

The Direct Connection provider is a UiPath internal provider that does not need any 3rd party terminal emulation software on the robot machine. The emulation is done by the robot, at runtime.

Configuration properties:

• Address - IP address or host name of the terminal environment system.
• Port - A port number where the terminal environment system accepts connections.

• Type - The type of terminal emulation needed:

  • TN3270 - Commonly used by IBM Z-series systems
  • TN5250 - Commonly used by IBM I-series systems (AS-400)
  • VT - DEC VT compatible terminals
  • HP Series - HP specific terminal emulation
  • Tandem - Tandem Systems terminal emulation
  • Wyse - Wyse series terminal emulation
  • ANSI - Terminal emulation based on the ANSI specification
  • Sco ANSI - Extension of the ANSI specification used by SCO Unix systems

• Protocol - The communication protocol to be used for the connection:

  • Telnet - The Telnet protocol
  • SSH - The SSH protocol used by most Unix/Linux systems
  • HPVT - HP specific protocol used in conjunction with the HP Series terminal emulation
• Terminal Mode - The specific flavor of terminal emulation. The value available here is dependent on the value chosen in the Type field.
• Encoding - The codepage used by the terminal environment system. The default is IBM037 for the IBM family terminals and ASCII for other types of terminals.
• Enable SSL/TLS - Used in conjunction with the Telnet protocol, to specify that the terminal environment system uses an SSL or TLS encrypted connection.
• LU Name - The logical unit name, used with the IBM family terminal types.
• Answerback - A text message to be sent to the host system when the terminal receives the ENQ control character. The message can contain the Enter control key, encoded in the string value as ^M. This configuration option is available only when the selected terminal type is VT.

The IBM EHLLAPI provider

The IBM EHLLAPI provider works with any 3rd party terminal emulation software that implements the EHLL API. The details for the implementation of the EHLL API should be found in the 3rd party terminal emulator software documentation.

Note: The terminal emulation software needs to be started and connected before attempting to connect to it via EHLLAPI.

Configuration properties:

• EHLL dll - The path to the dll used for implementing the EHLLAPI in the 3rd party terminal emulator software.
• EHLL function - The name of the entry point function in the EHLL dll. Usually, “hllapi”.
• EHLL session - The name of the session as it appears in the terminal emulation software. Usually “A”, but when using multiple simultaneous sessions, the value may vary.
• EHLL encoding - The encoding used by the terminal emulation software for the given connection.
• EHLL enhanced - Used to specify if the 3rd party terminal emulator implements the standard or enhanced version of the EHLL API.
• Encoding - The codepage used by the terminal environment system. The default is IBM037 for the IBM family terminals and ASCII for other types of terminals.
• Basic mode - A mode that disables field level processing for better performance. Note that field level activities (Get Field, Set Field, etc) will not be working in this mode.
• Run in process - Controls the way the communication with the 3rd party terminal emulation is made via EHLL API. By default, this is disabledand in this case the communication is done via a proxy process, a different executable that is part of the terminal activities package. At runtime, the proxy process will communicate with the UiPath Executor process via IPC (Inter-Process communication). When enabled, communication with the 3rd party terminal emulation software is made inside the UiPath Executor process. This option should be enabled only if the proper functioning of the proxy process is prevented by antivirus software or by software security policies.

Note: Due to a limitation in the specification of the EHLLAPI, the enhanced version of EHLLAPI does not support working with multiple EHLLAPI sessions when the Run in process option is checked. Only the standard implementation of EHLLAPI supports such a scenario. This means that the EHLL enhanced option is unchecked and the DLL file listed in the EHLL dll field is a version that implements the standard EHLLAPI specification.

The Attachmate Reflection provider

The Attachmate Reflection provider works with the Attachmate Reflection terminal emulator.

Configuration properties:

• Attach to existing session - In this mode, the terminal emulator is expected to be already started and connected. No configuration profile will be used in this case.
• Use an existing profile - In this mode, the path to a configuration profile needs to be provided. The terminal emulator will be started automatically.

• Manually specify address - In this mode, no configuration profile will be used. The configuration properties need to be specified manually:

  • Address - IP address or host name of the terminal environment system
  • Port - A port number where the terminal environment system accepts connections

  • Type - The type of terminal emulation needed:

    • TN3270
    • TN5250
    • VT

The Attachmate Extra provider

The Attachmate Extra provider works with the Attachmate Extra! terminal emulator.

Configuration properties:

• Use an existing profile - A path to a configuration profile needs to be provided. The terminal emulator will be started automatically.

The Reflection for UNIX provider

The Reflection for UNIX provider works with the Reflection for Unix terminal emulator.

Configuration properties:

• Use an existing profile - A path to a configuration profile needs to be provided. The terminal emulator will be started automatically.

The Reflection for IBM provider

The Reflection for IBM provider works with Reflection for IBM terminal emulator.

Configuration properties:

• Use an existing profile - In this mode, the path to a configuration profile needs to be provided. The terminal emulator will be started automatically.

• Manually specify address - In this mode, no configuration profile will be used. The configuration properties need to be specified manually:

  • Address - IP address or host name of the terminal environment system
  • Port - A port number where the terminal environment system accepts connections

  • Type - The type of terminal emulation needed:

    • TN3270
    • TN5250
    • VT

The Rocket BlueZone provider

The Rocket BlueZone provider works with the Rocket BlueZone terminal emulator.

Configuration properties:

• Use an existing profile - In this mode, the path to a configuration profile needs to be provided. The terminal emulator will be started automatically.

• Manually specify address - In this mode, no configuration profile will be used. The configuration properties need to be specified manually:

  • Address - IP address or host name of the terminal environment system.
  • Port - A port number where the terminal environment system accepts connections.

  • Type - The type of terminal emulation needed:

    • TN3270
    • TN5250
    • VT

The IBM Personal Communications provider

The IBM Personal Communications provider works with the IBM Personal Communications terminal emulator.

Configuration properties:

• Use an existing profile - In this mode, the path to a configuration profile needs to be provided. The terminal emulator will be started automatically.

Terminal activities best practices

• When using the Output Connection/Existing Connection properties, make sure to close the Terminal Session when it is no longer needed in the workflow/process. Leaving the Terminal Session open can have adverse effects on performance and on the execution of other Terminal sessions. To properly close a previously saved Terminal Session, add a new Terminal Session (with an empty body) to your workflow, with the following properties:
  • Close Connection: True
  • Existing Connection: The TerminalSession variable that contains the saved session
• Avoid using the Output Connection/Existing Connection properties in conjunction with the IBM EHLLAPI provider. These options are used for ensuring the connection persistence between workflows. Since the connection is already persisted in the terminal emulator, a second layer of persistence is not needed. Also, this avoids having to perform the extra steps to close the connection as described above.
• Avoid using Terminal Sessions nested in other Terminal Sessions. This also applies to indirect nesting, such as calling from a Terminal Session body a workflow that contains a Terminal Session with the same connection, or calling a library function that contains a Terminal Session with the same connection.
• Avoid using field-based activities like Get Field/Set Field. It is not always clear if or how the screen is split into fields, which may lead to confusion. Also, different providers may split the same screen in different ways because different APIs are used. It is safer to use methods similar to what humans will use, like combinations of Move Cursor or Send Control Key = Tab followed by Send Keys activities for sending data to the screen. For retrieving data from the screen use Get Screen Area or Get Text At Position.
• Use the Wait Screen Text activity to make sure the correct screen was loaded before doing any operations on it
• For extracting tabular data from screens in a DataTable format, use the Get Screen Area activity for the part of the screen containing the table and use the output of this activity as input for the Generate Data Table activity, from the UiPath.System.Activities package.