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

Related Topics   

Overview

Displays an auto-generated multiple choice dialog based the specified options. Choice is useful when a multiple-choice selection is needed or the user must make a decision that affects which subsequent actions are 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 of the title bar.
Populate variable with result Text Yes (Empty) RESULTVARIABLE="varname" Specifies the name of an existing variable populated with the value parameter of the item selected. If the user selects multiple items, the values are returned as a comma-delimited list.
Message to display Text No (Empty) MESSAGETEXT="The message" The text of the selection dialog. Usually this is a question that the user answers.
List Type Text (options) Yes Dropdown LISTTYPE="checkbox" Specifies how the list is displayed on the auto-generated form at runtime. This selection is relevant not only for aesthetics but also affects the ability of the user to make a multiple choice selection (see below). The available options are:
  • Dropdown - The items in the list are placed into a drop-down box. This option does not allow multiple selections.
  • Checkbox - The items in the list are represented as a collection of check boxes. This option allows multiple selections.
  • Option - The items in the list are 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 are represented as a list box. This option allows multiple selections.
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 Automate Desktop dataset.
  • Array - Allows the list to derive from an existing array.
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 returned by the item if selected at runtime. 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 selected by default. Depending on the option selected under the List Type parameter, the requirements for this parameter differ. For Dropdown or Options list types, one item must be selected. For List or Checkbox list types, no items or multiple items can 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 are 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 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 selected by default. Depending on the option selected under the List Type parameter, the requirements for this parameter differ. For Dropdown or Options list types, one item must be selected. For List or Checkbox list types, no items or multiple items can 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 is 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 are gathered from. This parameter is valid only if Array is selected from the Use items from parameter.
NOTE: The first column of the array is used as the caption.
Bring message to front of all other windows Yes/No No Yes WINDOWINFRONT="NO" If selected (default), the message window appears 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 returned into the variable if the user clicks Cancel. The available options are:
  • Continue - The task continues  if you click Cancel.
  • Stop (default) - Stops the task  if you click Cancel.
  • Fail - The step fails if you click Cancel.
  • Start Task - Starts the specified task if you click Cancel.
  • Set Variable - The selected variable is set to the specified value  if you click Cancel.
Automatically press the OK button after Number No Disabled
  • COUNTDOWNDELAY="1"
  • MEASURE="minutes"
 The delay time for this activity.
Measure Text (options) No Disabled MEASURE="hour" The numeric measure.

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
  • COUNTDOWNDELAY="1"
  • MEASURE="minutes"
 If enabled, indicates that the OK button is automatically pressed after the specified elapsed time. If this option is disabled, the choice dialog is displayed indefinitely. Measures include:
  • Milliseconds
  • Seconds (Default)
  • Minutes
  • Hours

Description

Error Causes

On Error

Examples

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.

Example 1

The following sample task shows how to use the Selection activity action and make decisions based on the answer:

Copy 
<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% = &quot;1&quot;"><AMSHOWDIALOG MESSAGE="You chose hamburger." /></AMIF>
<AMSHOWDIALOG MESSAGE="You chose hamburger." />
<AMIF ACTIVITY="end" />
<AMIF EXPRESSION="%FoodofChoice% = &quot;2&quot;"><AMSHOWDIALOG MESSAGE="You chose pizza." /></AMIF>
<AMSHOWDIALOG MESSAGE="You chose pizza." />
<AMIF ACTIVITY="end" />
<AMIF EXPRESSION="%FoodofChoice% = &quot;3&quot;"><AMSHOWDIALOG MESSAGE="You chose chicken." /></AMIF>
<AMSHOWDIALOG MESSAGE="You chose chicken." />
<AMIF ACTIVITY="end" />

Example 2

The following 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.

Copy 
<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>