Dialog - Selection
Declaration
<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" />
Description
Displays an auto-generated multiple choice dialog 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.
Practical usage
Similar to the Dialog - Input activity except this action allows the user to select a value in response to a question. The text value is populated into a variable which can be used later in the task.
Parameters
General
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
Dialog Title | Text | No | (Empty) | WINDOWTITLE="the_title" | The text that should appear on the title bar of this dialog. |
Populate variable with result | Text | Yes | (Empty) | RESULTVARIABLE="varname" | Specifies the name of an already created variable that should be populated with the value parameter of the item selected. If the user has selected multiple items the values are returned as a comma-delimited list. |
Message to display | Text | No | (Empty) | MESSAGETEXT="The message" | The text to be displayed in the selection dialog. Usually this is a question that the user should select the answer to. |
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:
|
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:
|
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. |
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 values 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. |
Selected | Number | Yes if items derive from a list | (Empty) | SELECTED="3" | Specifies the index number 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 List is selected from the Item Source 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. |
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. |
Index selected | Number | Yes if list items are gathered from a dataset or array | (Empty) | INDEXSELECTED="3" | Specifies the index numbers 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. |
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. |
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. This parameter is valid only if Array
is selected from the Use items
from parameter. NOTE: The first column of the array will be used
as the caption. |
Bring message to front of all other windows | Yes/No | No | Yes | WINDOWINFRONT="NO" | If selected (default value), the message window will appear in front of all other windows during execution of this step. |
Buttons
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
On Cancel | Text (options) | No | Stop | VALUEONCANCEL="cancelled" | Specifies the value that should
be returned into the variable if the user presses the Cancel
button. The available options are:
|
Automatically press the OK button after | Number | No | Disabled |
|
The delay time for this activity. |
Measure | Text (options) | No | Disabled | MEASURE="hour" | The numeric measure to use when |
Advanced
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
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. |
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. |
Automatically press the OK button after | Number/Options | No | Disabled |
|
If enabled, indicates that the OK
button will be automatically pressed after the elapsed time specified.
If this option is disabled, the choice dialog is displayed
indefinitely. Measures include:
|
Examples
- 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.
Example 1
This sample task shows how to use the Selection activity action and make decisions based on the answer.
<AMVARIABLE NAME="FoodofChoice" VALUE="" />
<AMSHOWDIALOG ACTIVITY="select" MESSAGETEXT="What would you like to eat?" RESULTVARIABLE="FoodofChoice" LISTTYPE="option" ITEMS="Hamburger,Pizza,Chicken" VALUES="1,2,3" INDEXSELECTED="2" WINDOWTITLE="What's for lunch?" />
<AMIF EXPRESSION="%FoodofChoice% = "1""><AMSHOWDIALOG MESSAGE="You chose hamburger." /></AMIF>
<AMSHOWDIALOG MESSAGE="You chose hamburger." />
<AMIF ACTIVITY="end" />
<AMIF EXPRESSION="%FoodofChoice% = "2""><AMSHOWDIALOG MESSAGE="You chose pizza." /></AMIF>
<AMSHOWDIALOG MESSAGE="You chose pizza." />
<AMIF ACTIVITY="end" />
<AMIF EXPRESSION="%FoodofChoice% = "3""><AMSHOWDIALOG MESSAGE="You chose chicken." /></AMIF>
<AMSHOWDIALOG MESSAGE="You chose chicken." />
<AMIF ACTIVITY="end" />
Example 2
This sample task displays how variables can be used interactively. A selection dialog appears allowing the user to select one or more list items. Thereafter, a message box displays all of the items selected.
<AMVARIABLE NAME="var1">First Name</AMVARIABLE>
<AMVARIABLE NAME="var2">Last Name</AMVARIABLE>
<AMVARIABLE NAME="var3">Address</AMVARIABLE>
<AMVARIABLE NAME="var4">Phone Number</AMVARIABLE>
<AMVARIABLE NAME="theVars" />
<AMSHOWDIALOG ACTIVITY="select" MESSAGETEXT="Please select one or more items below." RESULTVARIABLE="theVars" LISTTYPE="checkbox" ITEMS="%var1%,%var2%,%var3%,%var4%" VALUES="First Name,Last Name,Address ,Phone" WINDOWTITLE="Sample
Item Selection Task " ONCANCEL="stop" FORCESELECT="NO" MULTIPLE="YES" />
<AMSHOWDIALOG WINDOWTITLE="Selected Items" BUTTONS="ok_cancel" ONSECONDBUTTONCLICK="stop">You selected the following items:%theVars%</AMSHOWDIALOG>