PromptSet Designer

Define interactive input forms on the PromptSet Designer page of PromptSet objects. Configure prompt sets with different user controls to let your users select or enter data. The values the user selects are passed to executable objects. Each element you include in the form also defines a variable that you can use in scripts. You can configure prompts to be entered manually or resolved automatically from default values of dynamic variables.

Creating and Editing Prompt Sets

1. Add a PromptSet object (PRPT).
2. Switch to the PromptSet Designer page of the object.
3. Drag and drop the desired prompt set elements from the right side of the screen into the center.
4. Select an element that you have dragged into the prompt set to configure the settings of the element.
5. Drag and drop elements within the form to change their order. Prompts are called in the order in which they appear here.
6. To remove an element, select the element and click its Remove icon or the Delete button in the toolbar.
7. Save the object.

You can now use the prompt set on the Prompts page under Variables & Prompts page of an executable object.

To Preview a Prompt Set

1. Add and sort the desired prompt set elements.
2. Save the prompt set.
3. Click the Preview button in the toolbar.

The form is displayed in a pop-up dialog, with the elements you configured.

Note: The preview does not resolve variables used to define default values.

Available Prompts

The following prompt elements are available:

• Header/Text
  Displays a text in the form
  Use this element for headers, as a section headline to group other elements, or to display other text to the user. Unlike other elements, this element does not pass values. The text cannot be edited in the form.
• Number
  Lets the user specify a number (integer)
• Text Field
  Lets the user enter a text string , in a single or multiple lines
• Combobox
  Lets the user select an entry from a drop-down list
• Radio Button
  Lets the user select a single option
• Checkbox
  Lets the user select one or more options by checking boxes
• Time/Date
  Lets the user select a time and date

Common Prompt Settings

The following settings are available for all prompt set elements, except the Header/Text prompt, which has only Label, Variable Name, Tooltip and Custom Field:

• Label

  Descriptive text displayed in the form. The field shows a default value when you add the element, which you can edit.

• Variable Name

  Defines a PromptSet variable that you can use in scripts. The variable is created every time the executable object runs. The field shows a default variable name when you add the element. You can edit this name, but variable name restrictions apply.

  Note: If the data reference is an EXEC variable object, the name of the PromptSet variable must match the script variable set as the parameter name in the EXEC variable object.

• Tooltip

  Text displayed when the user hovers over the field.

• Set Focus

  Puts the prompt into focus when the user views the form. If you set this option for multiple prompts in the form, the focus is on the last prompt with this option selected.

• Read-only

  Default value is displayed and cannot be edited by the user.

• Quotes

  Character that is appended at the beginning and end of the value.

• Custom Field

  Text that does not affect the functionality of the prompt set element, and is not displayed in the form. Use this field for notes or to store information about the prompt that can be read from the database.

For more information, see Script Variables.

Data Reference

The Data Reference field lets you select a Variable object that acts as a reference variable for the prompt. With the exception of the Header/Text prompt, all prompts allow you to specify a data reference. The data reference Variable object determines the allowed data type and values supplied in the prompt.

The column from which values are retrieved depend on the type of data reference VARA object specified: 

• Static variables: first value column
• Dynamic variables: RESULT column

Notes:

• If you use a dynamic VARA object (except FILELIST VARA) as the data reference, the number of entries returned is limited by the value of SQLVAR_MAX_ROWS in the UC_SYSTEM_SETTINGS variable. The default value is 200 lines.
• If you use an EXEC VARA object as the data reference, the name of the PromptSet variable (Variable Name) must match the script variable set as the parameter name in the EXEC variable object.

Important!

• Do not edit data reference VARA objects when executing objects with PromptSets, or while those objects are starting. At this time, the prompt interface has already been generated, so editing Variable objects will cause problems.
• If the values specified for a PromptSet element do not comply with the reference values, the prompt cannot be sent after object activation.

For more information, see:

• SQLVAR_MAX_ROWS
• UC_SYSTEM_SETTINGS - Systemwide Settings
• EXEC VARA Objects
• Activating Prompt Sets

Required Data Types

The Data Reference drop-down menu only includes VARA objects that have a suitable data type for the prompt set element. Use the appropriate prompt set element for the particular reference data type. For example, use the Time/Date prompt set element for date data types. Prompts can have the following data types:

• Number: number

• Text Field: text

• Combobox

  • Text
  • Number
  • Time
  • Date
  • Time stamp

• Radio Button

  • Text
  • Number

• Checkbox

  • Text
  • Number

• Time/Date

  The required data type depends on the Type setting of the prompt.

  • Date
  • Date and time (timestamp)
  • Time

Default Data Reference Variables

The system client (0) supplies default data references for the following prompts:

• Number: UC_DATATYPE_NUMERIC

• Text Field: UC_DATATYPE_STRING

• Time/Date:

  • Date: UC_DATATYPE_DATE
  • Date and Time: UC_DATATYPE_TIMESTAMP
  • Time: UC_DATATYPE_TIME

Key and XPath/XQuery Settings

(Text Field, Combobox, Radio Button and Checkbox prompts only) If you select an XML variable in the Data Reference field, the following additional settings are available:

• Key
  Key from the Key list of the XML variable selected in the Data Reference field
  
• XPath/XQuery
  XPath or XQuery expression of the XML variable selected in the key.

Note: Both fields allow variables.

Example

Assume you have the following XML in the key:

<server>

    <name>MyUNIXServer</name>

    <ip>19.16.8.1.200</ip>

</server>

Follow these steps to specify the IP address:

1. Select the XML variable in the Data Reference field.
2. Select the appropriate key for the XML variable in the Key field.
3. Enter server/ip.

Default Value/Default Selection

The default value is displayed when the prompt set is called. If the user does not select a different value, or if the field is set as read-only, this value is passed. With the exception of the Header/Text prompt, all prompts allow you to specify a default value.

The following restrictions apply to specific prompt types:

• The length of the default text for prompt set elements is not limited, unless a maximum length is specified in the definition of the Variable set as the prompt's data reference.
• Trailing blanks are truncated.
• Time/Date prompt set elements cannot be stored without default values. If you want the current date and time to be displayed as default values when the prompt opens, use the predefined variables &$PHYS_DATE_format# and &$PHYS_TIME_format#.

Defining a Default Value

Select an option to define the default value:

• Set Manually

  Depending on the type of prompt, enter the default value by either picking the value from the control, or typing the value in the title bar of the prompt element. Use this option if you want a static default value for the prompt.
  

• Set by Variable

  Type the variable name into the field in the title bar of the prompt element, or click the $x button to open the Insert Variable dialog, where you can select a predefined variable. Use this option if you want the current value of the variable to be retrieved when the prompt set is called. The variable returns values depending on the object that the prompt set is assigned to, and not on the PromptSet object itself.

Notes:

• Manual and variable options both allow text and variables, except for Number prompts, which only allow numbers.
• The system does not check if the data type of the specified default value corresponds to the data reference Variable. The only exception is the Text Field prompt, where the system performs a reference check if the data reference Variable object has text as its data type.

Important! You can save a prompt set even if it includes prompts whose default values use the wrong data type or violate limitations specified in the settings of the prompt. The resulting error will occur when you attempt to save the object where you assign the PromptSet.

For more information, see Inserting Variables/VARA Objects in Objects and Scripts.

Overriding Prompt Values

The prompt value can be overridden in multiple places. The order of precedence of the prompt value used for activation is:

1. The default value (if one is set here).

2. The prompt on the Prompt Sets page under Variables & Prompts in the object definition of an executable object overrides the default value.

3. An override of the activation of the instance of a Workflow or other executable object when it is run:

   • Manually with an Execute command.
   • Via a Schedule object.
   • Via a ACTIVATE_UC_OBJECT script function with the PASS_VALUES parameter using :PUT_READ_BUFFER, :PUT_PROMPT_BUFFER.

   Note: The read buffer variable requires the same name as the PromptSet variable (Variable Name). A Request dialog for prompts is not displayed for tasks that are activated through Workflow, Schedule, or Script objects.

Note: You can also define Workflow-specific prompt values. For more information, see .

For more information, see:

• ACTIVATE_UC_OBJECT
• :PUT_READ_BUFFER, :PUT_PROMPT_BUFFER
• PromptSets Tab (for Workflows)

Other Prompt-specific Settings

Some settings are only available for particular types of prompts.

Dynamic Reload

(Combobox Prompts)

Depending on the data reference Variable, this setting does one of the following:

• If the data reference value is a dynamic Variable or a STATIC VARA object, this setting resolves the list of values for the combobox whenever the prompt is called. The list content is directly retrieved from the data source. This behavior affects the preview of the PromptSet object, the Variable & Prompts > Variables page for executable objects and the Request dialog at runtime.
• If a variable defined in the current prompt set is also specified in the object definition of the data reference Variable object of the Combobox prompt, then you can use the value of the earlier prompt in allowable fields of the data reference Variable. You must enter the Variable Name of the earlier prompt in one of the following object definition fields in the data reference Variable object definition of the current prompt.

Note: To use PromptSet variables in Variable objects, ensure that the value of the VAR_SECURITY_LEVEL in the UC_SYSTEM_SETTINGS system variable is set to 3. This limitation does not apply to the SQL statements of VARA objects that use the sources SQL SECURE and SQLI SECURE.

For more information, see variable settings and parameters in the following topics:

• BACKEND VARA Objects
• EXEC VARA Objects
• FILELIST VARA Objects
• SEC_SQLI VARA Objects: see In the Variable Settings section, specify the following:
• SEC_SQL VARA Objects: Connection, Login and SQL Statement (SEC_SQL VARA Objects)
• SQLI VARA Objects: see In the Variable Settings section, specify the following:
• SQL VARA Objects: Connection, Login and SQL Statement (SQL VARA Objects)
• VAR_SECURITY_LEVEL
• UC_SYSTEM_SETTINGS - Systemwide Settings

Mandatory

(Checkbox and Text Field Prompts)

Requires the user to enter or select data in the prompt

Minimum and Maximum

(Number and Time/Date Prompts)

Define the minimum and maximum allowed values.

Note: These limitations are already checked when you store the object to which the PromptSet object has been assigned. You cannot store objects whose PromptSet values defined on the Variables & Prompts page are invalid because of the PromptSet properties.

Multi-Select and Separator

(Checkbox and Text Field Prompts)

Use the following settings to allow users to select multiple values:

• Multi-Select
  Allows the user to select multiple values
• Separator
  (Only available if you activate the Multi-Select option) Character that separates individual values in multiple selections
  (Checkbox prompts only) No separator is required if you select the Array option.

Tip: (Text Field prompts only) Activate the Input Assistant option to let users easily select multiple values.

On Change Reset

(Text Field, Combo box and Check box Prompts)

Automatically unsets the value of other Text Field, Combo box, and/or Check box prompts, including default values, in this prompt set when a user selects a value for this prompt

Check boxes are displayed for each Text Field, Combo box and Checkbox in the current prompt set. Select the checkboxes of the fields which you want to reset if a user enters a value in this prompt.

Text Field Settings

The following additional settings are available for Text Field prompts only:

• Multi-line

  Allows the text field to display multiple lines. By default, the text field is a single line.

• Maximum Length

  Limits the allowed number of characters for the prompt value. This check is made when you save the PromptSet object or an executable object you assign it to.

• Input Assistant

  Includes a "..." button next to the text field that opens a dialog window where the user can select values. Use this option in the following situations:

  • You want to select values from the data reference Variable
  • The data reference is a FILELIST VARA object
  • Multi-select is enabled

  Note: When your data reference is a STATIC VARA object and you select a row from the dialog window, the value from the Value 1 column is selected.

• Upper Case

  Automatically converts lower case letters entered in the text field to upper case

• Show as Password

  Encrypts the value of the text field and hides characters entered in the text field by displaying them as asterisks (*).

  Notes:

  • The text is no longer shown in plain text in reports.
  • Use the Job Messenger's CMD parameter to run commands of Windows or UNIX jobs that include encrypted passwords.
    

• Regular Expression

  Creates rules for allowed text field contents by using a regular expression. You will not be able to save the prompt set or specify a value for it in an executable object if the value does not meet the regular expression rules.

  Examples:

  Only allow two-digit numbers: [0-9]{2}

  Allow all characters except for "x": [^x]

  One of the characters "a", "b" or "c": [abc]

  All uppercase and lowercase letters, numbers and the comma character can be used as often as required: [A-Za-z0-9,]*

  Allowed characters #, , ,$, @, A-Z, 0-9, and maximum length 10:  [A-Z0-9_#@$,]{0,10}

  Notes:

  • Leading and trailing blanks in regular expressions are not allowed and will not be ignored.
  • You can run an executable object with a prompt that has regular expression rules if the prompt has a null value. To ensure that the prompt has a value, check the Mandatory checkbox.
    

  Tip: Include rules in the tooltip of the prompt in order to assist users.

Time and Date Settings

In addition to the common settings, the following settings are available for Time/Date prompts:

• Type
  Select one of the following types:
  • Date
  • Date and Time
  • Time
  Notes:
  • These options have different default data references.
  • The Calendar, Calendar Event and Output format settings of the prompt determine date and time specifications.
• Calendar
  Select a Calendar object from which to pick a date
• Calendar Event
  Pick a calendar event from the selected calendar
• Output format
  Select a date format

Available formats for Date types:

• DD-MON-YYYY
• DD-MON-RR
• MM-DD-YYYY
• YYYYMMDD
• MMDDRR
• DDMMRR
• MM-DD-RR
• MM/DD/RR
• YYMMDD
• YY.MM.DD
• YY-MM-DD
• YYYYMMDD
• YYYY.MM.DD
• YYYY-MM-DD
• DDMMYY
• DD.MM.YY
• DD-MM-YY
• DDMMYYYY
• DD.MM.YYYY
• DD-MM-YYYY
• MMDDYY
• MMDDYYYY
• MM/DD/YY
• MM/DD/YYYY

Available formats for Date and Time types: 

• YYYYMMDDHH24MISS
• YYYY-MM-DD HH:MM:SS

See also:

• PromptSets (PRPT)
• Activating Prompt Sets
• Prompt Sets Page