diff --git a/docs/configuration/registration/_assets/objects_api_modal.png b/docs/configuration/registration/_assets/objects_api_modal.png new file mode 100644 index 0000000000..62b8da888b Binary files /dev/null and b/docs/configuration/registration/_assets/objects_api_modal.png differ diff --git a/docs/configuration/registration/_assets/variables_tab.png b/docs/configuration/registration/_assets/variables_tab.png new file mode 100644 index 0000000000..a22f6dcd76 Binary files /dev/null and b/docs/configuration/registration/_assets/variables_tab.png differ diff --git a/docs/configuration/registration/objects.rst b/docs/configuration/registration/objects.rst index 9acc03724d..40141d7ddf 100644 --- a/docs/configuration/registration/objects.rst +++ b/docs/configuration/registration/objects.rst @@ -11,12 +11,16 @@ supports creating objects in the Objects API, such as the `ProductAanvraag objec Open Forms can be configured to create an object (of type ``ProductAanvraag``) to register form submissions. +Since Open Forms ``2.6.0``, a new way of configuring the form registration is available. +Hereafter, we will refer to this new configuration as the *Variables mapping (v2)* configuration. +The old configuration will be refered as the *Legacy (v1)* configuration. + What does the Open Forms administator need? =========================================== -* API resource URL of object type(s) to use for registration. Open Forms does not (yet) - need access to the Object Types API. -* Access the Objects API, with write permissions for the relevant object types. Open +* API resource URL of object type(s) to use for registration. If using the *Variables mapping (v2)* + configuration, access to the Objecttypes API where the object type(s) leave is required. +* Access the Objects API, with write permissions for the relevant Objecttypes. Open Forms creates and updates records. * API resource URLs of document types (informatieobjecttype) in the Catalogi API - attachments are created using these document types: @@ -28,13 +32,137 @@ What does the Open Forms administator need? * Write access to the Documenten API, some attachments/files are created there and then related to the record in the Objects API. -.. warning:: For forms with payment requirements, a PATCH request is made to the - Objects API to update the payment status. This requires a version of the Objects API - newer than 2.1.1, which is unreleased at the time of writing. +.. warning:: + + When using the *Legacy (v1)* configuration, a PATCH request is made to the + Objects API to update the payment status (for forms with a payment requirement). + This requires a version of the Objects API newer than 2.1.1. When using the + *Variables mapping (v2)* configuration, a PUT request is made instead. Configuration ============= +To configure the Objects API follow these steps: + +#. In Open Forms, navigate to: **Configuration** > **Services** +#. Create a service for the Objects API (ORC) where the form data will be registered. + + a. Click **Service toevoegen**. + b. Fill out the form: + + * **Label**: *Fill in a human readable label*, for example: ``My Objects API`` + * **Type**: Select the type: ``ORC`` + * **API root url**: The root of this API, *for example* ``https://example.com/objecten/api/v2/`` + + * **Authorization type**: Select the option: ``API Key`` + * **Header key**: Fill in ``Authorization`` + * **Header value**: Fill in ``Token `` where ```` is replaced by the token provided by the backend service + * **OAS**: URL that points to the OAS, same URL as used for **API root url** with ``/schema/openapi.yaml`` added to it + *for example:* ``https://example.com/objecten/api/v1/schema/openapi.yaml`` + + * **NLX**: Support for NLX can be selected here if enabled in the installation + * **User ID**: Audit trail user ID, usually same as the Client ID + * **User representation**: *For example:* ``Open Forms`` + + c. Click **Opslaan** and repeat to create configuration for the other component. + +#. If using the *Variables mapping (v2)* configuration, create a service for the Objecttypes API (ORC). + + a. Click **Service toevoegen**. + b. Fill out the form: + + * **Label**: *Fill in a human readable label*, for example: ``My Objecttypes API`` + * **Type**: Select the type: ``ORC`` + * **API root url**: The root of this API, *for example* ``https://example.com/objecttypen/api/v2/`` + + * **Authorization type**: Select the option: ``API Key`` + * **Header key**: Fill in ``Authorization`` + * **Header value**: Fill in ``Token `` where ```` is replaced by the token provided by the backend service + * **OAS**: URL that points to the OAS, same URL as used for **API root url** with ``/schema/openapi.yaml`` added to it + *for example:* ``https://example.com/objecttypen/api/v1/schema/openapi.yaml`` + + * **NLX**: Support for NLX can be selected here if enabled in the installation + * **User ID**: Audit trail user ID, usually same as the Client ID + * **User representation**: *For example:* ``Open Forms`` + + c. Click **Opslaan** and repeat to create configuration for the other component. + +#. Create a service for the Documentregistratiecomponent (DRC) where the PDF summary and form attachment documents will be stored. + + a. Click **Service toevoegen**. + b. Fill out the form: + + * **Label**: *For example:* ``Documenten`` + * **Type**: Select the type: ``DRC`` + * **API root url**: The root of this API, *for example* ``https://example.com/documenten/api/v1/`` + + * **Client ID**: Fill the value provided by the backend service *For example:* ``open-forms`` + * **Secret**: Fill the value provided by the backend service + * **Authorization type**: Select the option: ``ZGW client_id + secret`` + * **OAS**: URL that points to the OAS, same URL as used for **API root url** with ``/schema/openapi.yaml`` added to it + *for example:* ``https://example.com/documenten/api/v1/schema/openapi.yaml`` + + * **NLX**: Support for NLX can be selected here if enabled in the installation + * **User ID**: Audit trail user ID, usually same as the Client ID + * **User representation**: *For example:* ``Open Forms`` + +#. Create a service for the Zaaktypecatalogus (ZTC). This is needed to retrieve Informatieobjecttypen. + + a. Click **Service toevoegen**. + b. Fill out the form: + + * **Label**: *For example:* ``Catalogi`` + * **Type**: Select the type: ``ZTC`` + * **API root url**: The root of this API, *for example* ``https://example.com/catalogi/api/v1/`` + + * **Client ID**: Fill the value provided by the backend service *For example:* ``open-forms`` + * **Secret**: Fill the value provided by the backend service + * **Authorization type**: Select the option: ``ZGW client_id + secret`` + * **OAS**: URL that points to the OAS, same URL as used for **API root url** with ``/schema/openapi.yaml`` added to it + *for example:* ``https://example.com/catalogi/api/v1/schema/openapi.yaml`` + + * **NLX**: Support for NLX can be selected here if enabled in the installation + * **User ID**: Audit trail user ID, usually same as the Client ID + * **User representation**: *For example:* ``Open Forms`` + +#. Navigate to **Configuration** > **Overview**. In the **Registration plugin** group, click on **Configuration** for the **Objects API registratie** line. +#. Enter the following details: + + * **Objects API**: Select the Objects API (ORC) service created above + * **Objecttypes API**: Only if using the *Variables mapping (v2)*, select the Objecttypes API (ORC) service created above + * **Documenten API**: Select the Documentregistratiecomponent (DRC) service created above + * **Catalogi API**: Select the Zaaktypecatalogus (ZTC) service created above + * **Productaanvraag type**: Fill in the type of ProductAanvraag *For example:* ``terugbelnotitie`` + * **Submission report informatieobjecttype**: Fill in the default URL of the INFORMATIEOBJECTTYPE for the submission report in the Catalogi API *For example* ``https://example.com/api/v1/informatieobjecttypen/1/`` + * **Upload submission CSV**: Indicate whether or not the submission CSV should be uploaded to the Documenten API by default (can be overridden per form) + * **Submission report CSV informatieobjecttype**: Fill in the default URL of the INFORMATIEOBJECTTYPE for the submission report CSV in the Catalogi API *For example* ``https://example.com/api/v1/informatieobjecttypen/2/`` + * **Attachment informatieobjecttype**: Fill in the default URL of the INFORMATIEOBJECTTYPE for the submission attachments in the Catalogi API *For example* ``https://example.com/api/v1/informatieobjecttypen/3/`` + * **Organisatie RSIN**: Fill the RSIN to be referred to in the created objects. *For example:* ``123456789`` + + If using the *Legacy (v1)* configuration, the default JSON templates can be configured as well: + + * **JSON content template**: This is a template for the JSON that will be sent to the Object API nested in the + ``record.data`` field. + * **Payment status update JSON template**: This is a template for the JSON that will be sent with a PATCH request to + the Object API to update the payment status of a submission. This JSON will be nested in the ``record.data.payment`` field. + +#. Click **Opslaan** + +The Objects API configuration is now complete and can be selected as registration backend in the form builder. +When doing so, the corresponding objecttype and objecttype version will have to be configured. + +.. versionchanged:: 2.6.0 + + The objecttype URL and version should be configured at the form level, and can't be configured globally. + +Using the *Legacy (v1)* configuration +===================================== + +When using a the legacy configuration, the JSON template (either the global default configured above or +the one specified at the form level) will be rendered a fixed input (e.g. the submission variables, the payment status). + +Using this legacy format is discouraged due to the limited customization it offers. + Below is an example of the contents in the ``record.data`` attribute in the Objects API. The top-level has meta-data about the form submission, and the ``data`` element holds the submitted form values, nested within each step (using the step-slug as key): @@ -159,91 +287,96 @@ Objects API. The top-level has meta-data about the form submission, and the } } +Using the *Variables mapping (v2)* configuration +================================================ -To configure the Objects API follow these steps: +When using the variables mapping configuration, each variable can be mapped to a specific location in the object type +JSON Schema. This configuration takes place in the **Variables** tab. To demonstrate how variables can be configured, +we will assume the following JSON Schema defines the object type being used: -#. In Open Forms, navigate to: **Configuration** > **Services** -#. Create a service for the Objects API (ORC) where the form data will be registered. +.. code-block:: json - a. Click **Service toevoegen**. - b. Fill out the form: + { + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "payment_completed": {"type": "boolean"}, + "data": { + "type": "object", + "properties": { + "firstName": {"type": "string"}, + "age": {"type": "integer"} + } + } + } + } - * **Label**: *Fill in a human readable label*, for example: ``My Objects API`` - * **Type**: Select the type: ``ORC`` - * **API root url**: The root of this API, *for example* ``https://example.com/objecten/api/v1/`` +.. note:: - * **Authorization type**: Select the option: ``API Key`` - * **Header key**: Fill in ``Authorization`` - * **Header value**: Fill in ``Token `` where ```` is replaced by the token provided by the backend service - * **OAS**: URL that points to the OAS, same URL as used for **API root url** with ``/schema/openapi.yaml`` added to it - *for example:* ``https://example.com/objecten/api/v1/schema/openapi.yaml`` + The JSON Schema is parsed internally by Open Forms. For best results, your schema should + follow these guidelines: - * **NLX**: Support for NLX can be selected here if enabled in the installation - * **User ID**: Audit trail user ID, usually same as the Client ID - * **User representation**: *For example:* ``Open Forms`` + - If possible, define a ``"$schema"`` URI pointing to the specification you are using. If not specified, + Open Forms will assume the latest specification (*2020-12*) applies, which might not be compatible. + - Do not omit the ``"type"`` key (in our case, ``"object"``). Only defining ``"properties"`` is not enough, + as having ``"type"`` unspecified means any type of data can be set. + - Using references is supported, but shouldn't point to an external entity. Be sure to use the ``$ref`` + keyword to point to a specific reference. - c. Click **Opslaan** and repeat to create configuration for the other component. +We will also assume the form has one step with two components defined: -#. Create a second service, for the Documentregistratiecomponent (DRC) where the PDF summary and form attachment documents will be stored. +- A text field with a key of ``userName``. +- A number field with a key of ``userAge``. - a. Click **Service toevoegen**. - b. Fill out the form: +The **Variables** tab should look like the following: - * **Label**: *For example:* ``Documenten`` - * **Type**: Select the type: ``DRC`` - * **API root url**: The root of this API, *for example* ``https://example.com/documenten/api/v1/`` +.. image:: _assets/variables_tab.png - * **Client ID**: Fill the value provided by the backend service *For example:* ``open-forms`` - * **Secret**: Fill the value provided by the backend service - * **Authorization type**: Select the option: ``ZGW client_id + secret`` - * **OAS**: URL that points to the OAS, same URL as used for **API root url** with ``/schema/openapi.yaml`` added to it - *for example:* ``https://example.com/documenten/api/v1/schema/openapi.yaml`` +Mapping variables +----------------- - * **NLX**: Support for NLX can be selected here if enabled in the installation - * **User ID**: Audit trail user ID, usually same as the Client ID - * **User representation**: *For example:* ``Open Forms`` +Each variable needs to be mapped to a target individually. To do so, click the edit icon in the +registration column. A modal should open with the following content: -#. Create a third service, for the Zaaktypecatalogus (ZTC). This is needed to retrieve Informatieobjecttypen. +.. image:: _assets/objects_api_modal.png - a. Click **Service toevoegen**. - b. Fill out the form: +For each variable, only the compatible JSON Schema targets (in our case, *data > firstName*) will be presented. +Once selected, click **Save** and do the same for the ``userAge`` variable. - * **Label**: *For example:* ``Catalogi`` - * **Type**: Select the type: ``ZTC`` - * **API root url**: The root of this API, *for example* ``https://example.com/catalogi/api/v1/`` +To be able to map register "meta" information about the submission (such as the payment completion), +the Objects API registration provides *registration variables*. These are only available during registration, +and behaves the same way other variables do. To configure a mapping for the ``"payment_completed"`` JSON Schema target, +go to the **Registration** tab (next to **Static**) and configure the *Payment completed* variable by mapping it to +``payment_completed`` (this should be the only option available). - * **Client ID**: Fill the value provided by the backend service *For example:* ``open-forms`` - * **Secret**: Fill the value provided by the backend service - * **Authorization type**: Select the option: ``ZGW client_id + secret`` - * **OAS**: URL that points to the OAS, same URL as used for **API root url** with ``/schema/openapi.yaml`` added to it - *for example:* ``https://example.com/catalogi/api/v1/schema/openapi.yaml`` +Registration result +------------------- - * **NLX**: Support for NLX can be selected here if enabled in the installation - * **User ID**: Audit trail user ID, usually same as the Client ID - * **User representation**: *For example:* ``Open Forms`` +With the mapping configuration provided above, the payload sent to the Objects API will look like the following: -#. Navigate to **Configuration** > **Overview**. In the **Registration plugin** group, click on **Configuration** for the **Objects API registratie** line. -#. Enter the following details: +.. code-block:: json - * **Objects API**: Select the Objects API (ORC) service created above - * **Documenten API**: Select the Documentregistratiecomponent (DRC) service created above - * **Catalogi API**: Select the Zaaktypecatalogus (ZTC) service created above - * **Objecttype**: Fill in the default URL of the ProductAanvraag OBJECTTYPE in the Objecttypes API *For example* ``https://example.com/api/v1/objecttypes`` - * **Objecttype version**: Fill in the default version of the OBJECTTYPE in the Objecttypes API *For example:* ``1`` - * **Productaanvraag type**: Fill in the type of ProductAanvraag *For example:* ``terugbelnotitie`` - * **Submission report informatieobjecttype**: Fill in the default URL of the INFORMATIEOBJECTTYPE for the submission report in the Catalogi API *For example* ``https://example.com/api/v1/informatieobjecttypen/1/`` - * **Upload submission CSV**: Indicate whether or not the submission CSV should be uploaded to the Documenten API by default (can be overridden per form) - * **Submission report CSV informatieobjecttype**: Fill in the default URL of the INFORMATIEOBJECTTYPE for the submission report CSV in the Catalogi API *For example* ``https://example.com/api/v1/informatieobjecttypen/2/`` - * **Attachment informatieobjecttype**: Fill in the default URL of the INFORMATIEOBJECTTYPE for the submission attachments in the Catalogi API *For example* ``https://example.com/api/v1/informatieobjecttypen/3/`` - * **Organisatie RSIN**: Fill the RSIN to be referred to in the created objects. *For example:* ``123456789`` - * **JSON content template**: This is a template for the JSON that will be sent to the Object API nested in the - ``record.data`` field. - * **Payment status update JSON template**: This is a template for the JSON that will be sent with a PATCH request to - the Object API to update the payment status of a submission. This JSON will be nested in the ``record.data.payment`` field. + { + "type": "https://example.com/objecttypen/api/v2/objecttypes/7e6a98c3-bf02-41a6-8835-5367f6099780", + "record": { + "typeVersion": 1, + "data": { + "payment_completed": true, + "data": { + "firstName": "Filled first name", + "age": 20 + } + }, + "startAt": "2024-01-01" + } + } -#. Click **Opslaan** +Mapping a variable to the ``"geometry"`` component +-------------------------------------------------- -The Objects API configuration is now complete and can be selected as registration backend in the form builder. +As shown in the image above, it is possible to map a specific variable (usually a Map component) +to the ``"record.geometry"`` target. When this option is selected, the variable will appear as the +geometry component in the Objects API. Technical =========