Prefill plugins

Open Forms has a plugin system for the prefill module. The prefill module is invoked when form step (or rather, submission steps) are retrieved from the API to obtain the FormioJS configuration. In the form builder, it’s possible to specify which plugin and plugin-specific attribute to use to prefill the default value.

Each plugin is responsible for fetching the relevant data from the plugin-specific backend, which could be StUF-BG, HaalCentraal BRP or Chamber of Commerce for example.

Developing plugins

Every possible backend can be implemented as a plugin, and registered with Open Forms.

Registering the plugin makes it available for content-editors to select as possible prefill option for a form field.

You can find an example implementation in openforms.prefill.contrib.demo.

Implementation

Plugins must implement the interface from openforms.prefill.base.BasePlugin. It’s safe to use this as a base class.

There are two relevant public methods:

get_available_attributes

provide an iterable of (identifier, label) tuples. This is used to pre-populate/ display the list of attributes that can be selected by content-editors.

get_prefill_values

the actual implementation of the prefill functionality. This is invoked inside the request-response cycle of certain API endpoints.

Public Python API

Plugin base class

class openforms.prefill.base.BasePlugin(identifier: str)
get_available_attributes() → Iterable[tuple[str, str]]

Return a choice list of available attributes this plugin offers.

get_co_sign_values(submission: openforms.submissions.models.submission.Submission, identifier: str) → tuple[dict[str, Any], str]

Given an identifier, fetch the co-sign specific values.

The return value is a dict keyed by field name as specified in self.co_sign_fields.

Parameters

identifier – the unique co-signer identifier used to look up the details in the pre-fill backend.

Returns

a key-value dictionary, where the key is the requested attribute and the value is the prefill value to use for that attribute.

get_identifier_value(submission: openforms.submissions.models.submission.Submission, identifier_role: openforms.prefill.constants.IdentifierRoles) → str | None

Given a submission and the role of the identifier, return the value of the identifier.

The role of the identifier has to do with whether it is the ‘main’ identifier or an identifier of someone logging in on behalf of someone/something else.

Parameters

  • submission – an active Submission instance

  • identifier_role – A string with one of the choices in IdentifierRoles

Returns

The value for the identifier

get_prefill_values(submission: openforms.submissions.models.submission.Submission, attributes: list[str], identifier_role: openforms.prefill.constants.IdentifierRoles = IdentifierRoles.main) → dict[str, 'DjangoJSONEncodable | JSONSerializable']

Given the requested attributes, look up the appropriate values and return them.

Parameters

  • submission – an active Submission instance, which can supply the required context to fetch the correct prefill values.

  • attributes – a list of requested prefill attributes, provided in bulk to efficiently fetch as much data as possible with the minimal amount of calls.

  • identifier_role – A string with one of the choices in IdentifierRoles

Returns

a key-value dictionary, where the key is the requested attribute and the value is the prefill value to use for that attribute.

When no prefill value can be found for a given attribute, you may omit the key altogether, or use None.

Module documentation

This package holds the base module structure for the pre-fill plugins used in Open Forms.

Various sources exist that can be consulted to fetch data for an active session, where the BSN, CoC number… can be used to retrieve this data. Think of pre-filling the address details of a person after logging in with DigiD.

The package integrates with the form builder such that it’s possible for every form field to select which pre-fill plugin to use and which value to use from the fetched result. Plugins can be registered using a similar approach to the registrations package. Each plugin is responsible for exposing which attributes/data fragments are available, and for performing the actual look-up. Plugins receive the openforms.submissions.models.Submission instance that represents the current form session of an end-user.

Prefill values are embedded as default values for form fields, dynamically for every user session using the component rewrite functionality in the serializers.

So, to recap:

  1. Plugins are defined and registered

  2. When editing form definitions in the admin, content editors can opt-in to pre-fill functionality. They select the desired plugin, and then the desired attribute from that plugin.

  3. End-user starts the form and logs in, thereby creating a session/Submission

  4. The submission-specific form definition configuration is enhanced with the pre-filled form field default values.

Todo

Move the public API into openforms.prefill.service.

openforms.prefill.inject_prefill(configuration_wrapper: FormioConfigurationWrapper, submission: Submission) → None

Mutates each component found in configuration according to the prefilled values.

Parameters

  • configuration_wrapper – The Formiojs JSON schema wrapper describing an entire form or an individual component within the form.

  • submission – The openforms.submissions.models.Submission instance that holds the values of the prefill data. The prefill data was fetched earlier, see prefill_variables().

The prefill values are looped over by key: value, and for each value the matching component is looked up to normalize it in the context of the component.

openforms.prefill.prefill_variables(submission: Submission, register: Registry | None = None) → None

Update the submission variables state with the fetched attribute values.

For each submission value variable that need to be prefilled, the according plugin will be used to fetch the value. If register is not specified, the default registry instance will be used.