IBM Security Access Manager for Enterprise Single Sign-On, Version 8.2.1

Triggers

The table lists the predefined triggers in AccessStudio and explains the conceptual information for each trigger in detail with relevant examples.

Table 1. AccessStudio Triggers
Trigger Description
Window is activated Windows raises an activate event on a window with a title bar when it is activated by the user or a program, by using the mouse or the keyboard, or while coding.

This trigger is fired when the activation of the window occurs. The activation is characterized by the appearance of the window in the foreground with a highlighted title bar.

The parameter of this trigger is the signature of the window that is activated.

Example:

To trap activate on window with title, "Messenger! signin", 
<wnd_activate_trigger> 
<signature>/child::wnd[@title="Messenger! signin"]
</signature> 
</wnd_activate_trigger>
Note: The window activate trigger works only on a window with a title bar. It works only for windows within the same process the agent is residing. The agent loads into the intended process before using activate trigger on the window within that process. Unlike other triggers, this trigger would not fail even if the window is not present when the trap is being set.
Button is clicked Windows raises a button click event when a button is clicked on a window.

This trigger is fired when this clicking of button occurs. The parameters for this trigger are signatures of the window and the button.

Example:

To trap the click of a button with control ID "101" within a window with the signature "/child::wnd[@title="Messenger"]", use 
<wnd_command_bn_click_trigger> 
<signature>/child::wnd[@title="Messenger"]</signature> 
<control> 
<signature>/child::wnd[@title="Messenger"]/ child::wnd
[@ctrl_id="101"]</signature> 
</control> 
</wnd_command_bn_click_trigger>
Note: If the window with the specified signature is not found, no event trapping is set. To make sure that the window is available, set a trap for activate at the top-level parent window containing that window.
Web page completes loading A document complete event takes place when a web page is fully loaded in the web browser. The status bar of the browser indicates that a web page is downloaded and displayed.

This trigger is fired when loading is complete. This trigger is typically the first trigger in the begin state in an AccessProfile for a website.

The parameter for this trigger includes the signature of the completed web page.

When this trigger is run, other triggers that are associated with the specific web page (identified by using the signature) are run.

Tip: To match dynamic pages with a single URL, you can specify the signature to a unique element on a page.
HTML element is clicked A web browser raises a click event when an HTML element is clicked manually or automatically.

This trigger fires when the HTML element is clicked.

The parameter of this trigger is the signature of the HTML element which is being monitored for clicking.

Example:

To trap a click event on an image element which source is someimage.jpg, use: 
<web_click_item_trigger> 
<signature>/child::html/child::html/child::html[@tag_
name="img" and src="someimage.jpg"]</ signature> 
</web_click_item_trigger>
Note: If the HTML element to which the click event is to be trapped has a JavaScript for that event, it can mean either of the following events when trapping the event: after or before the JavaScript execution. Set the before_javascript attribute to 0 to trap after the script execution.
Window gets created Windows raises a create event when a window is created.

This trigger fires when this creation of a window occurs.

The parameter for this trigger is the signature of the window which is being created.

Example:

To trap the creation of a window that would match / child::wnd[@title="Messenger"], use 
<wnd_create_trigger> 
<signature>/child::wnd[@title="Messenger"]</signature> 
</wnd_create_trigger>
Note: Unlike other triggers, this trigger would not fail if the window is not present while the trap is being set.
Window gets destroyed Windows raises an event when a window is closed.

This trigger fires when the window closes.

The parameter of this trigger is the signature of the window to be closed.

Example:

To trap a destroy event on a window that says Messenger! Messenger with Voice, the signature would look like 
/ child::wnd[@title="Messenger! Messenger with Voice" 
and @class_name="MessengerBuddyMain"]
Tip: This trigger can be used to transit the state engine if a mouse event or a key press event cannot be captured in an application that has an owner-drawn window.
Window is hidden Windows raises the hide window event on a window before hiding it.

This trigger is fired when event is raised.

The parameter of this trigger is the signature of the window which is to be hidden.

Example:

To trap hide window event on a window with text "Sign in" 
<wnd_hide_window_trigger> 
<signature>/child::wnd[@title="Sign in"]</signature> 
</wnd_hide_window_trigger>
Note: If the window with a specified signature is not found, no event trapping would be set. To make sure that the window is available, set a trap for activate at the top-level parent window containing that window.
Window is found This trigger searches for and fires when it finds the window specified in the signature parameter by polling that window.

The other parameters to this trigger are the polling interval in seconds and the number of times the window is searched for, the polling count.

Example:

In some cases, the Window is found trigger is the only choice because the Window is activated trigger is unable to trap the activate event generated by Windows. In such cases, the Window is found trigger is a direct substitute for the Window is activated trigger.

Note: Avoid using this trigger unless it is necessary. In general, any polling mechanism introduces a performance overhead that might degrade the user experience.
Key is pressed down on a window Windows generates a key down event when a key or a combination of keys on the keyboard are pressed.

The parameters of this trigger are the signature of the window that must be monitored for keyboard input, the key combination that match, and an optional regular expression if a specified text output is to be matched.

Note: When you set the property Fire trigger on key to Any key, the Enter key does not cause the trigger to fire.

Example:

To capture the user name and password when logging in to Messenger! Messenger, specify the signature of the password field in the signature box and choose to fire the trigger on the Enter key.

For a terminal application, a sequence of keystrokes - such as a command like change password - can be captured using the Key is pressed down on a window trigger and matched against the regular expression specified in the regex parameter of the trigger.

A successful match can be used to trigger the change password workflow in the state engine. The regular expression look like .*change.*

Note: This powerful trigger monitors user input and can be used in state engines that perform logon automation on terminal or mainframe applications that need heavy user interaction.

This trigger is sensitive to the signature of the window that is monitored for keyboard input.

If there are problems detecting the keyboard input on a window, try making the signature more generic or more specific.

If input from a previous Simulate keyboard input action is to trigger a Key is pressed down on a window trigger, ensure that the signatures for the input action and the key down trigger are identical.
Left mouse button is clicked Windows raises a left button down event when the left button of a mouse is clicked in an application window.

This trigger fires when this clicking of the left mouse button occurs.

The parameter of this trigger is the signature of the window in which the left mouse button is clicked.

Example:

To trap the left mouse button click OK, the Signature element would be 
/child::wnd[@title="Messenger Talk"]/
child::wnd[@class_name="Main View"]/
child::wnd[@class_name="#32770"]/
child::wnd[@class_name="Button" and @ctrl_id=1]
Tip: This trigger would normally contain a capture_action to capture the user name and password after the user clicks OK.
Right mouse button is clicked Windows raises a right button down event when the right button of a mouse is clicked in an application window.

This trigger fires when this clicking of the right mouse button occurs.

The parameter of this trigger is the signature of the window in which the right mouse button is clicked.

Example:

To trap the right mouse button click an OK button, the Signature element would be 
/child::wnd[@title="MessengerTalk"]/child::wnd[@class_
name="Main View"]/child::wnd[@class_name="#32770"]
/child::
wnd[@class_name="Button" and @ctrl_id=1]
MDI child window is activated Windows raises an activate events for other applications when a child window of an application with a title bar receives focus or is selected by the user.

The only parameter of this trigger is the signature of the child window that receives focus or is selected.

Example:

Some applications have child windows that can be monitored for mdi_activate events only. In such cases, the MDI child window is activated trigger is used instead of the Window is activated trigger.
Cursor moves on a window Windows raises a set cursor event for a window on which the cursor is active.

This trigger fires when the cursor moves on the specified window.

The parameter of this trigger is the signature of the window which set cursor" event is trapped.

Example:

To trap a "set cursor" event on window with signature / child::wnd[@title="Messenger"]/child::wnd[@ctrl_id="102"], use 
<wnd_set_cursor_trigger> 
<signature>/child::wnd[@title="Messenger"]/ child::wnd
[@ctrl_id="102"]</signature> 
</wnd_set_cursor_trigger>
Windows field gets focus Windows raises the set focus event when any input field on the window is clicked.

This trigger is fired when clicking occurs.

The parameter of this trigger is the signature of the window whose input field that is being monitored for input field click.

Example:

To trap a "set focus" event on window with signature / child::wnd[@title="Messenger"]/child::wnd[@ctrl_id="102"], use 
<wnd_set_focus_trigger> 
<signature>/child::wnd[@title="Messenger"]/ child::wnd
[@ctrl_id="102"]</signature>
Text is displayed on a window Windows raises a set text event when the text of a window is modified by an external program.

This trigger is fired when this modification by an external program occurs.

The parameter of this trigger is the signature of the window where the text modification is to occur.

Example:

To trap a set text event on a window with signature / child::wnd[@title="Messenger"]/child::wnd[@ctrl_id="102"] use 
<wnd_set_text_trigger> 
<signature>/child::wnd[@title="Messenger"]/ child::wnd
[@ctrl_id="102"]</signature> 
</wnd_set_text_trigger>
Window is shown Windows raises a window show event before a window is displayed on screen or before it is hidden (through minimization).

This trigger fires before the window is displayed or hidden.

The parameter of this trigger is the signature of the window which is to be displayed or hidden.

Example:

To trap the show event on a window with a text that says, "Sign in". 
<wnd_show_window_trigger> 
<signature>/child::wnd[@title="Sign in"]</signature> 
</wnd_show_window_trigger>
Note: If the window with the specified signature is not found, no event trapping would be set. To make sure that the window is available, set a trap to activate the top-level parent window containing that window.
Window position changes Windows raises an event when the position of a window is changed on the desktop.

This trigger fires when this change in window position occurs.

The parameters to this trigger are the signature of the window that is to be monitored for position change and an optional flag parameter value (the flag is a member of the WINDOWPOS structure which can be obtained using Spy).
Menu item is clicked This trigger fires when a specified menu item on the Windows application is clicked.

The other parameters to this trigger are the signature of window with the menu and the path of the menu item.

Example:

For the trigger to fire Menu item is clicked, specify: Signature of the window with the menu: 
/
child::wnd[@title="Form1" and
@class_name="ThunderRT6FormDC"]
Menu Path: File/Login
Tip: You can specify a multi-level menu item by providing a separator '/' in the menu path. For example File/Open.
Text is found on a console window This trigger searches for and fires when it finds the text that is specified in the sections parameter by polling for text in the console application screen.

The other parameters to this trigger are the sections of the text to match against the screen contents, the polling interval in seconds and the number of times the window is searched, the polling count.

Note: As this trigger is a poller, use this trigger judiciously.
Browser starts navigating A before navigate event takes place when the web browser starts navigating to a URL. This trigger is fired when this navigation to a URL begins.

Example:

To trap the event, user navigating out of a web page - for example, http://www.mail.example.com/ - use: 
<web_before_navigate_trigger> </web_before_navigate_
trigger>
Tip: As this trigger would trap all before navigate events, use test property for filtering.
HTML element completes loading The web browser raises an on load event when the loading of specific HTML elements on a web page is complete.

For example, this event and trigger are fired when the body of an HTML page finishes loading.

The parameter of this trigger is the signature of the HTML element which is to complete loading for the trigger to fire.

Example:

To trap an onload event on the body element, 
<web_elem_onload_trigger> 
<signature>/child::html[@tag_name="body"]</signature>
Key is pressed on a web page A web browser raises the key press event when a key is pressed for an HTML element.

This trigger fires when this event is raised for the specified HTML element.

The parameter of this trigger is the signature of the HTML element which is being monitored for pressing of the key.

Example:

To trap a key press event on an image element which source is someimage.jpg, use 
<web_key_press_trigger> 
<signature>/child::html/child::html/child::html[@tag_
name="img" and src="someimage.jpg"]</ signature> 
</web_key_press_trigger>
Note: If the HTML element of which the key press event has to be trapped has a JavaScript for that event, it means either of the following events: after or before the JavaScript execution. Set the before_javascript attribute to 0 to trap after the script execution.
Browser closed A browser close event takes place when the web browser closes. This trigger is fired when this event takes place.
Left mouse button is clicked on a web page Fires when the left mouse button is clicked on a web page control.

Use this trigger for Web elements if the HTML element is clicked trigger does not work. This trigger always fires before any JavaScript handler on the web page.

Provide the signature for the web element on which the mouse click has to be captured.

This trigger cannot be used as the first trigger to kick off the state-machine in the AccessProfile.

The HTML element is clicked trigger can fail for various reasons: either the element does not generate a click event, or the JavaScript code of the web page does not handle the click properly. Use this trigger in such cases.
HTML element is found Fires when the specified HTML control is found.

This trigger sets up a polling mechanism and searches for the specified HTML control.

Specify the HTML control signature, the polling interval, and polling count. The first poll is done immediately, and subsequent polls are made at the specified interval.
Note: Do not use this trigger as the first trigger to kick off the state-machine in the AccessProfile. Precede the first instance of this trigger with the Web page completes loading trigger.
HTML element gained focus Fires when the specified HTML control gets keyboard focus.

A flashing caret represents keyboard focus for an edit control.

Use this trigger in scenarios when the web page modifies the contents of the edit control on gaining focus.
HTML element lost focus Fires when the specified HTML control loses keyboard focus.

A flashing caret represents keyboard focus for an edit control.

Use this trigger in scenarios when the web-page modifies the contents of the edit control on losing focus.
Text is first displayed (Terminal) A terminal application raises the terminal application screen output event when there is text output on the application screen.

This trigger fires when this text output occurs. The parameter of this trigger is a regular expression of the text that is being searched.
Text is first displayed (Mainframe) AccessAgent raises the screen text change event when there is a change in the text anywhere on a window of the process for which an AccessProfile is running.

This trigger fires when this text change occurs.

The parameter of this trigger is sections of the text to match against the window contents.

Example:

To trap a "screen text change" event when a window 10th line changes to "user name:" 
<mf_screen_output_ex_trigger> 
<sections> 
<section> 
<match_text_section> 
<line from="10" to="10"></line> 
<match_text>user name:</match_text> 
</match_text_section> 
</section> 
</sections> 
</mf_screen_output_ex_trigger>
Text is found (Mainframe) Specifies information for the trigger to fire when there is a specific text output on a mainframe application screen.

A mainframe application raises the screen output event when there is text out anywhere on a mainframe application window.

This trigger fires when this text output occurs.

The parameter of this trigger is sections of the text to match against the window contents.

Note: As this trigger is a poller, use this trigger judiciously.
Text is displayed (HLLAPI) The HLL framework of an HLL-compatible Mainframe or terminal application generates a message when the application outputs some text to screen.

This trigger is fired when this output occurs. Specific sections of text output to the screen can be matched by this trigger.

The parameters of this trigger are the signature of the HLL-enabled application window and a regular expression of the text that is being searched.

Note: This trigger works only for an application that is HLLAPI-enabled. Common HLLAPI-enabled applications are: Attachmate EXTRA!, IBM® iSeries and Reflection.
HLLAPI session starts The framework of an HLL application generates a message when an HLL-compatible Mainframe session starts.

This trigger fires when this session starts.

The parameters to this trigger are the signature of the HLL-enabled application window and the HLLAPI short name for the application.

Example:

<hll_session_start_trigger> 
<short_name>A</short_name> 
<long_name></long_name> 
<wnd_signature>/child::wnd[@class_name="SDIMainFrame" 
and @title#"WS - EXTRA! X-treme"]</wnd_signature> 
</hll_session_start_trigger>
Note: If the short name is not configured on the EXTRA application, then this trigger does not fire.
Fire immediately This trigger fires at a zero second timeout. There are no parameters for this trigger.

Example:

This trigger is used to test the value of properties that were set in previous states.

Note: Use two Fire immediately triggers in a state to control the flow in a state-engine by testing for one possible value of a Boolean condition as a test_property in each trigger.

Do not use two Fire immediately triggers in the same state without test_properties transiting to different states. The behavior of such usage cannot be predicted reliably.
On logon to AccessAgent AccessAgent raises a logon event when an AccessAgent user logs on.

This trigger is fired when this logon occurs.

The parameter of this trigger is the signature of the window on which automated logon is performed.

Tip: This trigger is used to perform automated logon to an application that runs without being terminated across multiple user sessions, as soon as a user logs on to AccessAgent.
On logoff from AccessAgent AccessAgent raises a logoff event when an active AccessAgent user logs off.

This trigger is fired when logoff occurs.

The parameters of this trigger are: Timeout in seconds, whether logoff is synchronized across applications, and whether logoff can happen concurrently. The default settings suffice for most cases.

Example:

This trigger is used to perform graceful logoff from desktop applications when a user logs off from AccessAgent.

The actions in this trigger can save the current work of the user and log the user off or terminate the application when a logoff event is received.

Tip: Use On logoff from AccessAgent triggers to ensure that a user is logged off an application regardless of when the user chooses to log off from AccessAgent. There are typically multiple On logoff from AccessAgent triggers in multiple states in a state engine.
Fire after specified time This trigger always fires after the timeout counter expires. The parameter to this trigger is the timeout value, in seconds.

Example:

This trigger can be used to test the value of properties that were set in previous states.

Use this trigger to wait for an application window to stabilize if the control IDs of the user name or password field change after window creation.

Use this trigger as a last resort, if all the triggers in a particular state never fire. This trigger prevents the state engine from freezing in that state.

Tip: Avoid using too many timeout triggers in an AccessProfile. Using too many timeout triggers makes the state-engine more difficult to troubleshoot or debug. It also increases the scope for user intervention during logon automation.
Java™ window is activated JVM raises an activate event on a Java window with a title bar when it is activated by the user or a program, using the mouse or the keyboard, or programmatically.

This trigger is fired when this activation of Java window occurs. The activation is typically characterized by the appearance of the Java window in the foreground with a highlighted title bar.

The parameter of this trigger is the signature of the Java window that is activated.

Example:

To trap activate on Java window with title say, "Login", 
<jwnd_activate_trigger> 
<signature>/child::jwnd[@title="Login"]</signature>
</jwnd_activate_trigger>
Note: The Java window activate trigger works only on a Java window with a title bar. It works only for windows within the same process the agent is residing. First, the agent loads into the intended process before using activate trigger on the window within that process. Unlike other triggers, this trigger would not fail even if the window is not present when the trap is being set. If this trigger is used, the java_ses_info_item must be added to the site_info of the AccessProfile for the trigger to work.
Java window is clicked Java generates the click event when a Java window is clicked manually or automatically.

This trigger fires when the Java window is clicked.

The parameter of this trigger is the signature of the Java window which is being monitored for clicking.

Example:

To trap a click event on a Java window, use 
<jwnd_click_item_trigger><signature>/
child::jwnd[@class_name="LoginPanel1"]/
child::jwnd[@class_name="javax.swing.JRootPane"]/
child::jwnd[@class_name="javax.swing.JLayeredPane"]/
child::jwnd[@class_name="javax.swing.JPanel"]/
child::jwnd[@class_name="javax.swing.JPanel"]/
child::jwnd[@class_name="javax.swing.JButton" and 
@is_visible=1 and @title="jButton1"]</signature>
</jwnd_click_item_trigger>
Note: If this trigger is used, the java_ses_info_item must be added to the site_info of the AccessProfile for the trigger to work.
Java window is found This trigger is sensitive to the signature of the window that is monitored for keyboard input.

If there are problems detecting the keyboard input on a window, try making the signature more generic or more specific.

If input from a previous Simulate keyboard input action triggers a Key is pressed on a Java window trigger, ensure that the signatures for the input action and the key down trigger are identical.

Note: Avoid using this trigger unless it is necessary. In general, any polling mechanism introduces performance overheads that spoil the user experience. If this trigger is to be used, the java_ses_info_item must be added to the site_info of the AccessProfile for the trigger to work.
Key is pressed on a Java window Java generates a key down event when a key or a combination of keys on the keyboard are pressed.

The parameters of this trigger are the signature of the Java window that must be monitored for keyboard input and the key combination that match.

Example:

To capture the user name and password when logging in to an internet banking system, specify the signature of the password field in the signature box and choose to fire the trigger on the Enter key.

Note: If this trigger must be used, the java_ses_info_item must be added to the site_info of the AccessProfile for the trigger to work.

This trigger is sensitive to the signature of the window that has to be monitored for keyboard input.

If there are problems detecting the keyboard input on a window, try making the signature more generic or more specific.

If input from a previous Simulate keyboard input action triggers a Key is pressed on a Java window trigger, ensure that the signatures for the input action and the key down trigger are identical.
JVM becomes available This trigger fires when the JVM (Java Virtual Machine) is available.

The other parameters of this trigger are the signature of window with the menu and the path of the menu item.

Example:

For the trigger to fire Menu item is clicked, specify: Signature of the window with the menu: 
/child::wnd[@title="Form1" and
@class_name="ThunderRT6FormDC"]
Menu Path: File/Login
Note: For Java applications, this trigger is provided in the start state so that the JVM is ready before any automation or SSO starts.

If this trigger must be used, the java_ses_info_item must be added to the site_info of the AccessProfile for the trigger to work.
Parent topic: AccessStudio Guide

Feedback