Retrieve Labels

The Retrieve Labels attribute can be used to dynamically retrieve labels for property values at run time. It is used to hide values of a property and to display corresponding labels instead. For example, an application uses numeric user IDs internally, which link to a full user name that is then displayed in the UI. The linked user name labels are used instead of the values both in AWM related views and in modelled dialogs.

The referenced Retrieve Labels action descriptor must contain a tool that returns a list of values and their corresponding labels, similar to Retrieve Values. In contrast to Retrieve Values, Retrieve Labels always returns value/label pairs. AWM provides the property value, of which a label must be retrieved in the execution context. It can be used as an input parameter within tool descriptors of the associated action descriptor (Parameter From = “Context”).

Defining a Retrieve Labels action results in only labels, instead of values, being displayed for the property in the UI. AWM automatically executes the Retrieve Labels action if a value of the property is about to be displayed and its label has not already been retrieved in the current session. Returned value/label pairs must at least contain the property value in question, otherwise an error message will be displayed. For performance reasons, Micro Focus recommends that you return all possible value, label combinations with one call. AWM will store all retrieved pairs in memory, so they can be resolved without executing the Retrieve Labels action again.

Note: This cache is not persisted between sessions, this is to prevent outdated labels being displayed.

If the property is also used in modelled dialogs, then you will also need to specify a Retrieve Values action. The reason for this is that you typically do not know the actual values of the property, so the only option is to select a label from a retrieved list of value/label pairs. Another reason is that modeled dialogs can also be used to display existing values (possibly even non-editable). So AWM needs to be capable to retrieve a value label before a dialog is even displayed.

Value/label pairs returned by Retrieve Values are stored in the same cache as those returned by the Retrieve Labels with the aim to further improve performance for retrieving labels. You can also reference the same action descriptor for Retrieve Labels and Retrieve Values, if all possible values and labels can be obtained and no filtering is desired in your modelled dialogs.

Modeling Examples

The usage of Retrieve Labels is only required in very specific scenarios. The typical prerequisites for using Retrieve Labels are:

An application interface does not return human-readable labels for a property, which should be displayed in the UI. For example, a query to an agile planning tool returns numeric user names but not the full names. The desired result is an element list with full user names.
Attributes with non-readable labels should be selected in modeled dialogs.
- The difference to the first list item is that the application may be able to return both user ID and full name in query results. But if a user ID can be specified in a modeled dialog, AWM requires an additional action to resolve the matching user names.
- For example, an agile planning tool requires a numeric user ID to be specified in order to create a work item. The desired AWM action enables the full user name to be selected from a list in a modeled dialog in this case which is then internally mapped to the numeric user ID.