Activity

Description

Declaration

Examples

Browse for Folder

Displays a standard 'Browse for Folder' dialog box. The folder specified is stored in a variable for use in subsequent steps. Execution is paused while the user makes a selection. Commonly used to allow a user to manually select a folder to open during task execution.

<AMSHOWDIALOG ACTIVITY="folder" WINDOWTITLE="text" RESULTVARIABLE="text" DEFAULTFOLDER="text" ONCANCEL="text (options)" />

This example demonstrates use of the Browse for Folder activity (step 2) by saving the path and name of the folder selected by the user then displaying the text in a separate Message Box (step 3).

<AMVARIABLE NAME="theFolder"></AMVARIABLE>

<AMSHOWDIALOG ACTIVITY="folder" WINDOWTITLE="Please select a folder" RESULTVARIABLE="theFolder" DEFAULTFOLDER="C:\" />

<AMSHOWDIALOG WINDOWTITLE="FOLDER SELECTED" COUNTDOWNDELAY="20">The folder selected is %theFolder%.</AMSHOWDIALOG>

Input Box

Displays an input box allowing the user to enter a value. The value entered is saved to the variable specified. Execution is paused while the task waits for a value to be entered. Useful for asking a question that requires a text response at runtime. This action is similar to the Message Box action except this action allows the user to enter a text value in response to a question. The text value is populated into a variable.

<AMSHOWDIALOG ACTIVITY="input" DEFAULTVALUE="text" RESULTVARIABLE="text" WINDOWTITLE="text" XPOS="number" YPOS="number" ICON="text (options)" ONCANCEL="text (options)" COUNTDOWNDELAY="number" MASKINPUT="YES/NO">text</AMSHOWDIALOG>

Example 1 - This sample task demonstrates use of the Input Box activity (step 2) by saving the text entered in the input box that appears and then displaying the text in a separate Message activity (step 3).

<AMVARIABLE NAME="textEntered"></AMVARIABLE>

<AMSHOWDIALOG ACTIVITY="input" RESULTVARIABLE="textEntered" WINDOWTITLE="ENTER TEXT">Please enter some text here.</AMSHOWDIALOG>

<AMSHOWDIALOG WINDOWTITLE="TEXT ENTERED">The text that was entered: %textEntered%</AMSHOWDIALOG>

Example 2 - This example demonstrates the following:

1. Use of the Input Box activity to ask the user a question and retrieve the answer

2. Use of Custom BASIC Functions

3. Use of the IF action

4. Use of Expressions

5. Use of Message Box activity to display the answer.

<AMVARIABLE NAME="theanswer" DESCRIPTION=""></AMVARIABLE>

<AMSCRIPT>Function SquareNumber(thenum)

SquareNumber = thenum * thenum

End Function</AMSCRIPT>

<AMSHOWDIALOG ACTIVITY="input" RESULTVARIABLE="theanswer">What number would you like to square?</AMSHOWDIALOG>

<AMIF EXPRESSION="IsNumeric(theanswer) = true">

     <AMSHOWDIALOG>The number %theanswer% squared  is %SquareNumber(theanswer)%</AMSHOWDIALOG>

<AMELSE />

     <AMSHOWDIALOG>The text "%theanswer%" is not a valid number. Please re-run and enter a valid number.</AMSHOWDIALOG>

</AMIF>

Message Box

Displays a message box using the settings specified. A message box is useful when notification and/or user input is required in a task. Commonly used to provide informative feedback to the user during task execution.

<AMSHOWDIALOG WINDOWTITLE="text" BUTTONS="text (options)" ONFIRSTBUTTONCLICK="text (options)" ONFIRSTBUTTONCLICKTASK="text" ONSECONDBUTTONCLICK="text (options)" ONTHIRDBUTTONCLICK="text (options)" RESULTVARIABLE="text" COUNTDOWNDELAY="number" XPOS="number" YPOS="number" ICON="text (options)">text (message to display)</AMSHOWDIALOG>

Example Task 1 - This example demonstrates use of the Input Box activity (step 2) by saving the text entered in the input box that appears and then displaying the text in a separate Message Box (step 3).

Example 2 - This example opens a message box that displays the version of your AWE installation.

Example 3 - This example demonstrates the following:

1. Use of the Input Box activity to ask the user a question and retrieve the answer

2. Use of Custom BASIC Functions

3. Use of the IF action

4. Use of Expressions

5. Use of Message Box activity to display the answer.

Open File

Displays a standard Windows Explorer dialog box allowing the user to select a specific file. The file selected is stored in a variable for use in subsequent steps. Execution is paused while the user makes a selection. Commonly used to allow a user to manually select a file to open during task execution.

<AMSHOWDIALOG ACTIVITY="open" WINDOWTITLE="text" RESULTVARIABLE="text" FILTER="text" DEFAULTFOLDER="text" ONCANCEL="text (options)" />

This example demonstrates use of the Open File activity (step 2) by prompting the user to select a file to open. A separate Message Box appears in step 3 displaying the path and file name of the file selected.

<AMVARIABLE NAME="theFile"></AMVARIABLE>

<AMSHOWDIALOG ACTIVITY="open" WINDOWTITLE="Please select file to open" RESULTVARIABLE="theFile" DEFAULTFOLDER="C:\" />

<AMSHOWDIALOG WINDOWTITLE="SELECTED FILE" MODAL="NO">The file selected is %theFile%</AMSHOWDIALOG>

Save File

Displays a standard Windows 'Save As' dialog box allowing the user to save a specific file. The file name and location specified is stored in a variable for use in subsequent steps. Execution is paused while the user makes a selection. Commonly used to allow a user to manually save a file during task execution.

<AMSHOWDIALOG ACTIVITY="save" WINDOWTITLE="text" RESULTVARIABLE="text" FILTER="text" DEFAULTFOLDER="text" ONCANCEL="text (options)" />

Open "Save File As" dialog.  Populate the variable "theVar" with the selected filename.

<AMSHOWDIALOG ACTIVITY="save" WINDOWTITLE="Please select file to save" RESULTVARIABLE="theVar" DEFAULTFOLDER="C:\Temp" />

Selection Box

Displays an auto-generated multiple choice dialog box based the options you specify. Choice is useful when a multiple-choice selection is needed or the user must make a decision that will affect which subsequent actions should be executed by the task. The value associated with the item that the user selects is placed into a variable where it can be evaluated and acted on.

<AMSHOWDIALOG ACTIVITY="select" MESSAGETEXT="text" RESULTVARIABLE="text" ITEMS="text (caption1),text (caption2),text (caption3)" VALUES="text (value1),text (value2),text (value3)" INDEXSELECTED="1" WINDOWTITLE="text" ONCANCEL="continue" COUNTDOWNDELAY="number" />

Property

Type

Required

Default

Markup

Description

Array

Text

Yes if list items are gathered from an array

(Empty)

ARRAY="arrayName"

The name of the array that the list items should be gathered from.

NOTE: The first column of the array will be used as the caption.

This parameter is valid only if Array is selected from the Use items from parameter.

Bring dialog to front

Yes/No

No

Yes

WINDOWINFRONT="NO"

If set to YES (default value), specifies that the input box will appear in front of all other open windows.

Caption

Text

Yes if items derive from a list

(Empty)

ITEMS="FTP,HTTP,Backup"

Specifies a comma-delimited list of items that appear at runtime during execution of this action. There must be an equivalent number of captions to value items. Each caption must have a corresponding item in the Value parameter. This parameter is valid only if List is selected from the Item Source parameter.

Caption Column

Text

Yes if list items are gathered from a dataset

(Empty)

COLUMN="Drive"

Specifies the dataset column that should be used as the caption (list of items that appear at runtime during execution of this action). This parameter is valid only if Dataset is selected from the Use items from parameter.

Dataset

Text

Yes if list items are gathered from a dataset

(Empty)

DATASET="theDataset"

The name of the dataset that the list items should be gathered from. This parameter is valid only if Dataset is selected from the Item Source  parameter.

Default Value

Text

No

(Empty)

DEFAULTVALUE="Question"

The default text that should appear in the input box. This parameter is optional.  

Descriptive Text (will be displayed above the folder tree)

Text

No

(Empty)

TITLE="Select Folder"

The title that the dialog box should display (i.e. "Please Browse for the target folder").

Index selected

Number

Yes if list items are gathered from a dataset or array

(Empty)

INDEXSELECTED="3"

Specifies the index number(s) of the items that should be checked or selected by default. Depending on the option selected under the List Type parameter, the requirements for this parameter differ. In the case of a Dropdown or Options list type, one item must be selected. In the case of a List or Checkbox list type, no items or multiple items may be specified. To specify multiple options the numbers should be comma-delimited. This parameter is valid only if Dataset or Array is selected from the Item Source  parameter.

Item Source

Text (options)

No

List

ITEMS="item1, item2"

Specifies where the list items should derive from. Different parameters appear depending on which option is selected. The available options are:

• List: Allows the option to manually enter a list by clicking Add.

• Dataset: Allows the list to derive from an existing dataset.

• Array: Allows the list to derive from an existing array.

List Type

Text (options)

Yes

Dropdown

LISTTYPE="checkbox"

Specifies the manner by which the list will be displayed on the auto-generated form at runtime. This selection is relevant not only for aesthetics but will also affect the ability of the user to make a multiple choice selection (see below). The available options are:

• Dropdown: The items in the list will be placed into a drop-down box. (This option does not allow multiple selections.)

• Checkbox: The items in the list will be represented as a collection of checkboxes. (This option allows multiple selections.)

• Option: The items in the list will be represented as a collection of option buttons - also known as radio buttons. (This option does not allow multiple selections.)

• List: The items in the list will be represented as a list box. (This option allows multiple selections.)

Mask input

Yes/No

No

No

 MASKINPUT="YES"

If set to YES, for security purpose, specifies that the information entered in the input box will be masked by the number sign (i.e. ######). This parameter is set to NO by default.

Message to Display

Text

Yes

(Empty)

MESSAGETEXT="What's your answer to the question?"

The text message to be displayed in the input box during runtime. This is usually a question that the user should input an answer to.

Populate variable with return code

Text

Yes

(Empty)

RESULTVARIABLE="varname"

The name of an already created variable that should be populated with the folder selected by the user.

Selected index

Number

Yes if items derive from a list

(Empty)

SELECTED="3"

Specifies the index number of the item(s) that should be checked or selected by default. Depending on the option selected under the List Type parameter, the requirements for this parameter differ. In the case of a Dropdown or Options list type, one item must be selected. In the case of a List or Checkbox list type, no items or multiple items may be specified. To specify multiple options the numbers should be comma-delimited. This parameter is valid only if List is selected from the Item Source parameter.

Dialog title

Title of input box

Title of the message box

Text

No

(Empty)

WINDOWTITLE="QUESTION"

The title that the dialog box should display.

Use column as value

Text

Yes if list items are gathered from a dataset

(Empty)

COLUMNVALUE="Drive"

If enabled, indicates that the value of a specific dataset column should be used as the value. The default option is Return index as value, which returns the index (row number) as the value.  

Value

Text

Yes if items derive from a list

(Empty)

VALUES="FTP Upload,HTTP Put,Backup Files"

Specifies a comma-delimited list of values. They represent value(s) that will be returned by the item if selected at runtime by the user. There must be an equivalent number of values to caption items. Each value must have a corresponding item in the Caption parameter. This parameter is valid only if List is selected from the Item Source  parameter.

Property

Type

Required

Default

Markup

Description

Automatically select [the default button] after

Number/Options

No

Disabled

COUNTDOWNDELAY="1"

MEASURE="minutes"

The delay time for this action.

Buttons contained in the message box

Text (options)

No

Ok

BUTTONS="yes_no"

BUTTONS="ok_cancel"

The button or array of buttons that should be displayed on the message box. Different parameters appear depending on the option chosen. The available options are:

• OK (Default): The message box will contain an OK button only.

• OK, Cancel: The message box will contain an OK and CANCEL button.

• Abort, Retry, Ignore: The message box will contain Abort, Retry and Ignore buttons.

• Retry, Cancel: The message box will contain a RETRY and CANCEL button.

• Yes, No: The message box will contain a YES and NO button.

• Yes, No, Cancel: The message box will contain YES, NO, and CANCEL buttons.

Button selected by default

Number

No

0

DEFAULTBUTTON=2

The number of the button (from left to right) that should be focused by default. The number specified must be the same as or lower than the total number of buttons on the message box. For example, if Yes, No is selected from the Buttons contained in the message box parameter, first (1) specifies the Yes button and second (2) specifies the No button.

On Abort

On Cancel

On Ignore

On OK

On Retry

Text (options)

No

(Empty)

ONCANCEL="fail"

ONFIRSTBUTTONCLICK="stop"

ONSECONDBUTTONCLICK="stop"

ONTHIRDBUTTONCLICK="stop"

Specifies how this activity will react if the user clicks the button. The available options are:

• Continue: The task will continue to the next step.

• Stop: The task will stop. No error is generated.

• Fail: The task fail with an error.  

• Start Task - The specified task will start if the Cancel button is pressed by the user.

• Set Variable - The selected variable will be set to the specified value if the Cancel button is pressed by the user.

Pause task execution until a button is clicked

Yes/No

No

Yes

MODAL="NO"

Specifies whether task execution should pause until a button is clicked (i.e. "modal") or the task moves on to the next step immediately (i.e. "modeless").

Populate variable with return code

Text

No

Disabled

RESULTVARIABLE="varname"

If enabled, indicates the name of an already created variable that should be populated with the number of the button (from left to right) that has been clicked. This option is valid only if MODAL=YES.

Task to start

Text

No

(Empty)

ONFIRSTBUTTONCLICKTASK=

"c:\foldername\taskname.aml"

ONSECONDBUTTONCLICKTASK=

"c:\foldername\taskname.aml"

ONTHIRDBUTTONCLICKTASK=

"c:\foldername\taskname.aml"

The task that should be run when the first button is clicked. Click the Folder icon to navigate to the desired task (.aml) file. Valid only if the Start task parameter is selected. Available when Start a task is selected in On Cancel box.

Variable name

Variable value

Text

No

(Empty)

ONFIRSTBUTTONCLICK="set_variable" ONFIRSTBUTTONCLICKVARNAME="USER_GROUPS" ONFIRSTBUTTONCLICKVARVALUE="%MESSAGE_ID%"

Available when Set a variable is selected in On [button] box.

Property

Type

Required

Default

Markup

Description

Allow multiple selections

Yes/No

No

No

MULTIPLE="YES"

Specifies that multiple selections are allowed. This option is only valid if the List Type parameter is set to Checkbox or List as only those controls support multiple-selection.

Capture mouse position

Dialog title icon

Text

No

(Empty)

ICON="exclamation"

If enabled, specifies the icon that should be displayed on the input box next to the title. This helps to determine what type of message is being displayed. The available options are:

• None:

• Exclamation point: An exclamation point icon is displayed.

• Information: The standard Windows information icon is displayed.

• Question mark: The standard Windows question icon is displayed.

• Stop sign: The standard Windows stop icon is displayed.

Filter

Text (options)

No

All files (*.*)|*.*

FILTER="All files (*.*)|*.*"

The file filters for the dialog box that appears. Filters represent the masks that are listed in the File Type drop-down. For example, to include only text files, enter *.txt.

Force selection

Yes/No

No

Yes

FORCESELECT="NO"

Specifies that the user must make a valid selection before continuing. This option is only valid if the List Type parameter is set to Checkbox or List. Other list types automatically force selection.

Initial Folder

Text

No

(Empty)

DEFAULTFOLDER="c:\foldername\"

The starting folder that the user sees when the dialog box appears.

On Cancel

Text (options)

No

(Empty)

ONCANCEL="fail"

Specifies how this activity will react if the user clicks Cancel. The available options are:

• Continue: The task will continue to the next step.

• Stop: The task will stop. No error is generated.

• Fail: The task fail with an error.  

Position

Text (options)

No

Centered on screen

POSITION="upper_left"

The button or array of buttons that should be displayed on the input box. The available options are:

• Upper left corner of the screen: The message box will be displayed at the upper left of the screen.

• Centered on the screen (default): The message box will be displayed at the center of the screen (default).

• Lower left corner of the screen: The message box will be displayed at the lower left of the screen.

• Upper right corner of the screen: The message box will be displayed at the upper right of the screen.

• Lower right corner of the screen: The message box will be displayed at the lower right of the screen.

• Customized: The message box will be displayed at the pixel coordinates specified at X Pos and Y Pos parameters.

X Pos

Number

No

(Empty)

XPOS="55"

The X (horizontal) coordinates of the position that the upper left corner of the input box should be displayed on the screen. Move the mouse cursor to the desired location on the screen and press INSERT to capture the position. This option is available only if Custom is selected from the Position parameter.

Y Pos

Number

No

(Empty)

YPOS="55"

The Y (vertical) coordinates of the position that the upper left corner of the input box should be displayed on the screen. Move the cursor to the desired location on the screen and press INSERT to capture the position. This option is available only if Custom is selected from the Position parameter.