6.2 Commands

Use with

Startup, Terminal Launcher, Web or Windows

Type

Action

Arguments

Method

The name of the advanced authentication method you wish to use. If not specified, AAVerify uses the method that was chosen during initial authentication to the directory.

User

The name of the user you wish to use for the AAVerify command. If not specified, AAVerify re-authenticates the currently logged on user.

Tree

The name of the tree the user is in. You must use this with the User argument.

Description

Use AAVerify with SecureLogin re-authentication, Novell Modular Authentication Service (NMAS), or Novell Lightweight Directory Access Protocol (LDAP) to verify the user. It is typically used before the application user name and password are retrieved and entered into the login box.

This provides application re-authentication using a strong login method. For example, a user might be forced to enter their smart card and PIN before the application will log on using SSO, even though the application natively knows nothing about smartcard and PIN. If the verification succeeds, the [?Result] is set to true, otherwise it is set to false. These additions are for SecureLogin and NMAS.

SecureLogin re-authentication may use one of the following methods:

You can specify more than one method arguments. A user is allowed to re‑authenticate with any of the specified methods. For example, you can use the command to request authentication using a fingerprint reader or smart card.

NMAS or Novell LDAP-specific

The method should be the name of the sequence as defined in the environment.

If AAVerify is called with no arguments, then the currently logged in user is re‑authenticated using different login methods based on the following scenarios:

Example 1

Windows application definition

This example detects the login dialog box. Before SecureLogin enters credentials, it prompts the user to provide the re-authentication credentials. The credentials are not submitted until the re-authentication succeeds.

# Logon Dialog Box
Dialog
   Title "Log on"
EndDialog
AAVerify -Method "Enhanced Password" ?Result
If ?Result Eq "True"
   Type $Username #1001
   Click #1
Else
   Click #2
   MessageBox "Authentication failed. Please verify your smart card is inserted and your PIN is correct."
EndIf

Example 3

Windows application definition

The following example shows how to re-authenticate against the user's login method:

Dialog
   Title "Log on"
EndDialog

OnException AAVerifyFailed Call AAVerifyFailed
OnException AAVerifyCancelled Call AAVerifyCancelled

If ?isPin Eq "true"
   AAVerify -method "smartcard" ?result
Else
   AAVerify -method "password" ?result
EndIf

ClearException AAVerifyFailed
ClearException AAVerifyCancelled

Type $username
Type \n
Type $password
Type \n

Sub AAVerifyFailed
   Click #2
   MessageBox "Re-authentication failed."
   EndScript
EndSub

Sub AAVerifyCancelled
   Click #2
   EndScript
EndSub

Used with

Startup, Terminal Launcher, Web, or Windows

Type

Variable manipulator

Arguments

<Variable1>

The first argument, the number to which the second argument will be added. This argument will also contain the result of the addition equation if the optional [?Result] argument is not passed in. If used without the [?Result] argument, <Variable1> must be a SecureLogin variable. Otherwise, <Variable1> can be any numeric value.

<Variable2>

The second argument, the number added to the first argument in the equation. <Variable2> can be a SecureLogin variable or numeric value.

[?Result]

Optional, the sum or result of the equation.

Syntax examples

Add 1 2 ?Result
Add ?LoginAttempts ?LoginFailures
Add ?LoginAttempts ?LoginFailures ?Result
Add ?LoginAttempts 3
Add ?LoginAttempts 3 ?Result

Use with

Advanced Web application definition

Type

Specifier

Arguments

< Attribute Name>

Name of the HTML attribute to discover.

< Attribute Value>

The value the above HTML attribute must contain for the condition to be true.

Example

This example finds the form that has an attribute of Name with a value of Logon.

Tag "Form"   
Attribute "Name" "Logon"
EndTag

Use with

Startup, Terminal Launcher, Java, Web, or Windows application definitions to send an audit event to the Windows Event Log.

Type

Specifier

Arguments

<message>

The variable or text string passed to the Windows Event Log.

Example

If the Audit platform agent is not present on the workstation nothing will be logged.

AuditEvent "message"

The parameter “message” is passed to the Windows Event Log.

AuditEvent $message

The parameter $message variable is passed to the Windows Event Log.

Use with

Terminal Launcher (Generic and Advanced Generic only)

Type

Action

Arguments

None

Example

Terminal Launcher application definition

This example launches the emulator and the SecureLogin waits 2 seconds for it to connect. The splash screen is displayed to cover the flickering, the login field is detected, the user name is entered, then the splash screen disappears.

Delay 2000
BeginSplashScreen
WaitForText "Login:"
Type $Username
EndSplashScreen
Type @E

Use with

Advanced application definitions created using the Web Wizard, WinSSO, JavaSSO and .NetSSO workers.

Type

Action

Usage for the WinSSO, JavaSSO and .NetSSO workers

BooleanInput #ElementID "checked"BooleanInput #ElementID "unchecked"

Description

Used inside a Site block to set the state of a Boolean field (either a check box or radio button).

Use with

Startup, Terminal Launcher, Web, or Windows

Type

Action

Arguments

None

Example 1

Windows application definition

This example reads the screen and the content is searched for the words ‘log on’. If log on is found, the Repeat loop is broken and the application definition continues. If log on is not found, the application definition will check again.

Dialog   
   Class #32770   
   Title "Log on"
EndDialog
Repeat   
   ReadText  #301 "?Text"   
   If ?Text Eq "Log on" 
   Break   
   EndIf
Delay 100
EndRepeat

Account is locked for some reason, possibly inactive.   
If -Text "Account Locked" MessageBox "Your account has been locked, possibly due to inactivity for 40 days. Please contact the administrator on x453." EndIf # Main Menu, user has logged on #successfully. If -Text "Application Selection" Break   
EndIf
Delay100
EndRepeat

Use with

Startup, Terminal Launcher, Web, or Windows

Type

Flow control

Arguments

<SubRoutine>

The name of the subroutine called. This must be identical to the name given in the Sub command.

Example

Terminal application definition

This example looks for the word Username, if it is found on the screen the subroutine Log on is launched. If Wrong Password is found, the subroutine WrongPassword is launched.

Repeat   
If -Text "Username"      
   Call "Login"   
EndIf   
If -Text "Wrong Password"      
   Call "WrongPassword"   
EndIf
EndRepeat 
#==Login Subroutine==
Sub Login   
   Type $Username
   Type @E 
   Type $Password
   Type @E
EndSub
#==Wrong Password Subroutine==
Sub WrongPassword
   DisplayVariables "The password entered is incorrect. Please check your password and click OK to try again. IT x4532." 
   $Password  
   Call Login
EndSub

Use with

Startup, Terminal Launcher, Web, or Windows

Type

Action

Arguments

<Variable>

A normal or runtime variable in which the password is stored.

[Text]

The text you want displayed in the change password dialog box.

[Random]

Random will invoke the random password generator.

Syntax examples

ChangePassword $NewPassword
ChangePassword ?NewPassword "Please enter a new password"
ChangePassword ?NewPassword Random

Use with

Startup, Windows

Type

Dialog specifier

Arguments

<Window-Class>

A string specifying the window class that this statement will match.

Example

Windows application definition

This example checks the dialog box generated by the application to determine if the Window Class is #32770. If true and its title is log on, that section of the application definition will execute. If false, the application definition checks the next Dialog block.

# Logon Dialog Box
Dialog   
Class "#32770"    
Title "Log on"
EndDialog
Type $Username #1001
Type $Password #1002
Click #1

Use with

Web Wizard

Type

Action

Arguments

"SiteName"

The name of the site to clear, as specified in the matching Site/EndSite block that will be reset to initial.

Examples

In this example, the user is redirected to the Google home page and any previous user information is cleared.

GotoURL "http://www.google.com"

ClearSite Login

In this example, the ClearSite command is used with as part of conditional statement and if a particular condition is true the user information is cleared.

Site "Login" –subsequent

MatchURL "here.now.com"

endsite

MessageBox "Would you like to login again?" -yesno ?Continue

If ?Continue eq "Yes"

  Call LoginSub

Else

  ClearSite Login

EndIf

Use with

Web, WinSSO, JavaSSO and .NetSSO workers.

Type

Action

Web usage

Click <#Number>

Description

When used with Windows applications, the Click command sends a click instruction to the specified <#Ctrl-ID>.

You can set the –Raw flag if the button or control does not respond to the Click command. The –Raw flag causes SecureLogin to emulate the mouse and send a direct click message to the control. Using the -Right flag with the -Raw flag sends a right-click to the control.

Setting the <#Ctrl-ID> to 0 (zero) sends the click instruction to the window on which the application definition is running.

If -Raw is specified, then you can set the X coordinate and the Y coordinates. These coordinates are relative to the client area of the application, not the screen.

When used with web application definitions, the Click command takes a single argument, which is the sequential number on the page of the button to be pressed. Click #3 will click the third button on the page. Due to the web page layout and design, the sequential order of the buttons may not be obvious, and you may have to use the DumpPage command to discover the field layout (see DumpPage).

Example 1

Windows application definition

This example detects the login dialog box, the user name and password are entered, and button number 1 (in this case the logon button) is clicked.

# Logon Dialog Box
Dialog   
Class #32770  
Title "Log on"
EndDialog
Type $Username #1001
Type $Password #1002
Click #1

Example 3

Windows application definition

This example uses the Java application, so there is no control ID. Instead, the Click command is told to click a particular place on the window.

# Logon Dialog Box
Dialog   
Class #32770
Title "Log on"
End Dialog
Type $Username
Type $Password
Click -X 12 -Y 24

Use with

Web Wizard

Type

Action

Arguments

#ElementID

User assigned ID number

Example

This example uses the ClickElement command to click the item defined in MatchElement command.

Site "Citrix Receiver" -initial
MatchElement #4 -selector "#loginBtn"
EndSite
ClickElement #4
Endscript

Use with

Advanced Web application definitions created using the Web Wizard.

Type

Action

Usage for the WinSSO, JavaSSO and .NetSSO workers

ClickInput #ElementID

Description

Use this command to simulate pressing the Enter key.

Example

This example uses the ClickInput command that simulates pressing the Sign In button after the username and password fields are filled for the www.google.com website.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid "Google Log On" -initial
MatchForm #1 -name "log on"
MatchDomain "www.google.com"
MatchField #1:1 -name "Email" -type "text"
MatchField #1:2 -name "Passwd" -type "password"
MatchField #1:3 -name "Cookie" -type "check"
EndSite
SetPrompt "Enter your user credentials"
TextInput #1:1 -value "$Username"
TextInput #1:2 -value "$Password"
FocusInput#1:2 -focus "true"
BooleanInput #1:3 -check "false"
ClickInput #1:4
Endscript

Use with

Startup, Terminal Launcher, Web, or Windows

Type

Variable manipulator

Arguments

<String Time>

The output variable.

Example

Windows application definition

This example converts the time to a readable format and displays it in a dialog box.

# Logon Dialog Box
Dialog
Class #32770
Title "Log on"
End Dialog
ConvertTime ?CurrTime(system) ?Time
MessageBox ?Time

Use with

Startup, Windows, Java

Type

Dialog specifier

Arguments

<#Ctrl-ID>

The ID number of the control to check.

[<RegEx>]

The regular expression.

Syntax examples

Ctrl #1
Ctrl #1 "OK"

Use with

All

Type

Action

Arguments

<Data>

The text displayed to the user.

Data can be several strings, variables, or a combination of both..

Syntax examples

DebugPrint "Caught the login dialog"
DebugPrint "Setting platform to " ?Platform

Use with

All

Type

Variable manipulator

Arguments

<Variable>

The name of the variable to decrease in value.

Syntax examples

Decrement ?RunCount

Use with

All

Type

Action

Arguments

<Time Period>

A period of time, expressed in milliseconds (1/1000 of a second), during which application definition execution is paused.

Example

Windows application definition

This example detects the login box, then the application definition waits half a second before acting upon it to make sure that the box is complete.

# Logon Dialog Box
Dialog   
Class #32770   
Title "Log on"
EndDialog

Delay 500
Type $Username #1001
Type $Password #1002
Click #1

Use with

Java, Windows

Type

Dialog specifier

Arguments

None

Example

Windows application definition

This example tests the dialog box in order to determine its identity. If it is determined to be the login box, the application definition will parse the Type and Click commands to complete the login process.

# Logon Dialog Box
Dialog 
Ctrl #1 "OK"    
Title "Log on"   
Parent      
Title "Application 1"   
EndParent
EndDialog

Type $Username #1001
Type $Password #1002

Click #1

Use with

All

Type

Action

Arguments

[<User Prompt>]

Optional, customized text displayed in the Enter SecureLogin Variables dialog box. This message can be defined in a runtime variable (see example 2).

[<Variables>]

The name of the variables for which you want the user prompted. If not specified, SecureLogin will prompt for all variables that are used by the application definition.

Syntax examples

DisplayVariables
DisplayVariables "Please enter your details"
DisplayVariables "Please enter a new password" $Password
DisplayVariables "Please enter your username and password" $Username $Password
DisplayVariables "" $Username $Password

Example 2

Windows application definition

This examples passes the message in as a variable.

Dialog
Class "Notepad"
Title "Untitled - Notepad"
EndDialog
Set ?Vars "\$Username"
Set ?Msg "This is a DisplayVariables message"
DisplayVariables ?Vars
DisplayVariables ?Msg $Password
DisplayVariables "testing" ?Vars
DisplayVariables "testing" $Password $Username

Use with

Startup, Terminal Launcher, Web, or Windows

Type

Variable manipulator

Arguments

<Variable1>

The dividend, the first argument, the number that is divided by the second argument. Also this argument contains the result if the optional [?Result] argument is not passed in. If used without the [?Result] argument, <Variable1> must be a SecureLogin variable, either?Variable1 or $Variable1. Otherwise <Variable1> can be any numeric value.

<Variable2>

The divisor, the second argument, the number by which the first argument is divided. <Variable2> can be a SecureLogin variable or a numeric value.

[?Result]Optional, the quotient, the result of the equation.

Syntax examples

Divide "1" "2" ?Result
Divide ?LoginAttempts ?LoginFailures
Divide ?LoginAttempts ?LoginFailures ?Result
Divide ?LoginAttempts "3"
Divide ?LoginAttempts "3" ?Result

Use with

Advanced Web application definition

Type

Action

Arguments

<Variable>

The string variable to receive the page information.

Example

DumpPage ?dump
MessageBox ?dump 

Use with

Startup, Terminal Launcher, Web, or Windows

Type

Action

Arguments

None

Example

Windows application definition

This example detects the login box, then SecureLogin enters the user name and password, and the user clicks OK. If the Incorrect Password message is detected, SecureLogin displays a message that the password was incorrect, and terminates the application definition.

Dialog   
Title "Logon Failure"   
Ctrl #1
EndDialog

ReadText #65535 ?ErrorMsg
If "Incorrect Password" -In ?ErrorMsg MessageBox "You have entered an incorrect password"   
EndScript
EndIf

Use with

Windows

Type

Dialog specifier

Arguments

<Event Specifier>

The application event to monitor. This corresponds to a Windows event, which usually begins with WM_.

For example, WM_COPYDATA, WM_GETOBJECT, WM_GETTEXT

For information about Windows events, see Microsoft Developer network website.

Microsoft's Spy++, or similar Windows message spy tools, are also useful for trapping event names in specific windows. information about Spy ++ is also available on the MSDN website.

Syntax examples

Dialog    
Class "someclass"    
Event WM_ACTIVATE
EndDialog
MessageBox "Caught the WM_ACTIVATE message"

Use with

Startup, Terminal Launcher, Web or Windows and advanced application definitions created using the Web Wizard, WinSSO, JavaSSO and .NetSSO workers.

Type

Action

Arguments

#FormID:FieldID

The ID that was given to the matched field in the Site block using MatchField command. The FormID and FieldID must be unsigned integers.

Example

In this example the value of field #1:2 is being checked by the application definition.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid "Google Logon" -initial
MatchDoimain "www.google.com"
MatchField #1:1 -name "Email" -type "text"
MatchField #1:2 -name "Passwd" -type "password"
MatchField #1:3 -name "Cookie" -type "check"
EndSite
SetPrompt "Enter your user credentials"
FocusInput #1:1
TextInput #1:1 -value "$Username"
FocusInput #1:2
TextInput #1:2 -value "$Password"
FocusInput #1:3
BooleanInput #1:3 -check "false"
Endscript

Use with

Advanced Web, Windows

Type

Action

Arguments

<Item Number>

The ID of the check box.

<Variable>

The target variable for the status of the specified check box. Value returned is Checked or Unchecked. Partially selected tristate check boxes will be returned as Unchecked. The variable can be a question mark (?) or a dollar sign ($) variable.

Example

GetCheckBoxState #25 ?state1
GetCheckBoxState #26 ?state2
MessageBox ?state1
MessageBox ?state2

Use with

Startup, Windows

Type

Action

Arguments

<Variable>

This variable defines where to store the captured command line.

Example

Windows application definition

This example reads the command line of the application, and then tests the line to see if it is Notepad.exe. If it is, Notepad is closed. If it is not, the application definition ends.

GetCommandLine ?Text
If ?Text Eq "\"C:\Windows\System32\notepad.exe\""
   KillApp Notepad.exe
EndIf

Use with

All

Type

Action

Arguments

<EnvVar>

This is the environment variable name you wish to retrieve.

<Variable>

This variable defines where to store the retrieved environment variable data.

Example

Windows application definition

GetEnv "SESSIONNAME" ?SessionName
If ?SessionName eq "console"
MessageBox "Running from Citrix Server Console"
EndIf

Use with

Windows

Type

Action

Arguments

<Variable>

This variable defines where to store the captured handle.

Example 1

Windows application definition

GetHandle ?winHandle
MessageBox ?winHandle

Use with

Windows, Web, Terminal Emulator, Java

Type

Action

Arguments

<Ini File>

This is the file name from which you wish to read the section or key.

<Section>

Name of the section that contains the key name.

<Key>

Name of the key to read.

<Variable>

This variable defines where to store the retrieved data from the ini file.

Example

Windows application definition

GetIni "C:\Program Files\Lotus\Notes\Notes.ini" "Notes" "KeyFileName" ?NotesDefaultIDFileSetPlat

Use with

Windows

Type

Action

Arguments

<Variable>

Variable to store the returned MD5 hash value.

Example

In a Windows application definition, the MD5 hash value is stored in the variable that was passed as the argument to the command. The variable can either be a temporary or stored variable type.

GetMD5 ?tmp

or

GetMD5 $hash_value

The MD5 hash value would normally be obtained with the Window Finder tool on a window from the application. This MD5 value will then be put into a script and compared against the results of the GetMD5 command. If the MD5 hash values do not match, the executable file may have been altered.

Use with

All

Type

Action

Arguments

<RegEntry>

This is the registry entry to read.

<Variable>

This variable defines where to store the retrieved environment variable data.

<platform>

This optional variable reads the worker registries. The following are the platform inputs:

Example

Windows application definition

GetReg "HKLM\Software\ABCCorp\ProductID" ?ProductID
If ?ProductID noteq "xxxxxxxxxx"
   EndScript
EndIf

Use with

All

Type

Variable manipulators

Arguments

<?StatusVariable>

The target variable to which the value of the primary status is copied.

The value returned is either online or offline.

Example

GetDirectoryStatus ?status
If ?status eq "online"
#online instructions
EndIf
If ?status eq "offline"
#offline instructions
EndIf

Use with

Terminal Emulator

Type

Action

Arguments

<Variable>

The target variable that the session name is copied into.

Example

Terminal Emulator application definition

GetSessionName ?Session_name

Use with

Web, Terminal Launcher

Type

Action

Arguments

<Variable>

This variable defines where to store the captured text.

Example

Web application definition

This example copies the text content of the web page to the ?Text variable. SecureLogin tests for the presence of the word ‘Logon’. If Logon exists, SecureLogin enters the credentials and submits them automatically.

GetText ?Text
If "Log on" -In ?Text   
Type $Username
Type $Password Password
EndIf

Use with

Web

Type

Action

Arguments

<Variable>

This variable defines where to store the captured URL.

Example

Web application definition

This example copies the URL of the website to the ?URL variable and tests the URL to see if it matches text being searched for. If it does, SecureLogin pops up a message box and redirects the user to the intranet.

GetURL ?URL
If "Log off" -In ?URL
MessageBox "You have chosen to log off the application. You will now be redirected to the intranet home page."
GoToURL "http://Intranet"
EndIf

Use with

Web

Type

Action

Arguments

<URL>

The URL to which the browser will navigate.

<-frame>

Opens the URL in the frame which started the application definition.

Example

Web application definition

This example detects an incorrect password message, displays a message box informing the user, and then browses to the NetIQ website.

If -Text "Incorrect Password"   
  MessageBox "You have entered an incorrect password"   
  GoToURL "http://www.NetIQ.com"
EndIf

Use with

Web

Type

Action

Example

Web application definition

If –Text "Logon"
  Highlight #1
  Type $Username #1
  Highlight #2
  Type $Password #2
  Type "\N"
EndIf

Use with

Startup, Terminal Launcher, Web, or Windows

Type

Flow control

Usage 2

If <Value1> <Eq|NotEQ > <Value2> [-I|-S]
#Do This
[Else] 
#Do This
EndIf

Usage 4

If -Text [-Frame] <Text> 
#Do This
[Else]
#Do This
EndIf

Arguments

<Value1>

The left side of the expression for evaluation.

<Value2>

The right side of the expression for evaluation.

<Text>

The text for which you are searching.

Syntax examples

If $Number NotEQ "1"
MessageBox "NotEQ 1"
Else
MessageBox "Eq 1"
EndScript
EndIf

If ?Value1 Gt ?Value2
If -Text "Log on"
If -Exists $RunBefore
If "Log on" -In ?Text

Example 2

Windows application definition

Each time the application definition is run, a variable is incremented. This example counts the number of times the dialog box is displayed. If it is displayed more than three times, the application is closed. If the log on is successful, the count is reset.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #1001 ?Username

If –Exists $Username
Else
   Set $Username ?Username
EndIf
Increment ?RunCount
If ?RunCount Gt "3"
MessageBox "Log on has been attempted too many times.  The application will be closed."
KillApp "app.exe"

Else

   Type $Username #1001

   Type $Password #1002

   Click #1

EndIf

Example 3

Web application definition

This example copies the text content of the Web page to ?WebText. The variable is then tested to see if ‘Log on’ is present. If it is, SecureLogin performs the login process. If it is not present, the application definition is terminated.

GetText ?WebText
If "Log on" –In ?WebText
   Type $Username
   Type $Password Password
Else
   EndScript
EndIf

Use with

All

Type

Flow control

Arguments

<Platform-Name>

The name of the application definition to include.

Example

Windows application definition

This example detects the login dialog, the Notepad.exe application definition is executed, and then the user's credentials are entered.

# Logon Dialog Box
Dialog
Class #32770
Title "Log on"
EndDialog

Include "Notepad.exe"
Type $Username #1001
Type $Password #1002
Click #1

Use with

All

Type

Variable manipulator

Arguments

<Variable>

The name of the variable to increase in value.

Syntax examples

Increment ?RunCount

Use with

All

Type

Action

Arguments

<Process-Name>

The name of the process to terminate.

-title “Application title”

The title of the process to terminate.

Example 1

Windows application definition

Each time the application definition is run, a variable is incremented. This example counts the number of times the dialog box is displayed. If the dialog box is displayed more than three times, the application is closed. If the log on is successful, the count is reset.

# Logon Dialog Box
Dialog
   Title "Log on"
   Class #32770
EndDialog

Increment ?RunCount

If ?RunCount Gt "3"
   MessageBox "Log on has been attempted too many times.  The  application will be closed."
   KillApp "app.exe"

Example 2

Windows application definition

Same application definition as used in Example 1, however, the KillApp process is specified by title.

Dialog
   Title "Login Simple"
   Class #32770
EndDialog

Increment ?RunCount

If ?RunCount Gt "3"
   MessageBox "Log on has been attempted too many times.  The application will be closed."
   KillApp -title "Login Simple"
Else
   Type $Username #1001
   Type $Password #1002
   Click #1
EndIf

# Logon Successful Message
Dialog
   Title "Login - Simple Successful"
   Ctrl #1
EndDialog

Set ?RunCount "0"

Use with

All

Type

Variable manipulator

Arguments

<?Variable>

The runtime variable to declare as local.

Example

Windows application definition

This example declares a variable as local, and then uses it to count the number of times a dialog box is displayed. If the dialog box is displayed too many times, SecureLogin will alert the user, then close the application.

# Invalid Logon Message
Dialog   
  Class #32770   
  Title "Logon Failure"
EndDialog

Local ?RunCount
Increment ?RunCount
If ?RunCount Gt "5"   
  MessageBox "Closing application"   
  KillApp "PasswordText.exe"
EndIf
Type $Username
Type $Password

Use with

Advanced application definitions created using the Web Wizard.

Type

Action

Arguments

Domain

The domain name or address to be matched.

Example

In this example the site www.google.com is being matched by the application definition.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site "Login" -userid "Google Log On" -initial
  MatchDomain "www.google.com"
  MatchField #1:1 -name "Email" -type "text"
  MatchField #1:2 -name "Passwd" -type "password"
  MatchField #1:3 -name "Cookie" -type "check"
EndSite

SetPrompt "Enter your user credentials"
TextInput #1:1 -value "$Username"
TextInput #1:2 -value "$Password"
FocusInput#1:2 -focus "true"
BooleanInput #1:3 -check "false"
PressInput
Endscript

Use with

WinSSO, WebSSO, JavaSSO, and .NetSSO workers.

SecureLogin version for WinSSO, JavaSSO and .NetSSO workers

8.7 or later

Usage

MatchElement #<ElementID> <Selector>

Description

Use MatchElement to match the dynamic controls in a window.

ClickElement is the only command that interacts with MatchElement. For more information, see Section 6.2.14, ClickElement.

Example for WebSSO

Site "Microsoft Documentation"
MatchElement #1 -selector "#directory-page-search-form-autocomplete-input"
EndSite
ClickElement #1
Endscript

In this example, MatchElement matches the search bar in the webpage.

Site "Citrix Receiver" -initial
MatchElement #4 -selector "#loginBtn"
EndSite
ClickElement #4
Endscript

In this example, MatchElement matches the login button.

Use with

Advanced application definitions created using the Web Wizard.

Type

Action

Arguments

#FormID:FieldID

The ID to be given to the matched option within the field, building from the #FormID of the associated form. The FormID and FieldID must be unsigned integers. The combined #FormID:FieldID must be unique within the site block.

-optional

Specifies that matching this field is not required to successfully match the parent form.

-name "name"

Match against the field name.

-type "type"

Match against the field type. Type can be one of the following:

-value "value"

Match against the field value.

-defaultValue "defaultValue"

Match against the field’s default value.

-id “ID”

Match against the field ID.

Example 1

This example would locate the Web page fields Email, Password and Cookie within the website www.google.com.com matched by the application definition.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid "Google Log On" -initial
  MatchForm #1 -name "log on"
  MatchDomain "www.google.com"
  MatchField #1:1 -name "Email" -type "text"
  MatchField #1:2 -name "Passwd" -type "password"
  MatchField #1:3 -name "Cookie" -type "check"
  MatchField #1:4 -name "SAVEOPTION" -type "checkbox" -value "YES"
  MatchField #1:5 -name "Submit2" -type "submit"
EndSite

SetPrompt "Enter your user credentials"
TextInput #1:1 -value "$Username"
TextInput #1:2 -value "$Password"
FocusInput#1:2 -focus "true"
BooleanInput #1:3 -check "false"
BooleanInput #1:4 -check "false"
PressInput
Endscript

Use with

Advanced application definitions created using the Web Wizard.

Type

Action

Arguments

Example 1

Use with

Advanced Web application definitions created using the Web Wizard, WinSSO, JavaSSO and .NetSSO workers.

Type

Action

Usage for WinSSO, JavaSSO and .NetSSO workers

MatchOption #ElementID [-index “index”] [-text "text"]

Arguments for WinSSO, JavaSSO and .NetSSO workers

#ElementID

The ID to be given to the matched option within the field, building from the #ElementD of the associated selection field. The element ID must be unique within the site block.

-text "text"

Specifies the text string for this particular option.

-index "index"

Specifies the order for this particular option.

Example for Web

In this example the form named ‘log on’ within the secure website www.lotto.com is being matched by the application definition.

# === Logon Application Definition #4 ==
# === Lotto User Initial Logon ====
#========================================
Site Login -userid "Member Log In" -initial
  MatchForm #1 -name "log in"
  MatchDomain "https://site10.Lotto.com"
  MatchField #1:1 -name "Member ID" -type "text"
  MatchField #1:2 -name "Passwd" -type "password"
  MatchOption #1:3 -text "Secure" -value "Secure"
EndSite

SetPrompt "Enter your user credentials"
TextInput #1:1 -value "$Username"
TextInput #1:2 -value "$Password"
FocusInput #1:3
BooleanInput #1:3 -check "true"
PressInput
Endscript

Use with

Advanced Web application definitions created using the Web Wizard.

Type

Action

Arguments

-regex

Used with MatchReferer to use the referer value as regular expression rather than exact match.

For example, if referer is any page with prefix as "Page" and suffix as ".htm", then pass the argument as -regex "Page\w+\.htm"

"Referer"

The site referer which is to be matched. If PageA.htm includes a link to PageB.htm, then the referer is "PageA.htm".

Example

In this example, the referring HTML page www.lotto.com/index.html is being matched by the application definition.

# === Logon Application Definition #5 ==
# === Lotto User Initial Logon ====
#========================================
Site "Login" -userid "Member Log On" -initial
   MatchForm #1 -name "log on"
   MatchReferer "www.lotto.com/index.html"
   MatchDomain "https://site10.lotto.com"
   MatchField #1:1 -name "Member ID" -type "text"
   MatchField #1:2 -name "Passwd" -type "password"
   MatchOption #1:3 -name "Secure" -type "text"
EndSite

SetPrompt "Enter your user credentials"
TextInput #1:1 -value "$Username"
TextInput #1:2 -value "$Password"
FocusInput #1:2 -focus "true"
BooleanInput #1:3 -check "true"
PressInput
Endscript

In this example, the referring HTML page is being matched by the application definition.

# === Logon Application Definition #5 ==
# === Lotto User Initial Logon ====
#========================================
Site "Login" -userid "Member Log On" -initial
   MatchForm #1 -name "log on"
   MatchReferer -regex "\w{0,3}.*(lotto.)\w+"
   MatchDomain "https://site10.lotto.com"
   MatchField #1:1 -name "Member ID" -type "text"
   MatchField #1:2 -name "Passwd" -type "password"
   MatchOption #1:3 -name "Secure" -type "text"
EndSite

SetPrompt "Enter your user credentials"
TextInput #1:1 -value "$Username"
TextInput #1:2 -value "$Password"
FocusInput #1:2 -focus "true"
BooleanInput #1:3 -check "true"
PressInput
Endscript

Use with

All

Type

Action

Arguments

<RegEx>

The regular expression

<Input-String>

The string to match against.

Example

This example matches against any Web page on the www.google.com domain that has a text box, a password box and text somewhere on the page that matches against the “Welcome \w+ to Gmail” regular expression (“Welcome Nick to Gmail” for example).

Site "Gmail: Email from Google"
  MatchForm #1
  MatchDomain "www.google.com"
  MatchField #1:10 -type "text"
  MatchField #1:11 -type "password"
  GetText ?PageText
  MatchRegex "Welcome \w+ to Gmail" ?PageText
EndSite
MessageBox "Matched"

Use with

Advanced Web application definitions created using the Web Wizard.

Type

Action

Arguments

-regex

Indicates that the Title argument is a regular expression.

"Title"

The site title which is to be matched.

For more information regarding regular expressions see the Boost C++ Libraries website

Example

In this example the HTML page with the title ‘The New York Times > Log In’ within the website www.nytimes.com is matched by the application definition.

# =============================================
# Login Script #1 - The New York Times > Log In
# =============================================
# === Initial Login ===
Site "Login" -userid "nytimes.com #1" -initial
   MatchURL "http://www.nytimes.com/auth/login"
   MatchDomain "www.nytimes.com"
   MatchTitle "The New York Times > Log In"
   MatchForm #1 -name "login"
   MatchField #1:1 -name "USERID" -type "text"
   MatchField #1:2 -name "PASSWORD" -type "password"
   MatchField #1:3 -name "SAVEOPTION" -type "checkbox" -value "YES"
   MatchField #1:4 -name "Submit2" -type "submit"
EndSite

If the title needing to be matched is "The New York Times > Log In", then you could use -regex and match against only a portion of the title.

MatchTitle -regex "Times > Log In"

Use with

Advanced Web application definitions created using the Web Wizard.

Type

Action

Arguments

-regex

You may also use regular expressions to match part of a URL, such as the domain only.

"URL"

The site URL which is to be matched. This need not be the URL listed in the navigation field of the Web browser as the given page may not have been loaded from there.

For more information regarding regular expressions see the Boost C++ Libraries website.

Example

In this example the URL “https://www.nytimes.com/auth/login” is matched.

# === Initial Login ===
Site "Login" -userid "nytimes.com #1" -initial
   MatchURL "https://www.nytimes.com/auth/login"
   MatchDomain "www.nytimes.com"
   MatchTitle "The New York Times > Log In"
   MatchForm #1 -name "login"
   MatchField #1:1 -name "USERID" -type "text"
   MatchField #1:2 -name "PASSWORD" -type "password"
   MatchField #1:3 -name "SAVEOPTION" -type "checkbox" -value "YES"
   MatchField #1:4 -name "Submit2" -type "submit"
EndSite

If the URL to match is “http://www.nytimes.com/auth/login?URI=http://”, then you can match a portion of the URL with the -regex parameter.

MatchURL -regex "nytimes.com"

Use with

Startup, Terminal Emulator, Web, or Windows

Type

Action

Arguments

<-YesNo>

The -YesNo flag allows the user to select Yes or No within the message box, rather than being limited to an OK button only.

<-YesNoCancel>

The -YesNoCancel flag allows the user to select Yes, No, or Cancel when a message box is displayed.

<?Variable>

This runtime variable is required with the -YesNo / -YesNoCancel flag to store the result of the user action.

<-Background>

When specified, this parameter allows the user to open an application and work in that application, without having to respond to the MessageBox. If this parameter is not used, the MessageBox remains the active window. In Web applications, you must respond to the MessageBox before you can continue with any other work.

<-DefaultNo>

This optional parameter is used only with the -YesNoCancel flags. When the ‑DefaultNo parameter is set, the No button has the default focus rather than the Yes button.

<Data>

The text displayed to the user. <Data> can be several strings, variables, or a combination of both.

Syntax examples

MessageBox "Application definition completed successfully"

MessageBox "Do you wish to continue?"  -YesNo ?Result

MessageBox "Do you wish to continue?" -YesNoCancel ?Result ‑Background -DefaultNo

Example 2

Terminal Emulator test application definition

Use message boxes when troubleshooting application definitions. This example displays a message box before each step in the application definition to allow the writer to see where the application definition execution is failing.

MessageBox "Beginning wait for logon prompt"
WaitForText "ogin:"
MessageBox "Logon detected, now entering user name"
Type $Username
MessageBox "User name entered, now simulating Enter"
Type @E
MessageBox "Enter has been simulated, now waiting for password"
WaitForText "assword:"
MessageBox "Password detected, now entering password"
Type $Password
MessageBox "Password entered, now simulating Enter"
Type @E
MessageBox "Sequence completed, the user should now be logged on"

Use with

All

Type

Variable manipulator

Arguments

<Variable1>

The first argument is the number multiplied by the second argument.

<Variable2>

The second argument is the number by which the first number is multiplied.

[?Result]

Optional, the result of the equation.

Syntax examples

Multiply "1" "2" ?Result

Multiply ?LoginAttempts ?LoginFailures

Multiply ?LoginAttempts ?LoginFailures ?Result

Multiply ?LoginAttempts "3"

Multiply ?LoginAttempts "3" ?Result

Use with

All

Type

Flow control

Arguments

<Exception Name>

The name of the exception on which you wish to act. The following exceptions are supported:

<SubRoutine>

The name of the subroutine you want to run when the exception condition is true.

Syntax examples

OnException ChangePasswordCancelled Call Display Error
ClearException ChangePasswordCancelled

Example 2

Windows application definition

This example prompts the user to change their password. The user is restricted from clicking cancel and is forced to enter a new password.

# Change Password Dialog Box
Dialog
   Class #32770
   Title "Change Password"
EndDialog

Type $Username #1005
Type $Password #1006
OnException ChangePasswordCancelled Call ForceChangePwd
ChangePassword $Password "Please enter a new password for the Human Resources application. IT x4532"
Type $Password #1007
Type $Password #1008
ClearException ChangePasswordCancelled

Sub ForceChangePwd
   OnException ChangePasswordCancelled Call ForceChangePwd
   ChangePassword $Password "You must enter a new password and cannot Cancel. IT x4532"
   ClearException ChangePasswordCancelled
EndSub

Example 4

Windows application definition

This example demonstrates the OnException usage of GenerateOTPCancelled and GenerateOTPFailed.

#
# Login - Simple
#
Dialog
   Title "Login - Simple"
   Class "#32770"
   Ctrl #1001
   Ctrl #1002
   Ctrl #1 "&Login"
   Ctrl #2 "Cancel"
   Ctrl #1027 "Username:"
   Ctrl #1028 "Password:"
   Ctrl #1009
EndDialog
   OnException GenerateOTPCancelled Call CancelSimpleLoginDialogCancelled
   OnException GenerateOTPFailed Call CancelSimpleLoginDialogFailed
   GenerateOTP -mode "AISC-SKI" ?OtpResult
   Type $Username #1001
   Type ?OtpResult #1002
   Click #1
#
# Cancel the Simple Login Window - GenerateOTP cancelled
#
Sub CancelSimpleLoginDialogCancelled
   Click #2
   EndScript
EndSub
#
# Cancel the Simple Login Window - GenerateOTP failed
#
Sub CancelSimpleLoginDialogFailed
   Click #2
   MessageBox "Your generation of your password failed.  Login cancelled"
   EndScript
EndSub

Use with

Windows

Type

Dialog specifier

Arguments

None

Example 1

Windows application definition

This example specifies the dialog box that is used for log on. In this case, the parent of the login box has a class of "Centura:MDIFrame".

# Logon Dialog Box
Dialog 
   Class "Centura:Dialog"
   Ctrl #4098   
   Ctrl #4100   
   Title "Log on"   
   Parent      
      Class "Centura:MDIFrame"   
   EndParent
EndDialog

Type $Username #4098
Type $Password #4100
Click #4101

Use with

All

Type

Action

Arguments

<Display-Text>

The text displayed in the pick list for the specified option.

<Return-Value>

The value returned from the pick list. If not specified, the return value is the display text.

Java or Windows application definition

In this example, the user has to pick which of three accounts to use. They pick which account they want to use, and SecureLogin switches to that set of credentials using the SetPlat command.

# Logon Dialog Box
Dialog 
   Class #32770
   Title "Log on"
EndDialog

PickListAdd "Account One" "One"
PickListAdd "Account Two" "Two"
PickListAdd "Account Three" "Three"
PickListDisplay ?Account "Please select the account you wish to use"-NoEdit
SetPlat ?Account
Type $Username #1001
Type $Password #1002
Click #1
## End Logon Dialog Box ##

Example 3

Java or Windows application definition

In this example, SecureLogin reads the possible values for the Other drop down box. It then prompts the user to select the desired item and types in the username, password, and selected item.

###Logon
PickListAdd #3
PickListDisplay ?Database "Select your database" -NoEdit
SetPlat ?Database
Type #1 $Username
Type #2 $Password
Select ?Database #3
###End logon##

Use with

All

Type

Action

Arguments

<?Variable>

The output variable for the selected option.

<Display-Text>

The description text for the pick list box.

-NoEdit

The -NoEdit flag disables the addition of extra variables by the user.

Syntax examples

PickListDisplay ?Choice "Please select the account you wish to use"
PickListDisplay ?Choice "Please select the account you wish to use" -NoEdit 

Use with

Password Policy application definitions

Type

Action

Arguments

[NUMERAL]

The character at <Position> must be a numeral.

[UPPERCASE]

The character at <Position> must be an uppercase character.

[LOWERCASE]

The character at <Position> must be a lowercase character.

[PUNCTUATION]

The character at <Position> must be a punctuation character.

<Position>

The character position in the password.

Example

The password is not valid unless the first, sixth, and seventh characters are uppercase.

POSITIONCHARACTER UPPERCASE 1,6,7

Use with

Advanced Web application definitions created using the Web Wizard.

Type

Action

Arguments

#FormID:FieldID

The ID that was given to the matched field in the Site block using MatchField command. The FormID and FieldID must be unsigned integers.

Example

This example the PressInput command within the application definition is the equivalent of clicking the Sign In button on the www.google.com website.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid "Google Log On" -initial
  MatchForm #1 -name "log on"
  MatchDomain "www.google.com"
  MatchField #1:1 -name "Email" -type "text"
  MatchField #1:2 -name "Passwd" -type "password"
  MatchField #1:3 -name "Cookie" -type "check"
  MatchField #1:4 -name "Submit" -type "submit"
EndSite

SetPrompt "Enter your user credentials"
TextInput #1:1 -value "$Username"
TextInput #1:2 -value "$Password"
FocusInput #1:3
BooleanInput #1:3 -check "false"
FocusInput #1:4
PressInput #1:4
Endscript

Use with

Web application, WinSSO, JavaSSO and .NetSSO workers.

Type

Action

Usage for the WinSSO, JavaSSO and .NetSSO workers

ReadInput #ElementID -value ?valTextReadInput #ElementID -checked ?isChecked

Description

In a web application, the ReadInput command reads the text from any given <#Ctrl-ID> (check box, radio button, submit button and text field). For this command to function correctly, the <#Ctrl-ID> must be valid.

Example 1

Web application

Site "test"
MatchForm #1 -name ""
MatchField #1:3 –type "text"
EndSite

ReadInput #1:3 -checked ?fieldValue

Use with

Terminal Emulator, Windows.

Type

Action

Arguments

<#Ctrl-ID>

The control ID number of the text to read.

[-order]

If the control ID's are not constant, utilize the -order argument to instruct SecureLogin to type into a control based on the creation order and not the tab order. For more information about the -order argument usage, see Example 4.

<#Order-ID>

For Windows application definitions, this parameter specifies which control based on the creation order in which to type the text.

<?Variable>

The variable that receives the text that is read.

<Character-Number>

The number of characters to read.

<Row-Number>

The horizontal position number of the first character to read (for example, row).

<Column-Number>

The vertical position number of the first character to read (for example, column).

Syntax examples

ReadText #301 ?Text
ReadText ?Text 10 4 6

Example 2

Windows script

ReadText #1004 ?result 

Example 4

Windows application definition

This example reads the text from a control ID and sets the database variable so the user is not prompted to set the variable.

# Logon Dialog Box
Dialog   
   Class #32770   
   Title "Log on"
EndDialog

ReadText #15 ?Database
If -Exists $Database
Else   
   Set $Database ?Database
EndIf
Type $Username #1001
Type $Password #1002
Type $Database #1003
Click #1

Example 6

Windows application definition

This example reads the text from a control defined by its creation order and sets the database variable so the user is not prompted to set the variable.

# Logon Dialog Box
Dialog   
   Class #32770   
   Title "Log on"
EndDialog

ReadText -order #5 ?Database
If -Exists $Database
Else   
   Set $Database ?Database
EndIf
Type $Username #1001
Type $Password #1002
Type $Database #1003
Click #1

Use with

All

Type

Action

Arguments

<RegEx>

The regular expression.

<Input-String>

The string that to split.

<Output-String1>

The first sub-expression.

<Output-String2>

The second sub-expression.

Example 1

Windows application definition

This example copies text from control ID 301 to the ?Text variable. The RegSplit command is then used to strip the user name details out of the text that was read. The platform is set to that user name, and the correct password is entered by SecureLogin.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #65535 ?Text
RegSplit "Please enter the password for (.*) account" ?Text ?UserSetPlat ?User
Type $Username #1001
Type $Password #1002
Click #1

Example 3

Open text example

Set ?InputString "This is a long string with a few components in it"
RegSplit "This(.*)a long(.*)with(.*)components(.*)" ?InputString ?First ?Second ?Third ?Fourth
Type "First value is " ?First
Type \n
Type "Second value is " ?Second
Type \n
Type "Third value is " ?Third
Type \n
Type "Fourth value is " ?Fourth
#?First = "is", ?Second = "string", ?Third = "a few", ?Fourth = "in it"

Use with

Startup, Terminal Emulator, Web, or Windows

Type

Action

Arguments

None

Example

Windows application definition

# ==== BeginSection: Application startup ====
Dialog 
   Class "#32770" 
   Title "Password Test Application"
EndDialog

ClearPlat
# ==== EndSection: Application startup ====

# ==== BeginSection: Log on ====
Dialog 
   Class "#32770" 
   Title "Log on"
   Ctrl #1001
EndDialog

ReLoadPlat
SetPrompt "Username =====>"
Type $Username #1001
SetPrompt "Password =====>"
Type $Password #1002
SetPrompt "Domain =====>"
Type $Domain #1003
Click #1
# ==== EndSection: Log on ====

## ==== BeginSection: Log on successful ====
Dialog 
   Class "#32770
   "Title "Log on successful"
EndDialog

ClearPlat
Click #2
# ==== EndSection: Log on successful ====

# ==== BeginSection: Log on failure ====
Dialog 
   Class "#32770" 
   Title "Log on failure"
EndDialog

Click #2
ReLoadPlatOnException ChangePasswordCancelled Call Change-Cancelled 
ChangePassword $password
ClearException ChangePasswordCancelled 
Type -raw \Alt F
Type -raw L
# ==== EndSection: Log on failure ====

# ==== BeginSection: Change credentials cancelled ====
Sub ChangeCancelled 
   ClearPlat 
   EndScript
EndSub
# ==== EndSection: Change credentials Cancelled ===

Use with

All

Type

Action

Arguments

[Loop#]

The number of times the repeat application definition block is repeated. If not specified, the repeat continues indefinitely unless broken by other commands.

Syntax examples

Repeat
Repeat 3

Use with

All

Type

Action

Arguments

<Variable-Name>

The name of the variable to restrict.

<Password-Policy>

The name of the policy to enforce on the variable.

Example 1

Windows application definition

This example uses the application definition to restrict the $Password variable to the Finance password policy. The user's password must match the policy when they first save their credentials. When the password requires changing, the application definition generates a new password randomly based on that policy (no user intervention is required).

# Set the password to use the Finance password policy
RestrictVariable $Password FinancePwdPolicy

#Logon Dialog Box
Dialog 
   Class #32770 
   Title "Log on"
EndDialog

Type $Username #1001
Type $Password #1002

#Change Password Dialog Box
Dialog
   Class #32770   
   Title "Change Password"
EndDialog

Type $Username #1015
Type $Password #1004
ChangePassword $Password Random
Type $Password #1005
Type $Password #1006
Click #1

Use with

Startup, Terminal Launcher, Web, or Windows

Type

Action

Arguments

<Command>

The full path of the program to execute.

<Arg1> <Arg2>

An optional list of arguments and switches for the command.

Example

Startup application definition

This example prompts the user to start the Finance System.

If they click:

MessageBox "Would you like to connect to the Finance System?" -YesNo ?Result
If ?Result Eq "Yes"   
   Run "C:\Program Files\HRS\Finance.exe"  "/DB:HRS" "/Debug" 
Else   
   MessageBox "You have chosen not to run the Finance System.  Please do so manually."   
   EndScript
EndIf

Use with

Startup, Terminal Launcher, Web, or Windows

Type

Action

Arguments

-show <state>

state is a variable or value that represents a window state.

-position <coord>

coord is a variable or value that represents screen position in pixels from the top left of the window.

-size <dimensions>

dimensions is a variable or value that represents width in pixels.

<Arg1>....<ArgN>

An optional list of arguments and switches for the command

-cmd <command>

Command is the full path of the program to execute. Note that the full path is only necessary if the application cannot be located in the systems path environment variable.

Example

For Example:

# Run cmd.exe maximized
RunEx -show maximize -cmd cmd.exe
# Run cmd.exe minimized
RunEx -show 6 -cmd cmd.exe
# Run cmd.exe hidden using a variable
Set ?show hide
RunEx -show ?show -cmd cmd.exe
# Run cmd.exe at position 50, 50 
RunEx -position 50,50 -cmd cmd.exe
RunEx -pos 50,50 -cmd cmd.exe
# Run cmd.exe at position 50, 50 using a variable
Set ?pos 50,50
RunEx -pos ?pos -cmd cmd.exe
# Run cmd.exe in a window sized to 800,900
RunEx -size 800,900 -cmd cmd.exe
# Run cmd.exe in a window sized to 400,500 using a variable
Set ?size 400,500
RunEx -size ?size -cmd cmd.exe

Use with

Java, Advanced Web, Windows

Type

Action

Arguments

<Text of Item to select>

The text item that you want SecureLogin to select in the list box.

<#Ctrl-ID>

When multiple list boxes are found, this specifies which list box to address.

Examples

This example picks an item from the session combo or list control:

Select ?session #1

This example selects a tab within another tab control. When one tab control is contained within another, the tab selection order is irrelevant.

Select "Quick Connect" #70
Select "Connection" #69

This example selects a cell from within a table

Select "[0,0]" #1
If –text "User" #1
   Select "[0,1]" #1
   Type $Username #1
Endif

Use with

Advanced Web application definitions

Type

Action

Arguments

<Item text of selection>

The text item that you want SecureLogin to select in the list box. it can be a variable or a string.

<#Ctrl-ID>

This argument is required and represents the control ID of the list box.

<-multiselect>

Used to select multiple list box entries by using a subsequent SelectListBoxItem command.

Example

If "ERROR: The credentials supplied were invalid. Please try again." -In ?Text
   SelectListBoxItem "Find Context" #1
   Type ?SysUser #1
   Type $Password #2
   MessageBox "If logon continues to fail, please logout of the computer and back in, retry, and report it to your SecureLogin administrator."
   EndScript
EndIf

Use with

Advanced Web application definitions, WinSSO, JavaSSO and .NetSSO workers.

Type

Action

Usage for the WinSSO, JavaSSO and .NetSSO workers

SelectOption #ElementID -clearSelectOption #ElementID:OptionID -select "true"

Description

Use the SelectOption command to select or deselect options within a list box or combo dialog box.

Use with

All

Type

Action

Arguments

<Windows Handle>

A valid windows handle. This should be a local variable with the handle initialised via a call to GetHandle. Alternatively, it is possible to broadcast the event by using the Windows constant HWND_BROADCAST.

<Event Specifier>

See Section 6.2.26, Event/Event Specifiers for the applicable conditions. In addition, a new custom SSO event can be used, SSO_NOTIFY.

Example 1

Send WM_SETFOCUS using a captured handle

Event WM_SETFOCUS
....
GetHandle ?handle
SendEvent ?handle WM_SETFOCUS

Example 3

SC_CLOSE 0xF060 closes the window

GetHandle ?handle
SendEvent ?handle WM_SYSCOMMAND SC_CLOSE

Use with

Terminal Emulator

Type

Action

Arguments

<Text>

The text typed into the emulator screen.

Example

Terminal Emulator application definition

The example sends the username and password to the terminal emulator.

#Send User Name
SendKey "DJones"
SendKey "\N"
#Send Password
SendKey "Hu7%f"
SendKey "\N"

Use with

All

Type

Action

Arguments

<Variable>

The variable to which the data is being assigned.

<Data>

The text or variable to read from and assign to the specified variable, for example:

Set ?Message "\?Username"

Example 1

Windows application definition

This example uses the application definition to set a ?RunCount variable to count the number of times the application is run.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

If ?RunCount Eq <NOTSET>   
   Set ?RunCount "1"
Else 
   Increment ?RunCount
EndIf

Type $Username #1001
Type $Password #1002
Click #1

Example 3

Windows application definition

This example uses the application definition to read the value of control ID 15 and sets the $Database variable so the user does not have to set the variable.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #15 ?Database
If -Exists $Database   
Else   
   Set $Database ?Database
EndIf

Use with

Advanced Web, Windows

Type

Action

Arguments

<Item Number>

The check box in reference to the number of check boxes found.

<Option>

Specifies the status of the check box as Checked or Unchecked.

Example

MessageBox "Scroll down to see the 'Search Language' section with the check boxes then click OK"setcheckbox #1 "checked"
setcheckbox #2 "checked"
setcheckbox #3 "checked"
setcheckbox #4 "checked"
setcheckbox #25 "checked"
setcheckbox #26 "checked"
setcheckbox #27 "checked"
MessageBox "Did it select the first four languages and Norwegian, Polish and Portuguese languages" -yesno ?advweb
if ?advweb eq yes
  Set ?cmd37 "SetCheckBox command worked" 
Else
  Set ?cmd37 "SetCheckBox failed"
Endif
SetCheckbox #1 "unchecked"
SetCheckbox #2 "unchecked"
SetCheckbox #3 "unchecked"
SetCheckbox #4 "unchecked"
SetCheckbox #26 "unchecked"
SetCheckbox #27 "unchecked"
MessageBox "Did it clear all languages except Norwegian" -yesno ? advweb2
If ?advweb2 eq yes 
   set ?cmd38 "SetCheckBox command worked"
Else      
   set ?cmd38 "SetCheckBox failed"
Endif

Use with

Terminal Emulator application definition (only works with HLLAPI and some DDE Tlaunch emulator definitions)

Type

Action

Usage 2

SetCursor <X Coordinate> <Y Coordinate>

Description

Use the SetCursor command to set the cursor to a specified <Screen-Position> or <X Coordinate> <Y Coordinate>.

The position is noted by a number greater than 0 (zero), for example, SetCursor 200. Terminal Launcher displays an error message if the screen position is invalid.

Example

Terminal Emulator application definition

This example sets the cursor to the correct position, and then you enter credentials.

SetCursor 200
Type $Username
Type @E
Type $Password
Type @E

Use with

Java and Windows

Type

Action

Description

Use the SetFocus command to set the keyboard focus to a specified control ID.

A valid control ID is required for the SetFocus command to function correctly.

Use with

All

Type

Action

Usage 2

SetPlat <RegEx> <Variable> <#Ctrl-ID>

Description

By default, variables are stored directly against the platform or application on which you have SecureLogin enabled. For example, if you enable Groupwise.exe, the Groupwise credentials are stored against the Groupwise.exe platform.

SetPlat sets the platform or application from which variables are read and saved if you have:

Other uses of SetPlat include:

For information regarding regular expressions see:

www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html

When the user has run the application definition, they will see the user name and password saved as www.serversystems.com. The text matched inside the brackets then becomes the symbol application. If a dialog <#Ctrl-ID> is not specified, the symbol application is unconditionally changed to the application specified in <RegEx>. An unconditional SetPlat command is only valid if specified before Dialog/EndDialog statements.

Use with

All

Type

Action

Arguments

<Prompt-Text>

The customized text prompt displayed in the Enter SecureLogin Variables dialog box.

Example 1

Windows application definition

This example replaces the default text prompt in the Enter SecureLogin Variables dialog box. It places the SetPrompt command after the last variable typed.

# Logon Dialog Box
Dialog
   Class #32770   
   Title "Log on"
EndDialog

Type $Username #1001
Type $Password #1002
SetPrompt "Please enter your user name and password for accessing the Human Resources system.  These credentials will be remembered by SecureLogin and you will be automatically logged on in future. IT Help Desk x4532"
Click #1

Use with

WinSSO

Type

Action

Usage 2

SetRestPlat -method <Application-Name> -url <Domain-Name>

Description

Use this command in PAM application SSO in order to get the application credentials from the PAM server.

Example 2

This following example sends the specified url instead of application ID to the PAM server.

SetRestPlat –method "PAM" -url "10.230.6.11"
TextInput #user $Username
TextInput #pwd $Password

Use with

Advanced Web/Web Wizard Script application definitions created using the Web Wizard.

Type

Action

Arguments

Site

The Site/EndSite commands are used to match a particular site given a set of filters. Site/EndSite usage is much the same as the Dialog/EndDialog commands found in the windows scripting commands.

Name

Name is a static string used to denote the site being matched. The Name cannot be a variable and the same value can be used by multiple Site commands to specify a match for the same site under differing conditions.

-userid "userid"

Specifies the default set of credentials to be used for this site block.

-initial

Specifies that this site block will only match the first time.

-subsequent

Specifies that this site block will only match after an initial match has already been made.

Description

Site/EndSite begins and ends a site definition, similar to the Dialog/EndDialog commands used in Windows application definition scripts. There can be multiple site definitions within a single advanced web application script to identify different sites within the same domain.

Site/EndSite blocks are used to define all the parameters SecureLogin would expect to find on a Web page to run the application definition.

'Match' commands can be used to filter a given site. If one of the contained match commands fails to match, then the site block fails to match as a whole.

Example 2

This simple example will match the website www.google.com, match the login form fields and logs on to the user’s account using the user’s e-mail address, password, and don't remember checkbox unchecked.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid "Google Log On" -initial
  MatchDomain "www.google.com"
  MatchField #1:1 -name "Email" -type "text"
  MatchField #1:2 -name "Passwd" -type "password"
  MatchField #1:3 -name "Cookie" -type "check"
EndSite

SetPrompt "Enter your user credentials"
TextInput #1:1 -value "$Username"
TextInput #1:2 -value "$Password"
FocusInput#1:2 -focus "true"
BooleanInput #1:3 -check "false"
PressInput
Endscript

Use With

Web

Type

Action

Description

Use the SiteDeparted variable in Web scripts to see if the current document is still active when used as part of an If statement.

Use with

All

Type

Action

Arguments

<Variable>

The variable to which you want a result saved.

<Input-String1>

First data string or variable.

<Input-String2>

Second data string or variable.

Example

Windows application definition

This example reads the user name from #1001 into ?Username and uses the StrCat command to append the ?Username value with the value of $Password. The resulting string is returned in the ?LoginID variable, which SecureLogin then uses to log on to the system.

# Logon Dialog Box
Dialog
   Class #32770 
   Title "Log on"
EndDialog

ReadText #1001 ?Username
StrCat ?LoginID $Username $Password
Type ?LoginID #1002
Click #1

Use with

All

Type

Variable manipulator

Arguments

<Destination>

The output variable that will contain the results of the string length computation.

<String>

The string whose length you want to measure.

Example

Windows application definition

This example reads the password from #301 and then uses StrLength to count the number of characters. If it is less that 4, an error message is displayed.

Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #301 ?Password
StrLength ?Length ?Password 
If ?Length Lt "4"   
   MessageBox "Password is too short"
EndIf

Use with

All

Type

Variable manipulator

Arguments

<Destination>

The output variable. Also the input variable if no source is specified.

[<Source>]

The input variable. If not specified, SecureLogin reads the destination variable, makes the necessary changes, and writes over the variable.

Example

Windows application definition

The example reads the user name from #1001 and copies it into ?Username. The StrLower command is then used to make sure the user name is all lower case.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #1001 ?Username
StrLower ?LowerCaseUsername ?Username 
Type ?LowerCaseUsername #1002
Click #1

Use with

All

Type

Variable manipulator

Arguments

<Destination>

The output variable. Also the input variable if no source is specified.

[<Source>]

The input variable. If not specified, SecureLogin reads the destination variable, makes the necessary changes, and writes over the variable.

Example

Windows application definition

The example reads the user name from #1001 and copies it into ?Username. The StrLower command is then used to make sure the user name is all lower case.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #1001 ?Username
StrLower ?LowerCaseUsername ?Username 
Type ?LowerCaseUsername #1002
Click #1

Use with

All

Type

Variable manipulator

Arguments

<Destination>

The output variable.

<Source>

The input variable.

search

It is the existing character or string in the <Source> variable that is to be replaced.

replace

It is the new character or string that replaces the existing character or string (search) in the <Source> variable.

Example

Dialog
Title "Untitled - Notepad"
EndDialog
Type $Username
StrReplace ?Us \ \\ $username
Type ?Us
StrReplace ?Us abc Test ?Us2
Type ?Us2
EndScript

If Username is abc\n\tdef then the <Us> variable will store abc\\n\\tdef and <Us2> will store Test\n\tdef.

Use with

All

Type

Variable manipulator

Arguments

<Destination>

The output variable. Also the input variable if no source is specified.

[<Source>]

The input variable. If not specified, SecureLogin reads the destination variable, makes the necessary changes, and writes over the variable.

Example

Windows application definition

This example reads the user name from #1001 and copies it into ?Username. The StrUpper command is then used to make sure the user name is all upper case.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #1001 ?Username
StrUpper ?UpperCaseUsername ?Username 
Type ?UpperCaseUsername #1002
Click #1

Use with

Startup, Terminal Emulator, Web, or Windows

Type

Flow control

Arguments

<Name>

Any name entered to identify the subroutine.

Example

Terminal Emulator application definition

This example checks the emulator screen for the text Log On or Wrong Password. If either is found, the appropriate subroutine is called and run. After the subroutine completes, the script will continue processing the remaining commands in the application definition script.

If -Text "Log On"   
   Call "Login"
EndIf
If -Text "Wrong Password"   
   Call "WrongPassword"
EndIf

Sub Login
   Type $Username
   Type @E
   Type $Password
   Type @E
EndSub

Sub WrongPassword   
   DisplayVariables "Enter correct password" $Password
   Call Login
EndSub

Use with

The valid Web related application definitions that really apply.

Type

Action

Arguments

None

Example

Web application definition

This example enters the user name and password and then executes a manual Submit.

Type $Username #1

Type $Password #2

Submit

Use with

Startup, Terminal Emulator, Advanced Web/Web Wizard Script, or Windows

Type

Action

Arguments

<var result>

The <var result> argument is the variable where the sub text is stored.

<var source>

The <var source> argument is the actual string.

<var start>

The <var start> argument is the index number of the sub text.

<var count>

The <var count> argument is the number of characters from the <var start> position.

Use with

Java, Startup, Terminal Emulator, Advanced Web/Web Wizard Script, or Windows

Type

Action

Arguments

<var result>

The <var result> argument is a variable in which the value of the varvar variable is stored.

<varvar>

The <varvar> argument contains a variable of which value changes according to the variable manipulators or other commands that are used in the script.

Example

This example evaluates the variable that is stored in <varvar> and places the value in <var result>. If the variable that is stored in <varvar> is a runtime variable named password, then the following is equivalent to Set ?result ?password.

SubstVar ?result ?varvar

Following example can help in accessing password history for first ten passwords:

Set ?Count 0
Repeat 10
 Strcat ?varvar  password ?Count
 SubstVar ?currPass ?varvar
# obtain the required details from each password
 Increment ?Count
EndRepeat

Use with

Startup, Terminal Emulator, Advanced Web/Web Wizard Script, or Windows

Type

Variable manipulator

Arguments

<Start-Value>

The <Start-Value> argument is the start number from which the second argument is subtracted. This argument contains the result if the optional [?Result] argument is not passed in. If used:

<Subtract-Value>

The <Subtract-Value> argument is the number subtracted from the first argument. <Subtract-Value> can be a SecureLogin variable or a numeric value.

[?Result]

The result of the equation. This argument is optional but, if used, set to <Start-Value> - <Subtract-Value>. The [?Result] must be a SecureLogin variable, for example, $Result or ?Result.

Syntax examples:

Subtract "1" "2" ?Result
Subtract ?LoginAttempts ?LoginFailures
Subtract ?LoginAttempts ?LoginFailures ?Result
Subtract ?LoginAttempts "3"
Subtract ?LoginAttempts "3" ?Result

Use with

Advanced Web application definitions

Type

Tag specifier

Arguments

<Form-Name>

The form name is an optional value given to a form by the creator of the website.

Example

This example finds the form that has an attribute of Name with a value of Log on.

Tag "Form"   
   Attribute "Name" "Log on"
EndTag

Use with

Advanced Web application definitions created using the Web Wizard Script, WinSSO, JavaSSO and .NetSSO workers.

Type

Action

Usage for the WinSSO, JavaSSO and .NetSSO workers

TextInput #ElementID “value”

Description

Use the TextInput command after a Site block to input text into a specified field.

You can enter text into fields of type password/text/textarea/file.

Use with

Java, Windows, .NET etc.

Type

Dialog specifier

Arguments

<Window-Title>

The text to test against the window title.

-regex

You may also use regular expressions to match part of a URL, such as the domain only.

For more information regarding regular expressions see:

www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html

Example 1

Windows application definition

This example tests the dialog box to see if it has the correct title. If the title is not correct, the application definition passes on to the next Dialog block.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Logon"
EndDialog

Type $Username #1001
Type $Password #1002
Click #1

Use with

Java, Terminal Emulator, Web Wizard Script/Advanced Web, or Windows

Type

Action

Windows usage

Type <Text> [<#Ctrl-ID>]

Type [-Raw] <Text>

Type [-order] <Text> [<#Order-ID>]

Type [-msg] <Text> [<#Ctrl-ID>]

Arguments

[-Raw]

By default, when typing into a terminal emulator or Windows application, SecureLogin verifies that the window exists before continuing. This verification process is disabled when the -Raw argument is provided. Furthermore, instead of setting the text in the field directly, the -Raw argument simulates actual keystrokes, causing SecureLogin to type into whichever window has focus.The ‑Raw argument can also be used in a Web application. The -Raw argument attempts to type the text into the window that owns the Web page (Internet Explorer or Firefox) and works the same as -Raw on Windows applications.

[-order]

If the control ID's are not constant, utilize the -order argument to instruct SecureLogin to type into a control based on the creation order and not the tab order. For more information about the -order argument usage, see Example 5.

[-msg]

The -msg argument can be used when a Type command is sending the data correctly, but the application is not successfully reading the data. The -msg argument will only work in Windows applications as the argument simulates the keys being pressed (that is, key down, character, key up). The -msg argument sends the data character by character versus sending the text string all at once. This -msg option is often useful for older Windows applications, particularly old versions of Lotus Notes.

<Text>

The text to type into this area. This text can be static text, such as ABC, or any SecureLogin variable, such as $Username.

[<#Ctrl-ID>]

For Windows application definitions, this optional argument specifies the control into which to type the text. Use the Window Finder to extract these control IDs. For more information, see Windows specific.

[<#Order-ID>]

For Windows application definitions, this parameter specifies which control based on the creation order in which to type the text.

Description

Use the Type command to enter data such as user names and passwords into applications. There are reserved character sequences that are used to type special characters, for example Tab and Enter. If it is not possible to determine control IDs in a Windows application, and the Type command is not working, use the SendKey command instead.

Example 2

Windows application definition

This example shows the use of the -Raw argument. This argument is not actually required for the application but is used as an example.

# Calculator Is Active
Dialog
   Class #SciCalc
   Title "Calculator"
EndDialog

Type -Raw "15"
Type -Raw "+"
Type -Raw "20"
Type -Raw "="

Example 4

Windows application definition

The following syntax examples compare and contrast the use of the various Type command arguments.

Type #1 "text"

Will type text into control with ID of 1

Type #1 "text" -order

Will type text into the first control drawn in the application dialog window.

Type #1 "text" -msg

Will type text character by character into the first control with an ID of 1.

Type #1 "text" -raw
Type #1 "text" -focus

Ignores the unused parameter #1

Example 6

Web application definition

This example shows the use of the HTML type password as an argument to find the appropriate Password field.

Type $Username
Type $Password Password

In the application definition above, the SecureLogin agent locates the first password field. The first Type command sends $Username to the field immediately before the password field. The second Type command sends $Password to the password field. The same application definition could be rewritten using absolute placement as shown below. In the following example, the Submit command is also used to automatically submit the page.

Type $Username #1
Type $Password #2
Submit

Use with

Windows

Type

Flow control

Arguments

<#Ctrl-ID>

The ID number of the control with the focus.

[<Repeat-Loops>]

The number of repeat-loops that will run.

Syntax examples

WaitForFocus #301
WaitForFocus #301 "2000"
WaitForFocus #301 "0"
WaitForFocus #301 "-1"

Example 2

This example has the WaitForFocus command suspend the running of the application definition until control ID #15 is reached and a message box with “love” should appear.

## BeginSection: "Logon Window"
Dialog
  Class "Notepad"
  Title "Untitled - Notepad"
EndDialog

Setprompt "Optional:"
# Here the correct ID with the loops set to 0
WaitForFocus #15 0
Set ?thu "love\me"
RegSplit "(.*)\\(.*)" ?thu ?Domain ?User
MessageBox ?Domain
## EndSection: "Logon Window"

Use with

Terminal Emulator

Type

Flow control

Arguments

<Text>

The text for which the application definition is waiting.

Example

Terminal Launcher application definition

This command instructs SecureLogin to wait for the text ogin: to appear on the emulator screen before entering the user name. It will then wait for password: to display before entering the password.

The WaitForText cuts off the first character because it finds both Password and password, and responds to all password entry points.

WaitForText "ogin:"
Type $Username
Type @E
WaitForText "assword:"
Type $Password
Type @E

Use with

Startup, Terminal Emulator, Web, or Windows

Type

Flow control

Usage 2

While <Value1> <Eq|NotEQ > <Value2> [-I|-S]
#Do This
Endwhile

Usage 4

While -Text [-Frame] <Text> 
#Do This
Endwhile

Arguments