Dialog - Input

Declaration

<AMSHOWDIALOG ACTIVITY="input" MESSAGE="text" DEFAULTVALUE="text" RESULTVARIABLE="text" WINDOWTITLE="text" MAXLENGTH="number" POSITION="text (options)" XPOS="number" YPOS="number" ICON="text (options)" DEFAULTBUTTON="number (options)" ONCANCEL="text (options)" ONCANCELTASK="text" ONCANCELVARNAME="text" ONCANCELVARVALUE="text" COUNTDOWNDELAY="text" MEASURE="text (options)" MASKINPUT="YES/NO" />

Related Topics   

Overview

Displays an input dialog, allowing the user to enter a specific text value during runtime. The value is saved in the specified variable. Execution is paused while the task waits for a value to be entered. A default value can be specified in case no value is entered.

Practical usage

Useful for asking a question that requires a text response at runtime. Can be used to make decisions during task execution. For example, if value 1 is entered, continue to the next step; if value 2 is entered, end the task.

Parameters

General

Property Type Required Default Markup Description
Message to display Text Yes (Empty) MESSAGETEXT="What's your answer to the question?" The text message to display in the input box during runtime. This is usually a question that the user inputs an answer to.
Default value Text No (Empty) DEFAULTVALUE="theValue" The default text value that appears in the input box. Setting a default value (when possible) allows task execution to continue in case no user interaction occurs. This parameter is optional.  
Maximum length of string Number No Disabled MAXLENGTH="30" If enabled, specifies the maximum characters the user can enter in the input box. This prevents users from entering invalid data (such as entering more than 5 digits in a zip code field).
Populate variable with value entered Text No (Empty) RESULTVARIABLE="varname" The name of an existing variable to be populated with the text that the user entered as a response to the message.
Mask input Yes/No No No MASKINPUT="YES" If selected, allows the text being entered in the input box to be masked in real-time (for example, ######). This is useful if the user is entering a password or other sensitive data. This parameter is disabled by default.
Title of message box Text No (Empty) WINDOWTITLE="QUESTION" The title that appears in the title bar of the input box.
Bring dialog to front Yes/No No Yes WINDOWINFRONT="NO" If selected, specifies that the input box appears in front of all other open windows. This parameter is selected by default.

Buttons

Property Type Required Default Markup Description
Button selected by default Number No 0
  • DEFAULTBUTTON="0"
  • DEFAULTBUTTON="1"
 The number associated with the button that is automatically selected if no user interaction is applied within the time limit specified in the Automatically select the default button after parameter (below). The OK button correlates with 0 and the Cancel button correlates with 1. Setting a default button allows task execution to continue in case no user interaction occurs. The default value is 0.
On cancel Text (Options) No Stop
  • ONCANCEL="continue"
  • ONCANCEL="stop"
  • ONCANCEL="fail"
  • ONCANCEL="start_task"
  • ONCANCEL="set_variable"
 Specifies how this activity should react if you click Cancel . The available options are:
  • Continue - The task continues to the next step.
  • Stop (Default) - Stops the task. No error is generated.
  • Fail - The task fails with an error.  
  • Start a task - Starts another task.
  • Set a variable - The specified variable is set to a particular value.
Task to start Text Yes, if On cancel is set to Start a task (Empty) ONCANCELTASK="task_name" The path and file name of the Automate Desktop task (.aml) file to start if you click Cancel. Click the folder icon to navigate to the desired task file or enter the path and file name manually in the text box. This parameter is available only if the On cancel parameter is set to Start a task.
Variable name Text Yes, if On cancel is set to Set variable (Empty) ONCANCELVARNAME="var1" The name of the variable to set. This parameter is available only if the On cancel parameter is set to Set a variable.
Variable value Text Yes, if On cancel is set to Set variable (Empty) ONCANCELVARVALUE="value" The value of the variable. This parameter is available only if the On cancel parameter is set to Set a variable.
Automatically select the default button after Number No Disabled COUNTDOWNDELAY="10" If enabled, specifies the amount (numeric value) of time that elapses before the default button is selected as specified in the Button selected by default parameter. If this parameter is disabled, the input box is displayed indefinitely. This parameter is disabled by default.
Measure Text (Options) No Seconds
  • MEASURE="milliseconds"
  • MEASURE="seconds"
  • MEASURE="minutes"
  • MEASURE="hours"
 The time measurement to associate with the value entered in the Automatically select the default button after parameter. The available options are:
  • Milliseconds - Time measurement is set to milliseconds.
  • Seconds (Default) - Time measurement is set to seconds.
  • Minutes  - Time measurement is set to minutes.
  • Hours  - Time measurement is set to hours.
Populate variable with value entered Text No (Empty) RESULTVARIABLE="varname" The name of an existing variable to be populated with the text that the user entered as a response to the message.
Mask input Yes/No No No MASKINPUT="YES" If selected, allows the text being entered in the input box to be masked in real-time. This is useful when the user is entering a password or other sensitive data.
Title of message box Text No (Empty) WINDOWTITLE="QUESTION" The title that appears in the title bar of the input box.
Bring dialog to front Yes/No No Yes WINDOWINFRONT="NO" If selected, specifies that the input box appears in front of all other open windows. This parameter is selected by default.

Advanced

Property Type Required Default Markup Description
Position Text (Options) No Center of screen
  • POSITION="center"
  • POSITION="upper_left"
  • POSITION="lower_left"
  • POSITION="upper_right"
  • POSITION="lower_left"
  • POSITION="custom"
 The screen position in which to display the input dialog. The available options are:
  • Center of screen (Default) - The input dialog is displayed at the center of the screen.
  • Upper left corner of screen - The input dialog is displayed at the upper left of the screen.
  • Lower left corner of screen - The input dialog is displayed at the lower left of the screen.
  • Upper right corner of screen - The input dialog is displayed at the upper right of the screen.
  • Lower right corner of screen - The input dialog is displayed at the lower right of the screen.
  • Custom location - The input dialog is displayed at the specified X,Y coordinates.
Window coordinates (X) Number Yes, if Position is set to Custom location (Empty) XPOS="55" The X (horizontal) coordinates of the position that the upper left corner of the input dialog is displayed on the screen. To capture X coordinates using your mouse, enable the Capture mouse position (press Space to capture) option, move the mouse cursor to the desired location on the screen and press Space on your keyboard to capture the position. This parameter is available only if the Position parameter is set to Custom location.
Window coordinates (Y) Number Yes, if Position is set to Custom location (Empty) YPOS="55" The Y (vertical) coordinates of the position that the upper left corner of the input box are displayed on the screen. To capture Y coordinates using your mouse, select the Capture mouse position (press Space to capture) option, move the mouse cursor to the desired location on the screen and press Space on your keyboard to capture the position. This parameter is available only if the Position parameter is set to Custom location.
Dialog title icon Text(Options) No (Empty)
  • ICON="none"
  • ICON="information"
  • ICON="exclamation"
  • ICON="question"
  • ICON="stop"
 Specifies the icon displayed next to the title. This helps to determine what type of message is being displayed. The available options are:
  • None (Default) - No icon is displayed.
  • Information - An information icon is displayed.
  • Exclamation point - An exclamation point icon is displayed.
  • Question - A question mark icon is displayed.
  • Stop - A stop sign icon is displayed.

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 saves the text entered in an input box to a variable and then displays it in a message box:

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

The following sample task demonstrates use of the Input Dialog and Message Dialog, and demonstrates use of variables, BASIC Script, IF/End if activities and expressions.

Copy 
<AMVARIABLE NAME="theanswer" DESCRIPTION="" VALUE="" />
<AMSCRIPT>Function SquareNumber(thenum)SquareNumber = thenum * thenumEnd Function</AMSCRIPT>
<AMSHOWDIALOG ACTIVITY="input" RESULTVARIABLE="theanswer" MESSAGE="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>
<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 ACTIVITY="end" />