Terminal - Connect

Declaration

<AMTERMINAL TYPE="text (options)" HOST="text" SESSION="text" PORT="number" SHOWTERMINALWINDOW="YES/NO" TERMINALCLOSE="YES/NO" EMULATION="text (options)" TERMINALTYPE="text (options)" FONTSIZE="number" TRYSIGNOFF="YES/NO" SSL="YES/NO" SSLVERSION="text (options)" ROOTCACERTIFICATEFILE="text" CLIENTCERTIFICATEFILE="text" KEYCERTIFICATEFILE="text" CRTIFICATEPASSWORD="text (encrypted)" PROMPT="text" PROMPTISRE="YES/NO" WAITFORPROMPT="YES/NO" PROMPTTIMEOUT="number" MEASURE="text (options)" LOGFILE="text" ENCRYPTIONALGORITHMS="text (options)" AUTHENTICATIONMETHOD="text (options)" PRIVATEKEY="text" PASSPHRASE="text (encrypted)" OVERWRITELOG="YES/NO" />

Related Topics

Description

Connects to a terminal using the specified emulation type and establishes a new terminal session which can be used in subsequent terminal related steps.

Practical usage

Used to begin a transaction with a terminal. This activity is used in conjunction with other terminal activities such as Terminal - Get text, Terminal - Control, or Terminal - Send text. These activities are used in lieu of terminal emulation software. By using Automate Desktop's terminal activities, legacy systems can be automated in the background without the use of 3rd party software.

Parameters

General

Property Type Required Default Markup Description
Connection type Text (options) No TCP/IP
  • TYPE="TCP/IP"
  • TYPE="SSH"
The type of terminal connection to perform. If unsure which to use, check with the administrator of the terminal. The available options are:
  • TCP/IP: Connection is established using TCP/IP.
  • SSH: Connection is established using a secure socket.
Hostname Text Yes (Empty) HOST="ftp.netauto.com" The IP address (for example, xxx.xxx.xxx.xxx) or a server/domain name (for example, server.domain.com) of the host server to connect to.
Port Number No 23 PORT="25" The port to for TCP/IP, SSH, or SSL/TLS connections. The default port numbers for each connection type are as follows:
  • TCP/IP - 23

  • SSH - 22

  • SSL/TLS - 992

Username Text No (Empty) USERNAME="Anonymous" The username to use to authenticate and log in to an SSH server. The username should be pre-configured at the server level. This parameter is becomes available only if the Connection type parameter is set to SSH.
Password Text No (Empty) PASSWORD="encrypted" The password that corresponds with the Username parameter. This parameter becomes available if the Connection type parameter is set to SSH.
Session Text No TerminalSession1 SESSION="mySession" The session name to identify this terminal connection request in subsequent terminal steps. This allows several terminal sessions to be active simultaneously.
NOTE: If you are only using one connection at a time, you do not need to specify a value other than the default, which is TerminalSession1.
Show terminal window Yes/No No No SHOWTERMINALWINDOW="YES" If selected, a window will be displayed at runtime showing the results of the terminal transaction. This option is normally enabled while debugging the task so that the developer can see what is occurring in the session. It is normally disabled during production so that the transaction occurs in the background and does not interfere with other tasks. This parameter is disabled by default.
Close after completion Yes/No No Yes TERMINALCLOSE="NO" If selected, the terminal window automatically closes after task execution. If disabled, the window remains open after task execution to allow manual work to be performed in the window, if desired. This parameter is selected by default.

Advanced

Property Type Required Default Markup Description
Emulation No No ANSI
  • EMULATION="tty"
  • EMULATION="ansi"
  • EMULATION="vtT52"
  • EMULATION="vt100"
  • EMULATION="vt220"
  • EMULATION="vt320"
  • EMULATION="tn3270"
  • EMULATION="tn5250"

 

 

The type of terminal emulator that should be used. If you are unsure of the value to use in this parameter, contact your server administrator. The available options are:
  • TTY - Use the TTY terminal emulation standard.
  • ANSI (default) - Use the ANSI terminal emulation standard.
  • VT52 - Use the VT52 terminal emulation standard.
  • VT100 - Use the VT100 terminal emulation standard.
  • VT220 - Use the VT220 terminal emulation standard.
  • VT320 - Use the VT320 terminal emulation standard.
  • TN3270 - Use the TN3270 terminal emulation standard.
  • TN5250 - Use the TN5250 terminal emulation standard.
Resource Name Text No (Empty) RESOURCENAME="resources>" The resource name is a generic term for any of the following names: LU name, device name or device pool name. You may specify a Windows environment variable as the resource name. For example, if you specify %username%, it will be replaced by the Windows username when it is sent to the host. You may also specify a semicolon delimited list of resource names (for example, DEC-VT220;VT220;DEC-VT100;VT100). If the first resource is in use, then the session attempts to use the second, and so on. This parameter is available only when the Emulation parameter is set to TN3270 or TN5250.
Terminal type Text (options) Yes, if Emulation is set to TN3270 or TN5250
  • IBM-3278-2-E (TN3270)

  • IBM-3179-2 (TN5250)

  • TERMINALTYPE="IBM3278m2"
  • TERMINALTYPE="IBM3278m2E"
  • TERMINALTYPE="IBM3278m3"
  • TERMINALTYPE="IBM3278m3E"
  • TERMINALTYPE="IBM3278m4"
  • TERMINALTYPE="IBM3278m4E"
  • TERMINALTYPE="IBM3278m5"
  • TERMINALTYPE="IBM3278m5E"
  • TERMINALTYPE="IBM3179m2"
  • TERMINALTYPE="IBM3477mFC"
  • TERMINALTYPE="IBM3180m2"
  • TERMINALTYPE="IBM3477mFG"
  • TERMINALTYPE="IBM3196mA1"
  • TERMINALTYPE="IBM5292m2"
  • TERMINALTYPE="IBM5291m1"
  • TERMINALTYPE="IBM5251m11"
Specifies the terminal window resolution to use with emulation type TN3270 or TN5250. This parameter is available only when the Emulation parameter is set to TN3270 or TN5250.

The available options for TN3270 are:

  • IBM-3278-2

  • IBM-3278-2-E (default)
  • IBM-3278-3
  • IBM-3278-3-E

  • IBM-3278-4

  • IBM-3278-4-E

  • IBM-3278-5

  • IBM-3278-5-E

The available options for TN5250 are:

  • IBM-3179-2 (default)

  • IBM-3477-FC

  • IBM-3180-2

  • IBM-3477-FG

  • IBM-3196-A1

  • IBM-5292-2

  • IBM-5291-1

  • IBM-5251-11

For more information on these terminal types, see https://www.ibm.com/docs/en/i/7.4?topic=problems-troubleshooting-emulation-types.

Try sign off at disconnect Yes/No No Yes TRYSIGNOFF="YES" If selected (default), Automate Desktop navigates to the main IBM screen at runtime and sends a SIGNOFF command to attempt to end the job. This parameter is only available when the Emulation parameter is set to TN3270 or TN5250.
Font size Number No (Empty) FONTSIZE="10" Sets the font size of the terminal text for emulation types TN3270 and TN5250. The font size can range from 1-1000 (for example, 10). If no value is entered, a default size is used, based on the emulation type. This parameter is only available when the Emulation parameter is set to TN3270 or TN5250.
SSL Yes/No No No SSL="YES" If selected, this parameter allows the Terminal action to be configured to use a SSL/TLS connection. The default port number for SSL/TLS is 992. This parameter is only available when the Emulation parameter is set to TN3270 or TN5250 and is disabled by default.
SSL/TLS version Text (options) Yes, if Emulation is set to TN3270 or TN5250 TLS1.x
  • SSLVERSION="TLS"
  • SSLVERSION="SSL3"
Specifies the SSL/TLS version to use with the connection. This parameter is only available when the SSL parameter is selected. The available options are:
  • TLS1.x
  • SSL3.0
Root CA Certificate File Text No (Empty) ROOTCACERTIFICATEFILE="rootcacertificate.txt" The Root CA Certificate file to use with the SSL/TLS connection. This parameter is only available when the SSL parameter is selected.
Client Certificate File Text No (Empty) CLIENTCERTIFICATEFILE="clientcertificate.txt" The Client Certificate file to use with the SSL/TLS connection. This parameter is only available when the SSL parameter is selected.
Key File Text No (Empty) KEYCERTIFICATEFILE="keycertificatefile.txt" The Key Certificate file to use with the SSL/TLS connection. This parameter is only available when the SSL parameter is selected.
Certificate Password Text No (Empty) CRTIFICATEPASSWORD="text (encrypted)" The Certificate Password to use with the SSL/TLS connection. This parameter is only available when the SSL parameter is selected.
Default prompt Text No (Empty) PROMPT="READY>" The prompt that appears in the target terminal system. This allows subsequent terminal activities to wait until a certain prompt appears before executing. For example, on some terminal systems, the prompt is the text READY>. By specifying this value, Automate Desktop will know to wait until that text appears before moving onto the next step.
Regular expression Yes/No No No PROMPTISRE="YES" If selected, indicates that the text specified in the Default prompt parameter is a regular expression and not literal text. Specifying a regular expression can be useful This is useful in cases where the prompt may not always be the same but some portion of it is. This parameter is disabled by default.
Wait for default Prompt Yes/No No No WAITFORPROMPT="YES" If selected, indicates that the step will wait the for the default prompt to appear until the specified amount of time. If the default prompt does not appear within the amount of time specified, execution halts with a time-out error. If this parameter is disabled (default), the step will wait indefinitely.    
Time to wait (unlabeled) Number No 10000 PROMPTTIMEOUT="233" The length of time allowed to wait for the default prompt before a time out error is thrown. This parameter corresponds with the time measurement specified in the Measure parameter below.
Measure (unlabeled) Text (options) No milliseconds
  • MEASURE="milliseconds"
  • MEASURE="seconds"
  • MEASURE="minutes"
  • MEASURE="hours"
The time measurement that corresponds with the value entered in the Time to wait parameter. The available options are:
  • Milliseconds (default) - Time to wait value will be measured in milliseconds.
  • Seconds -  Time to wait value will be measured in seconds.
  • Minutes -  Time to wait value will be measured in minutes.
  • Hours -  Time to wait value will be measured in hours.
Key-Exchange algorithm(s) Text (Options) Yes Any
  • ENCRYPTIONALGORITHMS="Any"
  • ENCRYPTIONALGORITHMS="Curve25519"
  • ENCRYPTIONALGORITHMS="DiffieHellmanGroup14SHA1"
  • ENCRYPTIONALGORITHMS="DiffieHellmanGroup1SHA1"
  • ENCRYPTIONALGORITHMS="DiffieHellmanGroupExchangeSHA1"
  • ENCRYPTIONALGORITHMS="DiffieHellmanGroupExchangeSHA256"
  • ENCRYPTIONALGORITHMS="DiffieHellmanOakleyGroupSHA256"
  • ENCRYPTIONALGORITHMS="DiffieHellmanOakleyGroupSHA512"
  • ENCRYPTIONALGORITHMS="ECDiffieHellmanNistP256"
  • ENCRYPTIONALGORITHMS="ECDiffieHellmanNistP384"
  • ENCRYPTIONALGORITHMS="ECDiffieHellmanNistP521"
  • ENCRYPTIONALGORITHMS="None"
The key exchange algorithm to use during a SSH session. The available options are:
  • Any - Uses any of the algorithms available for this parameter.
  • Curve25519 - Elliptic Curve Diffie-Hellman key exchange based on Curve 25519 (only available through a plugin) with SHA-256.
  • DiffieHellmanGroup14SHA1 - Diffie-Hellman (Oakley Group 14) with SHA-1.
  • DiffieHellmanGroup1SHA1 - Diffie-Hellman (Oakley Group 2) with SHA-1.
  • DiffieHellmanGroupExchangeSHA1 - Diffie-Hellman (Group Exchange) with SHA-1.
  • DiffieHellmanGroupExchangeSHA256 - Diffie-Hellman (Group Exchange) with SHA-256.
  • DiffieHellmanOakleyGroupSHA256 - Diffie-Hellman (Oakley Group 14) with SHA-256.
  • DiffieHellmanOakleyGroupSHA512 - Diffie-Hellman (Oakley Group 15 or 16) with SHA-512.
  • ECDiffieHellmanNistP256 - Elliptic CurveDiffie-Hellman key exchange based on NIST P-256 curve (.NET >=4.0 or through a plugin) with SHA-256.
  • ECDiffieHellmanNistP384 - Elliptic Curve Diffie-Hellman key exchange based on NIST P-384 curve (.NET >=4.0 or through a plugin) with SHA-384.
  • ECDiffieHellmanNistP521 - Elliptic Curve Diffie-Hellman key exchange based on NIST P-521 curve (.NET >=4.0 or through a plugin) with SHA-512.
  • None - Omits the use of an algorithm.
NOTE: This parameter is not available if the Emulation parameter is set to TN3270 or TN5250.
Authentication Method Text (Options) Yes Any
  • AUTHENTICATIONMETHOD="Any"
  • AUTHENTICATIONMETHOD="KeyboardInteractive"
  • AUTHENTICATIONMETHOD="None
  • AUTHENTICATIONMETHOD="Password"
  • AUTHENTICATIONMETHOD="PublicKey"
The authentication method to use during a SSH session. The available options are:
  • Any - Uses any of the methods available for this parameter.
  • KeyboardInteractive - Authentication method "keyboard-interactive".
  • None - Omits the use of an authentication method.
  • Password - Authentication method "password".
  • PublicKey - Authentication method "publickey".
NOTE: This parameter is not available if the Emulation parameter is set to TN3270 or TN5250.
Private key file Text No Empty PRIVATE_KEY="C:\Temp\Private_Key_Location" Specifies the path and file name of the private key file. This parameter only becomes available if the Authentication Method parameter is set to PublicKey.
Passphrase Text No Empty PASSPHRASE="passphrase" Specifies the pass phrase used to authenticate connection. A pass phrase is a password that comprises a whole phrase. This parameter only becomes available if the Authentication Method parameter is set to PublicKey.
Log file Text (options) No (Empty)

LOGFILE="c:\temp\log.log"

The path and file name of a log file in which to log data about the terminal connection. This log file can be useful in diagnosing particular errors or elusive connection problems.
Overwrite existing log file Yes/No No No

OVERWRITELOG="NO"

If selected, specifies that the log file should be overwritten with new log data if the same file already exists. If disabled (default), the file will not be overwritten, however, an error will occur at runtime as a result. The default value is YES.

Description

Error Causes

On Error

Examples

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Example 1

This sample task connects to a terminal.

Copy
<AMTERMINAL HOST="linux.networkautomation.com" SESSION="TerminalSession1" SHOWTERMINALWINDOW="YES" EMULATION="tn3270" RESOURCENAME="a" PROMPT="as" PROMPTISRE="YES" WAITFORPROMPT="YES" PROMPTTIMEOUT="233" MEASURE="seconds" />

Example 2

This sample task uses an assortment of terminal activities to automate a terminal logon process. Examining the step parameters and properties of this task may assist you in creating your own terminal emulation task.

Copy
<AMVARIABLE NAME="theUsername" VALUE="Username" />
<AMVARIABLE NAME="thePassword" VALUE="password"></AMVARIABLE>
<AMTERMINAL HOST="linux.networkautomation.com" SESSION="TerminalSession1" SHOWTERMINALWINDOW="YES" EMULATION="vt220" ENCRYPTIONALGORITHMS="Any" AUTHENTICATIONMETHOD="Any" />
<AMTERMINAL ACTIVITY="waitfor" SESSION="TerminalSession1" TEXT="login" />
<AMTERMINAL ACTIVITY="sendtext" SESSION="TerminalSession1" TEXT="%theUsername% {ENTER}" />
<AMSHOWDIALOG MESSAGE="OK to proceed?"></AMSHOWDIALOG>
<AMTERMINAL ACTIVITY="waitfor" SESSION="TerminalSession1" TEXT="Password" />
<AMTERMINAL ACTIVITY="sendtext" SESSION="TerminalSession1" TEXT="%thePassword% {ENTER}" />
<AMSHOWDIALOG MESSAGE="OK to proceed?"></AMSHOWDIALOG>
<AMTERMINAL ACTIVITY="disconnect" SESSION="TerminalSession1" />