Retrieve All Values

The Retrieve All 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 output.

The Retrieve All Values action can only be executed in a modeled input dialog. See Open Modeled Dialog for more information. If a property with a Retrieve All Values action is used as an editable input field in a dialog, a Retrieve button is displayed next to it. Click Retrieve to execute the action and populate the dialog field with the returned values.

If several tool descriptors of the retrieve action return file descriptors then the last one 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 seen in the following figure:


A populated input field

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 All Values action.

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

Example:

In a Retrieve All Values action, you can use the Select Resource tool from the Eclipse function package or the Select Local OS Resource tool from the OS function package to open a standard dialog for a file/folder selection. The selected file/folder is directly placed into the dialog input field.

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

  1. Values From = Matching Property
    This is the recommended selection. By default AWM expects the values to be returned in a structured file descriptor which contains the concerning 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.

    Search hierarchy:

    • The last file descriptor of the Retrieve All 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 All 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.