Define Command Line Arguments in INI File

INI files are commonly used configuration files for storing settings and preferences for applications. The PS_Automate utility uses INI files to specify its own settings and parameters. It is generally provided as a command line parameter, for example, ini=login.ini. If no file is specified, the utility looks for an INI file in the same source directory with the same name as the utility, i.e. ps_automate.ini.

When command line arguments are provided, they can technically be listed in any order as each is prefixed with the argument name, i.e. argument=value.

The following common predefined INI files are included with the deployment of the PS_Automate utility.

  • AWSWebApp.ini for Amazon Web Services logins
  • BIWebApp.ini for BeyondInsight logins
  • GoogleWebApp.ini for Google URL logins
  • MSWebApp.ini for Microsoft URL Logins
  • ssms_database.ini for SQL Server Management Studio v18 logins

The INI file is in standard INI format consisting of one or more sections with each section containing one or more key/value pairs. Each of the sections and their key/value pairs are described below.

General Section

The [General] section defines the main settings for the application. Each setting and its accepted values are listed below.

Setting Definition
BrowserName Value: String (default is msedge)
Required: No
Description: Specifies the browser to launch for web app login (Edge, Chrome, Firefox). The browser can be specified in the INI file or overwritten by command line parameters.
TargetURL Value: String
Required: Yes
Description: Specifies the web app URL. The URL can be specified in the INI file or overwritten by command line parameters.
EnableLogging Value: Integer
  • 0 No logging (default)
  • 1 Error level
  • 2 Warning level
  • 3 Info level
  • 4 Debug level (Used for troubleshooting issues. A new console window is launched.)
Required: No
Description: Specifies if logging should be enabled.
LogMethod Value: Integer
  • 1 Log to file (default)
  • 2 Log to debug window
  • 3 Log to both
Required: No
Description: Specifies what log method to use.
LogPath Value: Valid file path
Required: No
Description: Specifies the path to create log files. Defaults to script path.
FixupPassword Value: Boolean (1*|0)
Required: No
Description: Specifies a different method of parsing out the password parameter. This allows a wider array of complex passwords to be used, such as space and quotes. Defaults to true.
RunApp Value: Any valid Windows executable. May include custom command line values.
Required: Only when TargetURL is not used.
Description: This is the initial application launched by the utility. The RunApp may also contain values based from the command line.
FileChangeDir Value: Any valid Windows directory. May NOT include custom command line values.
Required: No
Description: This is the initial working directory for the app in RunApp. Some apps require a custom WorkingDir value.
AppWindowTitle Value: Any valid Windows title name.
Required: No
Description: This is the window the utility initially connects to for targeting commands. We recommend providing this value; otherwise, the currently active window is targeted, which may lead to undesirable results.
WindowTitleMatchMode

Value: Integer (-1*,-2,-3,-4,1,2,3)
Required: No
Description: This is the method used to match the AppWindowTitle with the actual window text. The default is a case-insensitive search from the start of the window text.

For more information, please see Windows Titles and Text.
IgnoreCerts

Value: Integer (1*|0)
Required: No
Description: Enabling this option causes the Certificate warning screen to be automatically bypassed (accepted). This option only works on localhost for Chrome and Edge. Firefox does not have a localhost limitation.

This setting is for testing purposes only as bypassing certificates is NOT secure.
GlobalSequenceDelay

Value: Integer in milliseconds (default is 250)
Required: No
Description: How much time to wait in between each TaskSequence.
KioskMode

Value: Integer (0 | 1) (default is 0)
Required: No
Description: Set to 1 to enable Kiosk mode in the browser. Application runs in full screen without any browser user interface such as toolbars and menus.

Credentials Section

The [Credentials] section is an optional section used for hard coding the username and password values into the INI file. When this section is provided, both keys are required and override any command line values provided.

This section is used for testing. We recommend you secure any INI files containing credentials.

Setting Definition
UserName Value: Valid username
Required: Yes
Description: The username to provide to the security dialog. Specified as %username% to the provided task.
Password Value: Valid password.
Required: Yes
Description: The password to provide to the security dialog. Specified as %password% to the provided task.

TaskSequences Section

The [TaskSequenceX] sections of the INI file define the tasks to take once the RunApp or TargetURL has been accessed.

Place each [TaskSequenceX] in its own section in the INI file in sequential order and ideally order them numerically as per the following example:

[TaskSequence1]
task=value
…
[TaskSequence2]
task=value
…
[TaskSequence3]
…

Each [TaskSequenceX] can perform one or more tasks. Generally, a specific task sequence consists of providing information to target the appropriate dialog box/control and then send text or a command to it, for example click. Most pages generally require a minimum of two task sequences, one to populate the username and one to populate the password. Since tasks can be combined within the [TaskSequenceX], the submission (posting) of these values can be tasks of the same [TaskSequenceX].

Sometimes additional task sequences must be performed before or after supplying credentials. However, it is possible to automate many actions with a single task sequence through the use of SendKeys for Windows applications only.

App and WebApp task sequences and their values are listed below. All tasks within a task sequence are optional, though some depend on others or are mutually exclusive.

Each task can be defined only once within each [TaskSequenceX].

App Task Sequences

App task sequences begin after being initiated by a RunApp.

The standard function of a sequence is to enter a string of data (SendKeys) into a particular control (AppWindowControlID) on a window. If a control is provided to the sequence, the utility attempts to attach to the control, focus it, and send it directly to the control. This is a very accurate way of targeting commands. If no control is provided (or one can’t be found), the commands can still be issued to the active window/control.

In addition to the tasks from the generic task sequences, the following tasks are applicable for the RunApp (App) task sequences.

Setting Definition
SequenceDelay Value: Integer in milliseconds (default is 0)
Description: How much time to wait at the beginning of each task sequence. This is in addition to any value provided in GlobalSequenceDelay.
SendKeys

Value: Any valid string of characters
Description: A sequence of characters to send to the focused control/field. The utility supports the special characters defined by AutoIt({TAB}, {ENTER, etc.) when using the default mode of SendKeysRaw.

For more information on the special keys, please see the following:
SendKeysDelay Value: Integer in milliseconds (default is 5)
Description: This is the amount of time the utility waits in between each key stroke sent by SendKeys. It may be necessary to increase this delay if the interface cannot respond quickly enough to the send keys.
SendKeysRaw Value: Boolean (1*|0)
Description: Changes the interpretation of the SendKey sequence to be raw (literal). It will not interpret any of the special characters as defined by the AutoIt Send command. Due to the complexity of the characters often involved, we recommend setting this when using SendKeys to send passwords .
AppWindowTitle

Value: Any valid Windows title name.
Required: No
Description: This is almost identical to the AppWindowTitle specified in the generic task sequences. However, this is used to target to a new window that may be open during the authentication attempt. This value only needs to be provided if a new window requires focus. For instance, clicking on a login button may present a security warning or legal disclaimer in a new window which requires targeting. While it is not always required to target the new window directly, it can improve accuracy.
WindowTitleMatchMode

Value: Integer (-1*,-2,-3,-4,1,2,3)
Required: No
Description: This is identical to the WindowTitleMatchMode specified in the generic task sequences; however, it targets the AppWindowTitle App task sequence.
AppWindowControlID

Value: Any valid window control ID name.
Description: When provided, the utility targets the control directly. Valid control names are found with the AutoIt Windows Info utility and can be provided in a variety of formats.

For more information, please see ControlCommand.
AppWindowControlClick Value: Boolean (1*|0)
Description: Sends a standard left click event to the control defined in AppWindowControlID. Often, SendKeys can be used to simply send an {ENTER} command to a focused control, but in some circumstances, it may be necessary to send a click directly.

WebApp Task Sequences

The web application depends on a TargetURL from the General section. Task sequences use Xpath to find and click the web page element.

The standard function of a web application task sequence is to enter an Xpath string for the element you want to interact with, as well as a value for the element.

The webapp tasks rely on browser drivers to accomplish their tasks. The utility automatically downloads the browser driver to the same location as the utility. The browser version (major.minor.build) must match the driver version or the utility may fail to launch the browser. For example, chromeDriver 100.0.4896 will work with Chrome browser 100.0.4896.x.

Ensure the functional account used for the RDS Session has network permissions that allow the PS_Automate to access the internet. For example, add the functional account to GPO, thereby allowing the functional account to use the proxy.

In addition to the tasks from the General section, the following tasks are applicable for the WebApp TaskSequences section.

Setting Definition
XPathElement Value: Xpath string for the element
Description: Goes to the element specified.
XPathValue Value: Xpath string for the element value.
Description: Enters the text specified into the element.
XPathAction Value: String value click, clear.
Description: Clicks on the element specified by XPathElement.

Certificates

For keeping sensitive web traffic information secure, certificates are used. The PS_Automate utility has the ability to IgnoreCerts, which are provided for internal self hosted websites and for testing only.

Chrome and Edge browsers can ignore certificates for localhost only. The Firefox browser does not have this limitation.

Web App Known Issues

  1. When multiple RDP sessions are launched for the same machine at the same time, the end user may experience a delay with the automated logon for one of the sessions. One session blocks while the other loads. Once the session successfully loads (maximum wait time 30 seconds), the other session is able to successfully load its browser and begin the automated login.

  2. Manually clicking, opening new browser windows, or creating tabs on the launching of the automated browser can cause the automated login to fail.

  3. Issues automatically updating the Firefox driver (geckodriver) to the latest version. If PS_Automate fails to launch the Firefox browser, one possible cause is that the driver version is out of date. PS_Automate attempts to update the driver; however, there is a known issue where geckodriver updates may fail. In that case download the geckodriver, from https://github.com/mozilla/geckodriver/ and place it in the same directory as ps_automate.exe.