Retrieve Values

The Retrieve Values attribute can be used to dynamically retrieve valid values for a property at run time. The attribute requires an action descriptor to be referenced, which must contain a tool that returns a list of values. A file descriptor must be used to model the tool's output.

The Retrieve Values action can only be executed in a modeled input dialog. See Open Modeled Dialog for more information.

The manner in which the values for the field in the dialog are retrieved is determined by the Mode attribute of the corresponding property. The Mode values are:

Manual

• A Retrieve button is displayed next to the editable input field. When the retrieve button is clicked the associated action is executed and the input field is filled with the returned values.

  The label of the Retrieve button can be customized using the attribute Retrieve Button Label or the specific attribute defined under Application Options.

• If the retrieve action returns labels, they are only temporarily visible in the retrieved list. The dialog field will only display and accept the actual values.
• This mode is intended to be used for potentially long running retrieve actions, or if dialog field values are directly entered without retrieving valid values.

On Demand

• The retrieve action is executed as soon as a dialog field for this property is selected in a modeled dialog.
• Intended to be used for potentially short-running retrieve actions, or if retrieving values is typically required in order to enter or select a value.

If several tool descriptors of the retrieve action return file descriptors then the last descriptor is used by AWM.

The context of the retrieve action contains all the properties from the main context plus all values from the current dialog. You can use the dialog fields as input parameters for the retrieve action, as illustrated in the following figure:

Additionally, you can return labels for the retrieved values. The selection list in the dialog will then display only the labels, while selecting an item will put the value into the input field.

You cannot use a property of the type Text Array to support the Retrieve Values action.

If the retrieve action returns just one value, then the value is directly filled in the editable field and the selection list is not used. The retrieve action can be used for dialog fields where the user should enter a file or folder.

There are two different ways you can model a Retrieve Values action depending on the Values From attribute in the Retrieve All Values category of a property:

1. Values From = Matching Property

   Micro Focus recommends that you model your retrieve values action using this method. By default, AWM expects the values to be returned in a structured file descriptor which contains the relevant property, that is, the values are derived from the property in the file descriptor which id matches the id of the property to be populated. In this case, there is no need to specify a Label Property or Value Property.

   If values or labels should be derived from other properties than the concerning property, the property attributes Value Property and Label Property can be set to specify which properties should be used to provide values and labels. If the Label Property is not set, the values from the Value Property are used as labels, as well.

   AWM uses a specified search hierarchy to find values and labels:

   • The last file descriptor of the Retrieve Values action containing the Value Property is used to retrieve the value. If a file descriptor is found, the value for the label property is retrieved from this file descriptor. Any structured file descriptor is supported.
   • If the Value Property cannot be found in any file descriptor defined for tools of the action, the Value Property and Label Property is searched for among the mass processing input and output parameters.
   • If the Value Property cannot be found among the mass processing input and output parameters, the Value Property and Label Property is searched for among the single processing input and output parameters.

2. Values From = Output Table

   The modeled Retrieve Values action descriptor needs to contain a tool descriptor which returns a table structured file descriptor. The file descriptor must have at least one relationship to a property. If several tool descriptors of the retrieve action return file descriptors, the last one is used by AWM.

   To support labels in the box, simply return two values for each line of the structured file descriptor. AWM interprets the first value of each line as the value and the second as the label. Additional values returned in the file descriptor are ignored.