Registration plugins¶
Open Forms has a plugin system for the registrations module. The registrations module is invoked when a form submission is completed, and is responsible for persisting the form data to the configured backend.
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 a registration backend for a form.
Implementation¶
A plugin is nothing more than a callable, most often a plain Python function. It must adhere to the following function signature:
from typing import Optional
from openforms.submissions.models import Submission
def plugin(submission: Submission, options: dict) -> Optional[dict]:
# do stuff
The function body is of course up to you to interact with the registration backend.
Each backend can require additional configuration/options that is required for the
implementation. This is specified as a rest_framework.serializers.Serializer
:
from zgw_consumers.models import Service, APITypes
class PluginOptions(serializers.Serializer):
zaaktype = serializers.URLField()
zaken_api = serializers.PrimaryKeyRelatedField(
queryset=Service.objects.filter(api_type=APITypes.zrc)
)
Plugin developers have full control over these serializers.
The serializer is specified during plugin registration, using the @register
decorator syntax:
from ...registry import register
@register("unique-key", "Human readable name", configuration_options=PluginOptions)
def plugin(submission: Submission, options: dict) -> dict:
...
The return value of the callback is saved on the submission as backend result/log. If this is not JSON-serializable, you can specify a serializer for this as well:
from ...registry import register
@register(
"unique-key",
"Human readable name",
configuration_options=PluginOptions,
backend_feedback_serializer=BackendFeedbackSerializer,
)
def plugin(submission: Submission, options: dict) -> dict:
...
Registration failure¶
If the registration fails for whatever reason, then your plugin should raise
openforms.registrations.exceptions.RegistrationFailed
. This will mark the
submission with a failed state, making it possible to handle these failures.
The submission handler extracts the traceback, so you should ideally raise this exception from the root exception to include the full traceback:
try:
... # do plugin stuff
except Exception as exc:
raise RegistrationFailed from exc
Public Python API¶
Plugin base class
- class openforms.registrations.base.BasePlugin(identifier: str)¶
- camel_case_ignore_fields = None¶
Iterable of JSON keys to ignore when converting between snake_case/camelCase.
- configuration_options¶
A serializer class describing the plugin-specific configuration options.
A plugin instance is the combination of a plugin callback and a set of options that are plugin specific. Multiple forms can use the same plugin with different configuration options. Using a serializer allows us to serialize the options as JSON in the database, and de-serialize them into native Python/Django objects when the plugin is called.
alias of
openforms.registrations.base.EmptyOptions
- abstract get_reference_from_result(result: Any) str ¶
Extract the public submission reference from the result data.
This method must return a string to be saved on the submission model.
- Parameters
result – the raw underlying JSONField datastructure.
Module documentation
The openforms.registrations
package provides the persistence backends
for submissions.
Once a form is submitted (‘completed’) by an end-user, a
openforms.submissions.models.Submission
instance is available holding all the
submitted data.
This data needs to be forwarded to the appropriate systems - it could be that a Zaak
has to be created, or just an e-mail sent somewhere, or anything else. This package
provides a public Python API to trigger this mechanism, where each individual plugin
implements said appropriate system.
The registered plugins all have their own specific configuration and quirks, and we will expose this to the form designers / editors. We couple a single form object to a particular backend that needs to handle it.