Skip to main content
Version: Any 26

Data lists

A data list is a reference set of values: the list of the countries, of the agencies, of the contract types, of the analytical codes.

It lets users pick a value instead of typing it. The data then stays consistent (no "FR", "France" and "france" in the same metadata) and the displayed value can differ from the stored value: a code is stored, a label is shown. A data list can also carry resources, such as images.

A single list feeds as many metadata and forms as needed, and is updated in a single place.

Sort values alphabetically: sorts the values offered to the user, rather than keeping the order of the list.

Data source​

The Type determines where the values come from. A list can be filled in four ways.

Whatever the type, the values are displayed in a grid at the bottom of the page, with an Enabled column: a disabled value is kept but no longer offered to the user. The columns are editable only for a values list. For the other types, they are read from the source.

Values list​

The values are entered in the module itself, directly in the grid.

Columns are added and removed from the grid. A column name can only hold lowercase letters, digits and underscores, must be unique in the list, and cannot reuse a reserved name: value, data_list_name or value_column_name.

Two actions come with this list type:

  • Export to Excel: retrieve the values in a workbook.
  • Import values from file: replace the values with those of an Excel or JSON file. The columns are taken from the file.

Neither action is available at the module creation, nor as long as changes are not saved.

GQL query​

The values come from the contents of Any themselves.

GQL query or predicates: query that defines the values. It can cover the contents or the users (from users).

The Preview results button shows what the query returns. The grid of the page only displays the first 500 values. The list itself is not limited.

Java​

The values are produced by code.

Java Class: class that supplies the values, chosen among the deployed implementations. The columns and the values are the ones it returns.

REST​

The values are retrieved from an external service, which relies on a reference set already kept elsewhere rather than copying its content into Any.

Access URL: URL of the service. It accepts wildcards, which builds the call from the context and the parameters described below.

Data path: location of the list of values in the response of the service. Left empty, the response is itself the list.

Other REST parameters opens the rest of the call:

  • Call type: GET or POST.
  • HTTP headers: headers to send, for instance an API key or a token. Both names and values accept wildcards.
  • Content type and Content: only for a POST call. The content type (application/x-www-form-urlencoded, multipart/form-data, application/json or application/xml) pre-fills the body of the request with the parameters, which then have to be adjusted to the called service.

Parameters passed to the service​

Any does not just retrieve a frozen list: it passes to the service what the user is doing (what they typed, the page they are on) as wildcards to place in the URL or in the body of the request.

WildcardContent
${filters}Active filters, in JSON: an array of column_name, operator and value objects.
${column_names}Expected columns, in JSON.
${sort_by}Requested sort.
${include_disabled_values}true if the disabled values must be returned.
${from_index}Index of the first expected value.
${size}Number of expected values.

In a GET URL, these values are encoded automatically.

These parameters are what make a REST list usable on a large reference set: the service filters, sorts and paginates itself, and only returns the requested slice. This assumes they are actually used: a service that ignores them and returns everything on each call will work, but will transfer the whole reference set every time a list is opened. On-demand loading is available for POST calls only.

Expected response​

The response is JSON. Each object found at the data path becomes a value, and each of its fields a column:

{
"itemsCount": 240,
"data": [
{ "code": "FR", "label": "France" },
{ "code": "BE", "label": "Belgique", "is_enabled": false }
]
}

The is_enabled field of an object, if present, disables the value. Without it the value is active. The itemsCount field at the root gives the total number of values available beyond the returned slice: it is needed for pagination. Without it, Any considers that the response holds every value.

Limits​

A REST list, like a Java list, is not offered in the list picker of the properties pages nor of the Aspects module: these sources are too heterogeneous for filtering to be guaranteed on them.