Run Action Icon

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" />

See Also

Change Printer | Display | Empty Recycle Bin | End Process | Get Process Information | Get Volume Information | Log Event | Print | Registry

Description

Runs the program, application or document specified. If a document is specified, the application associated with the document will be used to open it.

Practical Usage

Commonly used to start an application or open a document in preparation to send keystrokes, mouse clicks or other interactive steps. This action has built in conveniences such as waiting for the application to be ready for input (finished loading) before moving on to the next step. The properties dialog box has a built in Start menu for easy selection of the application.

Remember that you can also specify documents in this action, so for many applications it is not necessary to first start the application and then use a separate step to open the document, as it can all be done in this one step.

Parameters

General Properties

Property

Type

Req'd

Default

Markup

Description

Run

Text

Yes

(Empty)

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

  2. FILE="Notepad.exe"

The command line to run. This parameter should specify the full path and file name to the EXE, COM, BAT, or CMD file you wish to run. To specify a document, use the browse button or Start menu emulator and select the document. The properly formatted command line including the associated application for the document will be automatically built.

NOTE: For easy navigation, use the provided Start button.

Run only if another instance is not running

Yes/No

No

No

SINGLEINSTANCE="YES"

If set to YES, specifies that the program specified on the Run parameter should not be run if another instance of it is already running on the current system. If another instance is running when this option is enabled, the step will be ignored and it will not generate an error. If set to NO (default), the specified program will run despite other running instances.

Initial Window State

Text (options)

No

Normal

WINDOWSTARTUP="minimized"

The state that the application's window should be set to at startup. The available options are:

  • Normal (Default): The application will start normally.

  • Maximized: The application will be requested to start maximized.

  • Minimized: The application will be requested to start minimized.

  • Hidden: The application will be requested to start hidden.

Startup Folder

Text

No

(Empty)

DEFAULTFOLDER=

"C:\Program Files\Network Automation\AutoMate 9\"

Certain applications require a startup folder. 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 Properties

Property

Type

Req'd

Default

Markup

Description

Do not wait

Yes/No

No

No

WAITFORINPUT="NO"

If set to YES, the step will not wait until the application is finished loading. Selecting this option could result in the task moving to the next line too early which would cause any interactive steps to be sent into nothing. This parameter is set to NO by default.

If the Wait until application completes parameter is set to YES then this parameter is ignored.

Wait until application is ready for input

Yes/No

No

Yes

WAITFORINPUT="NO"

If set to YES (default), the step will wait until the application is finished loading and is ready to receive input such as keystrokes or mouse clicks. Setting this parameter to NO could result in the task moving to the next line too early which would cause any interactive steps to be sent into nothing (because the application would not be loaded yet).

If the Wait until application completes parameter is set to YES then this parameter is ignored.

NOTE: DOS applications, batch files, and certain console applications may not function correctly with this parameter set to YES because such applications do not support standard Windows event messaging that enables this kind of integration. For these applications, you may 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 set to YES, the step should wait 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"

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 set to YES. Not all applications use return codes, so the functionality of this action may vary depending on the application.

Terminate process after

Yes/No

No

No

TERMINATEAFTERTIMEOUT="YES"

If set to YES, the running process will be terminated within the specified amount of time. This parameter is set to NO by default.

Data Properties

Property

Type

Req'd

Default

Markup

Description

Populate variable with process ID

Text

No

(Empty)

ROCESSIDVARIABLE="ID"

If enabled, specifies an already existing variable to be populated with the application's process ID.

Create and Populate Dataset

Text

No

(Empty)

RESULTDATASET="myDataset"

If enabled, specifies the name of a dataset to be created and populated with data from the window of the application that was run. More information about the dataset that this action creates can be found below under Notes.

Populate variable with window class

Text

No

(Empty)

WINDOWCLASSVARIABLE="myvar"

If enabled, specifies an already existing variable to be populated with the window class of the application that is launched. This parameter is available only if the Wait until application is ready for input parameter is set to YES.

Populate variable with window handle

Text

No

(Empty)

WINDOWHANDLEVARIABLE="handle"

If enabled, specifies an already existing variable to be populated with the window handle of the application that is launched. This parameter is available only if the Wait until application is ready for input parameter is set to YES.

Populate variable with window title

Text

No

(Empty)

WINDOWTITLEVARIABLE="title"

If enabled, specifies an already existing variable to be populated with the window title of the application that is launched. This parameter is available only if the Wait until application is ready for input parameter is set to YES.

Advanced Properties

Property

Type

Req'd

Default

Markup

Description

Run application as

Yes/No

No

No

DOS="YES"

Specifies whether a standard Windows application, document or console application is being launched. The available drop-down options are:

  • Standard Windows application

  • Document

  • Console application

Capture output and populate variable

Text

No

(Empty)

OUTPUTVARIABLE="theVariable"

If enabled, specifies an already existing variable to be populated with the console output. Valid only if Run application as is set to Console application.

NOTE: The Console output settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.

Capture output and write to file

 

Text

No

(Empty)

OUTPUTFILE="C:\Temp\filename.txt

If enabled, specifies a file to which the console output should be written. Valid only if Run application as is set to Console application.

NOTE: The Console output 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 set to YES, specifies that if the file being written to already exists, it will be overwritten. If set to NO (default) and the file already exists, the step will fail.

Description Properties

The Description tab allows you to customize the text description of any step as it appears in the Task Builder's Steps Pane.

More on setting custom step description

Error Causes Properties

The Error Causes tab allows you to select/omit specific errors that should cause a particular step to fail.

More on Error Causes properties

On Error Properties

The On Error tab allows you to determine what the task should do if a particular step encounters an error.

More about On Error properties

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 table below describes these fields (assuming the dataset assigned was named theDataset).

Name

Type

Return Value

theDataset.Title

Text

Returns the window title.

theDataset.Class

Text

Returns the window title class.

theDataset.Handle

Text

Returns the window handle.

theDataset.ProdcessID

Text

Returns the process ID.

theDataset.ReturnCode

Number

Returns the Return Code.

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by pressing F2.

More on variables
More on expressions

More on the expression builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

 

Description: Runs Adobe Photoshop.

 

<AMRUN FILE="&quot;C:\Program Files (x86)\Adobe\Adobe Photoshop CS3\Photoshop.exe&quot; " PROCESSIDVARIABLE="processID" WINDOWTITLEVARIABLE="theTitle" WINDOWSTARTUP="minimized" SINGLEINSTANCE="YES" RESULTDATASET="theDataset" />

 

↑ Top of Page