Main Window Commands
Main window commands are responsible for interacting with the primary window of an application, or the application itself rather than the current child window.
BringToForeground
The BringToForeground command is used to bring the main application into the foreground and to trigger a Windows “new foreground window” event which, in turn, will trigger any relevant pending WhenWindow commands in the desktop script.
This is necessary when an application opens behind the browser window when starting it from the Vault.
It is also commonly required when interacting with browser-based apps such as Flash sites or those that use custom embedded browsers.
Syntax Diagram
Parameters
When writing scripts, it is recommended to start with the least intrusive option and only move on to the more intrusive ones if necessary. The options are shown below from least visually intrusive to most intrusive.
Option Name | Impact | Technical Notes |
|---|---|---|
| Visually low, performance fast | Uses “SwitchToWindow” method. Default timeout is 10000 |
| Visually low, performance mediuim | Uses Cross Process Thread Linking method. Default timeout is 10000 |
| Visually medium, performance medium | Uses programmatic ALT TAB to switch away and back to the window. Often fails to restore window, but does take it away from foreground, can then use Switch option to bring back. Default timeout is 0 |
| Visually high, performance medium | Forces window to minimise and restore. Default timeout is 10000 |
| Visually high, performance medium | Sends the Windows messages SC_HOTKEY and SC_RESTORE to attempt to redraw the window in the foreground. Rarely achieves the aim. Default timeout is 10000 |
The timeout parameter tells the command how many milliseconds to wait while trying to detect that the window is now in the foreground. If the timeout expires then the script moves to the next command. When running multiple BringToForeground commands in a row it can be beneficial to reduce the default timeout.
Example
BringToForeground BtfAltTab
Application Notes
Microsoft deliberately makes this a difficult task to accomplish programmatically (the reason being to stop malicious software from hijacking a desktop). The result of this is that there are several different ways to try and achieve this effect and some have a more noticeable effect to the users than others.
Use the suggested approach, below, first and then experiment with various combinations of options if that does not work.
Note
It may not be 100% possible to force a window to the foreground because of this designed in behaviour by Windows.
Hint
Experimentation has shown the most effective way to use this command is to use it twice: first with the BtfAltTab option to ensure the app has been removed from the foreground and then with the BtfSwitch option to bring it back to the foreground.
BringToForeground BtfAltTab
BringToForeground BtfSwitch
SaveChanges
Ensures that any changes made to the bookmark attributes are written back to the My1Login repository.
This must be called after a bmNewPassword reference in order to save the new password value in the desktop app’s bookmark.
See the Password Change Example
Syntax Diagram
Parameters
None
Example
SaveChanges
SelectControl
Selects a control on the script process’ forground window, based upon the provided ControlSelectOptions.
The selected control is the automatic target when the commands below occur after the SelectControl command:
Syntax Diagram
Parameters
ControlSelectOptions
Used to determine which control in the current window should be selected.
See ControlSelectOptions for details.
Example
// Select the button with Control ID 0x82B3
SelectControl ControlButton 0x82B3
// Select the button ending with the text "SAP"
SelectControl ControlButton EndsWith "SAP"
UnSelect
De-selects any currently selected control.
Any subsequent actions that would target the control will now target the application’s current foreground window.
See SelectControl for details on affected commands.
Syntax Diagram
Parameters
None
Example
UnSelect
Wait
The Wait command pauses the script execution for one second or for a user specified number of milliseconds.
Warning
Wait commands should be used sparingly because they give an opportunity for a different app to take over the desktop. It is best to control script execution deterministically if possible.
Syntax Diagram
Parameters
Parameter Name | Description |
|---|---|
timeoutMillisecond | The number of milliseconds that the script should pause for. Default is 1000. |
Example
// Wait for half a second
Wait 500
// Wait for a second (two options)
Wait
Wait 1000
Application Notes
Wait is typically used to give the user interface time to paint its controls prior to injecting credentials into them. Try without using a Wait and only add one if nothing appears to be happening when the SendKeys command (or one of the select commands) is executed.
In most cases a wait of 100ms is adequate and minimises the time when another app could take the screen.
Related Articles
App Control Commands
App control commands are commands that emulate user interaction with a desktop application. I.e. they select controls, press buttons, type text or click the mouse. LeftClick Performs a mouse left click at the provided co-ordinates. The mouse cursor ...Desktop Client Commands
Table of Script Commands Command Description AlertInfo / AlertError Commands to show text messages to users. BringToForeground Attempt to force the main app window to desktop’s foreground. InteractiveSelectBookmark Allows manual intervention when ...Desktop Scripting
Structure of a Script A Desktop DSL Script has the following functional sections (not all are required for all apps): Error Directive Determines the impact of errors on the script run. Process Start and Identification Ensures the correct windows ...Error Directive, Alerting & Logging Commands
OnError Controls the processing of a script in the event of a runtime error. Multiple OnError commands may be used to control behaviour at different points in the script. Syntax Diagram Parameters Terminate - stop script execution Continue - continue ...Child Windows
Child Windows Child window commands are responsible for triggering behaviour when a dialog (child window) of the monitored process opens. WhenWindow Waits until a window (dialog box) child of the target app, whose caption matches the parameter value ...