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 be added to the INSTALLED_APPS setting in openforms.conf.base. See the demo app (openforms.prefill.contrib.demo.apps.DemoApp) as an example.

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)
static get_available_attributes() → Iterable[tuple[str, StrOrPromise]]

Return a choice list of available attributes this plugin offers.

classmethod get_co_sign_values(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.

classmethod get_identifier_value(submission: Submission, identifier_role: 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

classmethod get_prefill_values(submission: Submission, attributes: list[str], identifier_role: IdentifierRoles = IdentifierRoles.main) → dict[str, JSONEncodable]

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.

classmethod get_prefill_values_from_options(submission: Submission, options: OptionsT, submission_value_variable: SubmissionValueVariable) → dict[str, JSONEncodable]

Given the saved form variable, which contains the prefill_options, look up the appropriate values and return them.

Parameters:

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

  • options – contains plugin-specific configuration options.

  • submission_value_variable – the submission value variable which is needed in some prefill plugins.

Returns:

a mapping where the keys are form variable keys, and the values are the initial/default values to assign to the matching form variable. The variable keys can point to both component and user defined variables.

options

alias of EmptyOptions

requires_auth: Collection[AuthAttribute] = ()

Indicates the type of authentication that must be present on the form.

The prefill plugin will be inert if the user is not authenticated with one of the specified attributes. An empty value means that no particular authentication is required.

requires_auth_plugin: ClassVar[Collection[str]] = ()

A collection of authentication plugin IDs, of wich one must be enabled.

If a non-empty value is provided, it means the plugin requires a specific auth plugin to be enabled on the form to be functional, going beyond requires_auth.

classmethod verify_auth_plugin_requirement(submission: Submission) → bool

Hook to check if the authenticated user used the required auth plugin.

This only performs a check if any required auth plugin is specified on the prefill plugin class.

Parameters:

submission – an active Submission instance

Returns:

Whether the required auth plugin was used or not.

verify_initial_data_ownership(submission: Submission, prefill_options: OptionsT) → None

Hook to check if the authenticated user is the owner of the object referenced to by initial_data_reference

If any error occurs in this check, it should raise a PermissionDenied

Parameters:

  • submission – an active Submission instance

  • prefill_options – the configuration options, after validation and deserialization through the options serializer class.

Module documentation