sapui5tutors SAPUI5 • Fiori • SAP BTP Step-by-step tutorials Real project examples Interview Q&A
Practical SAPUI5 • Fiori • SAP BTP tutorials and interview prep

CAPM Value Helps: @Common.ValueList Explained

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.ValueList turns 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 ID back into the order's customer_ID field.
  • DisplayOnly parameter — shows the customer name in the dialog without writing it anywhere.
  • Fixed values — add @Common.ValueListWithFixedValues for 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.Text so 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.