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.

Registration

Plugins are implemented as Django apps / Python packages. The openforms.prefill.contrib.demo plugin acts as an example.

  1. Create the python package in openforms.prefill.contrib.<vendor>

  2. Ensure you have an AppConfig defined in this package, e.g.:

    class MyPlugin(AppConfig):
    name = "openforms.prefill.contrib.<vendor>"
    verbose_name = "My <vendor> plugin"

    def ready(self):
        from . import plugin  # noqa

    It’s important to import the plugin as part of the ready hook of the AppConfig, as this ensures that the plugin is added to the registry.

  3. Add the application to settings.INSTALLED_APPS, this will cause the AppConfig to be loaded.

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_prefill_values(submission: openforms.submissions.models.Submission, attributes: List[str]) → Dict[str, Any]

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

Parameters

  • submission – an active Submission instance, which can be 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.

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 pre-fill value can be found for a given attribute, you may omit the key altogether, or use None.

requires_auth = None

Specify the human-readable label for the plugin.

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.

openforms.prefill.apply_prefill(configuration: Dict[str, Union[str, int, None, float, JSONObject, List[JSONValue]]], submission: Submission, register=None)

Takes a Formiojs definition and invokes all the pre-fill plugins.

The entire form definition is parsed, plugins and their attributes are extracted and each plugin is invoked with the list of attributes (in parallel). If a default value was specified for a component, and the prefill plugin returns a value as well, the prefill value overrides the default.

Parameters

  • configuration – The formiojs form configuration, including all the components. This must adhere to the formiojs proprietary JSON schema.

  • submission – the relevant for submission session, holding the optional BSN or other identifying details obtained after authentication. This object is passed down to the plugins so that they can inspect the submission context to retrieve prefill data.

  • register – A openforms.prefill.registry.Registry instance, holding the registered plugins. Defaults to the default registry, but can be specified for dependency injection purposes in tests.

Returns

Returns a mutated copy of the configuration, where components defaultValue is set to the value from prefill plugins where possible. If the defaultValue was set through the form builder, it may be overridden by the prefill plugin value (if it’s not None).