Environment
NetIQ SecureLogin
NSL 8.8
Situation
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.
Resolution
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:
#id.class> child
For more information see “selectors” at https://api.jquery.com/category/selectors/
For example, the google.com 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.app.ng-scope > div > div:nth-child(2) > div > form > div > div.ng-isolate-scope > div > div > div > div > footer > span > div > div.mypage-tertiary-block > button"
Or
"form div.username button.mypage-tertiary"
The SecureLogin 8.8 Application Definition Guide includes a section on “MatchElement” in the Command Reference. See https://www.netiq.com/documentation/securelogin-88/application_definition_guide/data/bk0nzg3.html#t47zhw4rthur
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
EndDialog
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 webClickElement #username-- For non webTextInput #username $usernameClickInput #username
Example 2 (from the docs):
Dialog
Title "ACMsample"
MatchElement #password #1000
EndDialog
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):
Dialog
Title "ACMsample"
MatchElement #submit .Edit#101
EndDialog
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):
Dialog
Title "ACMsample"
MatchElement #buttonvalue Button[value=ok]
EndDialog
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 "https://login.mypage.com/idp/011781-HZNEP2-247/" -events mutate
MatchElement #101 -selector "button[ng-click*=troubleSigningIn]"
MatchElement #102 -selector "input[a-id=login-name-input]"
EndSite
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.