Using the “MatchElement” command with SecureLogin

  • 7025051
  • 16-Mar-2021
  • 31-Mar-2021


NetIQ SecureLogin
NSL 8.8


Using the match element command in a SecureLogin script.
How to use “MatchElement” when enabling a web page for SecureLogin SSO.
Using MatchElement to match dynamic controls in an HTML form or a Win 32 window.


Use the following syntax for MatchElement:
MatchElement #<elementID> <selector>

Where "Element ID" is an arbitrary number assigned by you to the matched element, and "Selector" is a combination of attributes that uniquely identifies an element of a form. The matching is based on this selector.

Use MatchElement to find at least one element with matching selector details such as type/id/class or other attributes like value/visible.  Failure to match an element causes the dialog or site block match to fail, and the next element on the page to be tried.  When a match is found, the label specified as the elementID is assigned to the attributes identified by the selector. 

Note:  Typically MatchElement is only used to identify an HTML form or a Win32 window.  For web pages, while you can match any element on a given page, the only interaction possible with MatchElement is ClickElement.  In otherwords, ClickElement is the only SecureLogin command that works with MatchElement in a web page.   All other interactions require MatchField to be used.  If you want to type/read/boolean values use MatchField instead of MatchElement

Additional Information

For Web pages, the selector is a CSS like/jQuery selector of the HTML Element.  This provides support for dynamic control.  For example: 

  > child

For more information see “selectors” at

For example, the  google search input field can be found with a selector of 
"body > div.L3eUgb > div.o3j99.ikrT4e.om7nvf > form > div:nth-child(2) > div.A8SBwf > div.RNNXgb > div > div.a4bIc > input"

Or shortened
"form  div.a4bIc > input"

For one customer’s username login page,  the "Trouble signing in?" element can be selected with 
"#ng-app > > div > div:nth-child(2) > div > form > div > > div > div > div > div > footer > span > div > div.mypage-tertiary-block > button"

"form div.username button.mypage-tertiary"

The SecureLogin 8.8 Application Definition Guide includes a section on “MatchElement” in the Command Reference.  See

The examples in the above doc all use "Dialog/ EndDialog" syntax, which is intended for windows applications.  Use "Site/ EndSite" syntax for matching web pages.  For websso the match elements should be within a site/endsite block.  Below are some examples and explanations.

Example 1 (from the docs):

Title "ACMsample"
MatchElement #username EditBox

In this example, MatchElement matches the type of the control.
This example assigns the label   #username   to the first EditBox element.
You can then refer to the first editbox element to perform some action then such as

-- For web
ClickElement #username

-- For non web
TextInput #username $username
ClickInput #username

Example 2 (from the docs):

Title "ACMsample"
MatchElement #password #1000
In this example, MatchElement matches the ID of the control.
This assigns the label #password to the first control with Win32 control id 1000.  

Example 3 (from the docs):

Title "ACMsample"
MatchElement #submit .Edit#101
In this example, MatchElement matches the class and ID of the control.
This assigns the label #submit to the first editbox with Win32 control id 101.  

Example 4(from the docs):

Title "ACMsample"
MatchElement #buttonvalue Button[value=ok]
In this example, MatchElement matches the value of the control.
This assigns the label #buttonvalue to the first element of type Button that also has a Value of "ok."

Example 5 (from a customer's environment):
Site "" -events mutate 
MatchElement #101 -selector "button[ng-click*=troubleSigningIn]"
MatchElement #102 -selector "input[a-id=login-name-input]"

ClickElement #101

In this example, the "trouble signing in" button from a customer's web page is assigned an element ID of 101, and the ClickElement command is used to bring up the  "trouble signing in" dialog when the page is accessed.