Integratie van Referentielijsten API

[joeridiederen]

Thema / Theme

Frontend

Omschrijving / Description

This RFC proposes integrating a Referentielijsten API into Open Forms to dynamically populate single-selection (keuzelijst) and multi-selection (selectievakjes) components with values retrieved from external reference lists.

Each time a form is loaded, Open Forms will fetch data from a configured Referentielijsten API endpoint. The fetched list populates selectable options, either as a single-choice dropdown or a multiple-choice checkbox group, depending on the component’s configuration.

The base URL and authentication of the Referentielijsten API is managed within the Open Forms administration interface. However, within each keuzelijst or selectievakjes-component’s settings, an administrator can specify a particular “code” (table identifier) to retrieve data for that specific table. This ensures that different components within the same form can request different sets of reference data from the same base URL, simply by varying the tabelcode. Also the isGeldig boolean should be visible for adminstrators.

As a “nice to have,” it would be beneficial if the component’s configuration UI could immediately display a preview of the retrieved data, providing visual confirmation that the correct tabelcode and parameters have been configured

For the keuzelijst (single selection), the user’s chosen label is stored as a string:

{
  "mijnKeuze": "Gekozen value"
}

For the selectievakjes (multiple selection), the chosen labels are stored as an array:

{
  "mijnSelecties": ["value 1", "value 2"]
}

Added value / Toegevoegde waarde

Integrating the Referentielijsten API to populate keuzelijst and selectievakjes components provides significant benefits. By seamlessly fetching and displaying dynamically maintained reference data, administrators no longer need to manually update static lists. This ensures that forms remain accurate and current over time, especially when tied to official, centrally managed reference lists.

Aanvullende opmerkingen / Additional context

• The keuzelijst must support searching, as all options will be loaded at once.

• If the API is unavailable or returns an error, Open Forms must display a user-friendly error message to the end user.

Nice to have: the integration must be language-aware*: if the form is presented in a certain language (e.g., Dutch, English), Open Forms should add a query parameter or header to the API call to retrieve language-appropriate labels.

*Not yet possible in the Referentielijsten API, request scheduled for further discussion.

Tasks

Configuration / runtime behavior (OF backend):

• Configure one or more Services to connect with Referentielijsten API. Add a m2m field to GlobalConfiguration to indicate which Services are Referentielijsten instances. #4991
• When loading the formstep perform a service fetch operation to populate the component choices #4993
• Nice to have: implement language awareness, ensure the language the form is rendered in is passed along with the API requests (as an Accept-Language header most likely)

Code changes to selectbox/selectboxes editform (FormIO builder):

• Add an extra data source option (Referentielijsten API) on the basic tab (might be good to move to a separate Source tab if the form ends up becoming too complex)
• When selected, display a react-select widget to select a service to populate from (if there is only one referentielijst service, automatically select that one)
• When the service is selected, display a react-select widget to select the code of the tabel (populated from the tabellen list of the API /api/v1/tabellen), in parentheses display the einddatumGeldigheid (or a boolean if this date is in the past)
• Nice to have: if a code is selected, perform the service fetch operation and display the choices retrieved from /api/v1/items?tabel__code=<code>
• When the editform is saved, openForms.dataSrc should be set to referentielijsten

General:

• whenever requests are performed and failures occur for whatever reason, display a user friendly error message

[sergei-maertens]

@stevenbal please draft a plan to implement this before starting to write code :-)

[stevenbal]

@sergei-maertens

Configuration (OF backend):

• Configure one or more Services to connect with Referentielijsten API. I'm not sure if it's necessary to be able to configure more than one endpoint, but I can imagine this is desirable at some point (since the same happened for ZGW / Objects API). We could add a separate model similar to ObjectsAPIGroupConfig with a FK to Service to construct a list of possible Referentielijsten APIs; or add a new referentielijsten type to zgw-consumers. I'm not sure though if the API types in zgw-consumers are still used, so I'm leaning towards adding a groupconfig model instead. Add a m2m field to GlobalConfiguration to indicate which Services are Referentielijsten instances

Code changes to selectbox/selectboxes editform (FormIO builder):

• Add an extra data source option (Referentielijsten API) on the basic tab (might be good to move to a separate Source tab if the form ends up becoming too complex)
• When selected, display a react-select widget to select a service to populate from (not sure if this should be the same for one form, or if it can differ per component within a form, but I guess we could start with the latter)
• When the service is selected, display a react-select widget to select the code of the tabel (populated from the tabellen list of the API /api/v1/tabellen), in parentheses display the einddatumGeldigheid (or a boolean if this date is in the past)
• Nice to have: if a code is selected, perform the service fetch operation and display the choices retrieved from /api/v1/items?tabel__code=<code>
• When the editform is saved, openForms.dataSrc should be set to referentielijsten

Runtime behaviour changes (OF backend):

• When loading the formstep perform a service fetch operation to populate the component choices, by performing a request to /api/v1/items?tabel__code=<code>
  • implement in openforms.formio.dynamic_config.dynamic_options.add_options_to_config
  • it could instantiate a ServiceFetchConfiguration object (without saving) to make use of that to fetch the data
• Nice to have: implement language awareness, ensure the language the form is rendered in is passed along with the API requests (as an Accept-Language header most likely)

General:

• whenever requests are performed and failures occur for whatever reason, display a user friendly error message

[stevenbal]

About the format of the data: we could add an option on the components to store labels instead of values, but do note that this might cause logic rules based on this data might not work as well in case of multiple languages, you would have to add a conditional per language, because the labels change per language.

Additionally, the current format of the selectievakjes is: {"mijnSelecties": {"keuze1": true, "keuze2": false, ...}. To have a format like you mentioned in the issue, we could also add an option to the selectievakjes component to transform the data to this shape.

@joeridiederen does that sound reasonable to you?

[joeridiederen]

Hi @stevenbal ; We had a quick discussion and concluded that storing the value is basically fine, as long as it remains human-readable. And that’s possible, because spaces are accepted. So for your first remark, you don’t need to make any changes; the output will then look like this:

{
  "mijnKeuze": "Gekozen value"
}

The same is true for the output of the 'selectievakjes' and the 'keuzelijst': the value is stored, not the label. I’ve updated the RFC accordingly.

Regarding your second remark: yes, we’d like to add your suggested option to ‘selectievakjes’ to transform the data so it’s immediately understandable for users when they see the value(s). In many cases, the output is meant for humans rather than machines, and we’ve noticed that users find the current format inconvenient.

The same goes for ‘keuzelijst’.