Prefill

The prefill module is invoked during the submission creation when an end-user starts the form submission, after logging in. For forms without login, most prefill plugins skip their execution. Typically the user identification (obtained through Authentication) is used to look up additional details in an external API or service.

For each form field (or variable), the form builder can configure which plugin to use to prefill it, and with which attribute. More complex configurations are possible, depending on the selected plugin.

Python API

There are currently two main modes of prefill configuration:

simple plugin + attribute, typically stored in the Formio component definition
advanced plugin + plugin options, for prefill behaviour that doesn’t fit in a formio component

We’re planning to rework the simple system into the more advanced system so that there’s only a single mode that covers all needs.

Module interface

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 to:: a) select which pre-fill plugin to use and which value to use from the fetched result via the component’s configuration, b) create a user-defined variable via the variables tab and select which pre-fill plugin to use and which value to use from the fetched result and c) define a user-defined variable via the variables tab in which the prefill_options are configured.

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:

Plugins are defined and registered
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.
Content editors can also define a user-defined variable and configure the plugin and the necessary options by selecting the desired choices for the prefill_options.
End-user starts the form and logs in, thereby creating a session/Submission
The submission-specific form definition configuration is enhanced with the pre-filled form field default values.

openforms.prefill.service.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.service.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 needs 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.

Plugin interface

Prefill plugins must inherit from the base plugin.

Plugin base API

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.

class openforms.prefill.base.EmptyOptions(*args, **kwargs)

class openforms.prefill.base.Options

Available implementations

Customer interactions

Fetch and update customer profile details from Open Klant.

Demo

Demo plugin that prefills form fields with random data.

eIDAS

Extract user or company details from the European authentication means.

Family members

Look up partner and/or children details of the authenticated user, using their BSN and “Haal Centraal BRP Personen bevragen” or StUF-BG.

Haal Centraal BRP Personen bevragen

Using the BSN of the authenticated user, fetch additional personal details, e.g. the name(s), date of birth…

KvK (Chamber of Commerce)

Look up company details based on the Chamber of Commerce number of the authenticated company.

Objects API

Given an Object reference at the start of a form, look up the object details and extract the relevant information for further use in the form submission. Object ownership is by default validated against the identification of the authenticated user.

StUF-BG

Using the BSN of the authenticated user, fetch additional personal details, e.g. the name(s), date of birth…

Suwinet

Todo

add description

Yivi

Yivi can both authenticate a user and act as a digital wallet to provide additional personal or company details during the login process.