Run

Declaration

<AMRUN FILE="text" DEFAULTFOLDER="text" PROCESSIDVARIABLE="text" WAITFORINPUT="YES/NO" WAITFOREND="YES/NO" OUTPUTVARIABLE="text" OUTPUTFILE="text" OVERWRITEOUTPUTFILE="YES/NO" TERMINATEAFTERTIMEOUT="YES/NO" TERMINATEAFTERTIMEOUTLENGTH="number" TERMINATEAFTERTIMEOUTSCALE="test (options)" RESULTVARIABLE="text" WINDOWSTARTUP="text (options)" SINGLEINSTANCE="YES/NO" DOS="YES/NO" RESULTDATASET="text" />

Related Topics   

Overview

Runs the specified program, application, or document. If a document is specified, the application associated with the document is used to open it. This action comprises some built in conveniences, such as the ability to wait for an application to finish loading (it is ready for input) or wait for it to complete its operation before continuing to the next step.

Practical usage

Commonly used to start an application or open a document in preparation to send keystrokes, mouse clicks, or other interactive steps. You can also specify documents in this action, so for many applications it is not necessary to first start the application and use a separate step to open the document, as it can all be done in this one step.

Parameters

General

Property Type Required Default Markup Description
Run Text Yes (Empty)

  • FILE="C:\Temp\File.exe"

  • FILE="Notepad.exe"

 The path and file name of the file to run. If necessary, this parameter should include the full path to the EXE, COM, BAT, or CMD file you want to run. To specify a document, click the folder icon or use Start (Windows logo) to browse to the desired item. The properly formatted command line including the associated application for the document is automatically built.
Run only if another instance isn't running Yes/No No No SINGLEINSTANCE="YES" If selected, the application specified in the Run parameter does not start if another instance of that application is already running on the system. Instead, the step is ignored and no error is generated. If disabled (default), the specified application runs despite other running instances.
Match processes by name (for compatibility with 64-bit applications) Yes/No NO (Empty) COMPAREBYNAME="YES" If selected, the method of comparing processes is by the name of each process. This parameter is active only if the Run only if another instance isn't running parameter is enabled.
Initial window state Text (options) No Normal

  • WINDOWSTARTUP="normal"

  • WINDOWSTARTUP="maximized"

  • WINDOWSTARTUP="minimized"

  • WINDOWSTARTUP="hidden"

 In certain situations, a specific application might be more convenient to have running in the background, minimized or out of the way of other programs. This property allows you to control the state that the application window should adhere to upon startup. The available options are:

  • Normal (Default) - The application window starts in a normal state.

  • Maximized - The application window starts maximized (fill the entire screen).

  • Minimized - The application window starts minimized to the taskbar (or notification tray).

  • Hidden - The application window starts hidden. This is ideal for running batch files or console applications without the unwanted DOS window appearing.

NOTE: If an application is set to start Hidden, execution occurs without a visible window, thus, any interactive actions that try to interact with the hidden application fails.
Startup folder Text No (Empty) DEFAULTFOLDER="C:\Program Files\AutoMate 2025\" The application startup folder (if one is required). This option is not required and is available primarily for legacy (older) applications. When not specified, the folder that the application resides in is used.

Wait

Property Type Required Default Markup Description
Do not wait Yes/No No No WAITFORINPUT="NO" If selected, the step does not wait until the application is finished loading. Selecting this option can result in the task moving to the next line too early which causes interactive steps to be sent into nothing. This parameter is disabled by default.

If the Wait until application completes parameter is selected then this parameter is ignored.
Wait until application is ready for input Yes/No No Yes WAITFORINPUT="NO" If selected (default), the step waits until the application is finished loading and is ready to receive input such as keystrokes or mouse clicks. Setting this parameter to NO can result in the task moving to the next step too early which causes any interactive steps to be sent into nothing (because the application has not fully loaded yet). If the Wait until application completes parameter is selected then this parameter is ignored.
NOTE: DOS applications, batch files, and certain console applications might not function correctly with this parameter selected because such applications do not support standard Windows event messaging that enables this kind of integration. For these applications, you might need to use a Pause action or other method of waiting for the application to be ready for input.
Wait until application completes Yes/No No No WAITFOREND="YES" If selected, the step waits until after the application has either closed itself (in the case of batch files, scripts, or console applications) or is closed by the user (in the case of Windows applications).
Populate variable with return code Text No (Empty) RETURNCODEVARIABLE="code" If enabled, specifies an already existing variable to be populated with the application-provided return code. This parameter is only available if the Wait until application completes parameter is selected.
NOTE: Not all applications use return codes, so the functionality of this action may vary depending on the application.
Terminate process after Number No No TERMINATEAFTERTIMEOUT="YES" If selected, the running process will be terminated when the timeout period is reached. This parameter is disabled by default and only available if the Wait until application completes parameter is selected.
Timeout length Number No No TERMINATEAFTERTIMEOUTLENGTH="50" The length of the timeout period. This value is used along with the Timeout scale parameter to display a timeout value.
Timeout scale Options No No

  • TERMINATEAFTERTIMEOUTSCALE="milliseconds"

  • TERMINATEAFTERTIMEOUTSCALE="seconds"

  • TERMINATEAFTERTIMEOUTSCALE="minutes"

  • TERMINATEAFTERTIMEOUTSCALE="hours"

The scale used to specify the timeout period. This parameter is used along with the Timeout length to display a timeout value. The available options are:

  • Milliseconds - The timeout value is measured by milliseconds.
  • Seconds (Default) - The timeout value is measured by seconds.
  • Minutes -  The timeout value is measured by minutes.
  • Hours -  The timeout value is measured by hours.

Data

Property Type Required Default Markup Description
Populate variable with process ID Text No (Empty) PROCESSIDVARIABLE="ID" If enabled, specifies an already existing variable is populated with the application process ID.
Create and populate Dataset Text No (Empty) RESULTDATASET="myDataset" If enabled, specifies the name of a dataset to create and populate with data from the window of the application that ran. More information about the dataset that this action creates can be found below under Datasets.
Populate variable with window class Text No (Empty) WINDOWCLASSVARIABLE="myvar" If enabled, specifies an already existing variable is populated with the window class of the application that is launched. If the Do not wait parameter is selected under the Wait properties, this parameter becomes unavailable.
Populate variable with window handle Text No (Empty) WINDOWHANDLEVARIABLE="handle" If enabled, specifies an already existing variable to populate with the window handle of the application that is launched. If the Do not wait parameter is selected under the Wait properties, this parameter becomes unavailable.
Populate variable with window title Text No (Empty) WINDOWTITLEVARIABLE="title" If enabled, specifies an already existing variable to populate with the window title of the application that is launched.  If the Do not wait parameter is selected under the Wait properties, this parameter becomes unavailable.

Advanced

Property Type Required Default Markup Description
Run application as Yes/No No No

  • DOS="YES"

  • ASEXPLORER="YES"

 Specifies how the application should be launched as. The available options are:

  • Standard Windows application (Default) -The application runs as a standard Windows application.

  • Document - The application runs as a document such as MS Word.

  • Console application - The application runs as a console application that takes input and displays output at a command line console. Selecting this option enables the following parameters.
Capture standard output stream to variable Text No (Empty) OUTPUTVARIABLE="theVariable" If enabled, specifies that an existing variable is populated with the console output. Valid only if the Run application as parameter is set to Console application.
NOTE: These settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.
Capture standard  output stream to file Text No (Empty) OUTPUTFILE="C:\Temp\filename.txt If enabled, specifies a file to which the console output is written. Valid only if the Run application as parameter is set to Console application.
NOTE: These settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.
Overwrite if file already exists Yes/No No No OVERWRITEOUTPUTFILE="YES" If selected, specifies that if the file being written to already exists, it is overwritten. If disabled (default) and the file already exists, it is not overwritten, however, the step fails as a result. Valid only if the Run application as parameter is set to Console application.
NOTE: These settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.
Capture standard error stream to variable Text No (Empty) ERRORVARIABLE="theVariable" If enabled, specifies that an existing variable is populated with the console error code (if any). Valid only if the Run application as parameter is set to Console application.
NOTE: These settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.
Capture standard error stream to file Text No (Empty) ERRORFILE="C:\Temp\filename.txt If enabled, specifies a file to which the console output is written. Valid only if the Run application as parameter is set to Console application.
NOTE: These settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.

Description

Error Causes

On Error

Additional notes

Datasets

A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset containing a specific set of fields in addition to the standard dataset fields. The following table describes these fields (assuming the dataset assigned is theDataset):

Name Type Return Value
theDataset.Title Text The window title.
theDataset.Class Text The window class.
theDataset.Handle Text The window handle.
theDataset.ProdcessID Text The process ID.
theDataset.ReturnCode Number The Return Code.

Example

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Description

The following sample task runs Notepad and sends keystrokes to it:

Copy 
<AMRUN FILE="Notepad" />
<AMINPUT KEYSTROKES="Sending keystrokes to Notepad." PREDELAY="500" STAYFOCUSED="YES" DELAYBETWEENKEYS="50" />