The dropdown every app needs
Users don't type customer IDs from memory — they pick from a list. In Fiori Elements, that list is a value help, driven by the @Common.ValueList annotation. One annotation, and your input field gets a searchable dialog.
@Common.ValueListturns a foreign-key field into a full value-help dialog: search, filter, and select — generated from annotations.
The basic annotation
service OrderService {
entity Orders as projection on my.Orders {
*,
customer : Association to Customers;
}
annotate Orders with {
customer @Common.ValueList : {
CollectionPath : 'Customers',
Parameters : [
{
$Type : 'Common.ValueListParameterInOut',
LocalDataProperty : customer_ID,
ValueListProperty : 'ID'
},
{
$Type : 'Common.ValueListParameterDisplayOnly',
ValueListProperty : 'name'
}
]
};
};
}
Reading the annotation
- CollectionPath — the entity set the dialog lists (
Customers). - InOut parameter — maps the selected customer's
IDback into the order'scustomer_IDfield. - DisplayOnly parameter — shows the customer
namein the dialog without writing it anywhere. - Fixed values — add
@Common.ValueListWithFixedValuesfor small static lists rendered as dropdowns instead of dialogs.
Always include a display-only text field (name, description) alongside the key. Users pick by name, the system stores the key.
Value help with filters
Need the dialog pre-filtered — say, only active customers?
customer @Common.ValueList : {
CollectionPath : 'Customers',
Parameters : [ ... ],
SearchSupported : true
};
Combine with a @Capabilities.FilterRestrictions or a service-level filter on the customers entity. The dialog respects the same query options as the entity set.
Common mistakes
- Annotating the association, not the key — the value list goes on the foreign key element (
customer_ID), or via the association as shown above. - Missing CollectionPath entity — the target entity set must be exposed in the same service.
- No text arrangement — add
@Common.Textso the field displays "1001 (Acme Corp)" instead of a bare ID.
Text arrangement: show names, store keys
A value help that displays bare IDs is only half done. Add @Common.Text so fields render as "1001 (Acme Corp)":
annotate Orders with {
customer @Common.Text : customer.name;
};
This pattern — key stored, text displayed — applies everywhere: statuses, categories, units of measure. Annotate the text once on the entity, and every Fiori UI that shows the field picks it up.
Small annotation, big UX win
Value helps are one of those features users never notice when present — and complain loudly about when missing. Twenty lines of annotation buys you a professional selection dialog.
Value help misbehaving? Describe the symptom in the comments.