diff --git a/docs/conf.py b/docs/conf.py index 32c6fe8ce7..401d56c6ef 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -78,6 +78,10 @@ "https://zgw-consumers.readthedocs.io/en/latest/", None, ), + "objecttypes": ( + "https://objects-and-objecttypes-api.readthedocs.io/en/stable/", + None, + ), } # -- Options for HTML output ------------------------------------------------- diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst index 21c88b05a9..a766afeae8 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/index.rst @@ -7,20 +7,25 @@ There are many configuration options in Open Forms. Some of these are included in the core of Open Forms, and some are included by plugins. We cover various configuration topics that come with Open Forms by default. -Initial configuration ---------------------- - Open Forms supports the ``setup_configuration`` management command, which allows loading configuration via YAML files. The shape of these files is described at :ref:`installation_configuration_cli`. +Initial configuration +--------------------- + .. toctree:: :maxdepth: 2 general/index +Plugins +------- + +Many of the plugins in Open Forms require some technical configuration before you can +use them in forms. The technical requirements are grouped by functionality module. + .. toctree:: :maxdepth: 2 - :caption: Plugins authentication/index payment/index diff --git a/docs/configuration/prefill/_assets/update_existing_object.png b/docs/configuration/prefill/_assets/update_existing_object.png deleted file mode 100644 index 1959fb0714..0000000000 Binary files a/docs/configuration/prefill/_assets/update_existing_object.png and /dev/null differ diff --git a/docs/configuration/prefill/objects_api.rst b/docs/configuration/prefill/objects_api.rst index 8760846f71..dd9b96b57f 100644 --- a/docs/configuration/prefill/objects_api.rst +++ b/docs/configuration/prefill/objects_api.rst @@ -1,59 +1,127 @@ -.. todo:: This feature is still in development and not ready for production yet. - .. _configuration_prefill_objects_api: =========== Objects API =========== -The `Objects API`_ stores data records of which the structure and shape are defined by a particular object type -definition in the `Objecttypes API`_. These records can be used to pre-fill form fields if an object reference is -passed when the form is started. +*This plugin is also known as the "product prefill" feature.* + +The `Objects API`_ stores data records of which the structure and shape are defined by a +particular object type definition in the `Objecttypes API`_. These records can be used +to pre-fill form fields if an object reference is passed when the form is started. .. note:: - The service may contain sensitive data. It is advised to require DigiD/eHerkenning authentication on the form. You - should be careful with how you pass the object references to the customers and set up the object type in a way that - makes authentication checks possible (e.g. by storing the expected BSN or KVK number). + The service likely contains sensitive data. It is required to use authentication on + the form, as this information is used to test ownership of the referenced object. -.. _`Objects API`: https://objects-and-objecttypes-api.readthedocs.io/en/latest/ -.. _`Objecttypes API`: https://objects-and-objecttypes-api.readthedocs.io/en/latest/ +What does the Open Forms administrator need? +============================================ +* An instance of the `Objecttypes API`_ with: + + - an API token to access the API from Open Forms + - one or more objecttypes + +* An instance of the `Objects API`_ (v2.2+) with: + + - (API) access to the above Objecttypes API + - an API token to access the Objects API from Open Forms + - read permissions for the relevant Objecttypes - Open Forms reads records. Configuration ============= -1. In Open Forms, navigate to: **Forms** -2. Click **Add form** -3. Define the necessary form details and add the desired components -4. Navigate to: **Variables** tab -5. Navigate to: **User defined** subtab -6. Click **Add variable** and fill in the data from the available options: +Configuration is similar to :ref:`its registration counterpart `, +but only the objecttypes and objects services are required. - * **Plugin**: Choose the *Objects API* plugin - * **API Group**: Select the appropriate API group. These API groups should be set up - by an administrator, via **Admin** > **Configuration** > **Prefill plugins** > - **Objects API** > **Manage API groups** - * **Objecttype**: Select the expected object type from the dropdown. - * **Mappings**: Configure which property from the Objects API record needs to be - assigned to which form variable. +.. tip:: You can re-use the same API groups that are used for the registration plugin. - For each form variable you want to pre-fill, add a new mapping. Then, on the left - select the desired form variable, and on the right you can specify which property - from the object type contains the value. +To configure the Objects API follow these steps: -7. Click **Save** -8. Save the form +#. In Open Forms, navigate to: **Configuration** > **Services** +#. Create a service for the Objects API (ORC) where the form data will be registered. -The Objects API configuration is now complete. + a. Click **Service toevoegen**. + b. Fill out the form: -.. note:: + * **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 + + c. Click **Opslaan** and repeat to create configuration for the other component. + +#. 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`` - The Objects API prefill can be used not only for prefilling and showing the data to the user, - but it can also work together with the Objects API registration plugin - (see :ref:`Objects API configuration (English) `) in order to make - modifications to an existing object in the Objects API. This requires the form user to be the "owner" - of the object and the necessary configuration in the Objects API registration at the form level - (by choosing to update the existing object). + * **NLX**: Support for NLX can be selected here if enabled in the installation - .. image:: _assets/update_existing_object.png + c. Click **Opslaan** and repeat to create configuration for the other component. + +#. Navigate to **Configuration** > **Configuration overview**. In the + **Prefill plugins** group, click on **Manage API groups** for the **Objects API** line. + +#. Enter the following details: + + * **Name**: Enter a recognizable name, it will be displayed in various dropdowns. + * **Objects API**: Select the Objects API (ORC) service created above + * **Objecttypes API**: Select the Objecttypes API (ORC) service created above + + The remainder of the fields can be left empty. + +#. Click **Save** + +The Objects API configuration is now complete and can be selected as prefill backend in +the form builder. When doing so, you will be able to select the desired object type and +its version. + +Recommendations for the Objecttype JSON Schemas +=============================================== + +The same recommendations apply as for the +:ref:`registration plugin `. We +rely heavily on the JSON Schema specified in the object type. + +Technical +========= + +Open Forms requires Objects API v2.2 or newer and the Objecttypes API v2.0 or newer. + +================ =============================================== +Objects API Test status +================ =============================================== +2.2.x Manually verified +2.3.x Manually verified +2.4.x Manually verified, automated end-to-end testing +================ =============================================== + +================ =============================================== +Objecttypes API Test status +================ =============================================== +2.0.x Unknown +2.1.x Manually verified +2.2.x Manually verified, automated end-to-end testing +================ =============================================== + +.. _`Objects API`: https://objects-and-objecttypes-api.readthedocs.io/en/latest/ +.. _`Objecttypes API`: https://objects-and-objecttypes-api.readthedocs.io/en/latest/ diff --git a/docs/configuration/registration/objects.rst b/docs/configuration/registration/objects.rst index ea9b235a5f..2ac614d3af 100644 --- a/docs/configuration/registration/objects.rst +++ b/docs/configuration/registration/objects.rst @@ -127,15 +127,23 @@ To configure the Objects API follow these steps: * **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. +#. Navigate to **Configuration** > **Configuration overview**. In the + **Registration plugins** group, click on **Manage API groups** for the + **Objects API registratie** line. #. Enter the following details: + * **Name**: Enter a recognizable name, it will be displayed in various dropdowns. * **Objects API**: Select the Objects API (ORC) service created above * **Objecttypes API**: Select the Objecttypes API (ORC) service created above * **Documenten API**: Select the Documenten API (DRC) service created above * **Catalogi API**: Select the Zaaktypecatalogus (ZTC) service created above + * **Organisatie RSIN**: Fill the RSIN to use as "bronorganisatie" in Document uploads. + *For example:* ``123456789``. You an override this on a per-form basis. + + The following fields are deprecated - it's better to specify a catalogue and the + description of the document types instead. + * **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/``. You an override this on a @@ -150,8 +158,6 @@ To configure the Objects API follow these steps: INFORMATIEOBJECTTYPE for the submission attachments in the Catalogi API *For example* ``https://example.com/api/v1/informatieobjecttypen/3/``. You an override this on a per-form and per-file component basis. - * **Organisatie RSIN**: Fill the RSIN to use as "bronorganisatie" in Document uploads. - *For example:* ``123456789``. You an override this on a per-form basis. For the legacy configuration format, additional fields are available: @@ -176,7 +182,7 @@ When doing so, the corresponding objecttype and objecttype version will have to .. _configuration_registration_objects_objecttype_tips: Recommendations for the Objecttype JSON Schemas -================================================ +=============================================== The objecttype definition uses `JSON Schema `_, and this schema is processed by Open Forms. diff --git a/docs/manual/forms/examples/_assets/product_prefill_options_1.png b/docs/manual/forms/examples/_assets/product_prefill_options_1.png new file mode 100644 index 0000000000..c2a84e7560 Binary files /dev/null and b/docs/manual/forms/examples/_assets/product_prefill_options_1.png differ diff --git a/docs/manual/forms/examples/_assets/product_prefill_options_2.png b/docs/manual/forms/examples/_assets/product_prefill_options_2.png new file mode 100644 index 0000000000..77fd4af701 Binary files /dev/null and b/docs/manual/forms/examples/_assets/product_prefill_options_2.png differ diff --git a/docs/manual/forms/examples/_assets/product_prefill_options_3.png b/docs/manual/forms/examples/_assets/product_prefill_options_3.png new file mode 100644 index 0000000000..94073623b0 Binary files /dev/null and b/docs/manual/forms/examples/_assets/product_prefill_options_3.png differ diff --git a/docs/manual/forms/examples/camunda7.rst b/docs/manual/forms/examples/camunda7.rst index 73d6ceb9d0..37fbb49925 100644 --- a/docs/manual/forms/examples/camunda7.rst +++ b/docs/manual/forms/examples/camunda7.rst @@ -50,7 +50,7 @@ raketicoon linksonder. Formulier maken =============== -#. Maak een formulier aan met de volgende componenten in een formulier stap: +#. Maak een formulier aan met de volgende componenten in een formulierstap: * Getal-component met label **Leeftijd** en eigenschapsnaam **leeftijd** * Getal-component met label **Inkomen** en eigenschapsnaam **inkomen** diff --git a/docs/manual/forms/examples/index.rst b/docs/manual/forms/examples/index.rst index ed10944d6d..b7f6b709c7 100644 --- a/docs/manual/forms/examples/index.rst +++ b/docs/manual/forms/examples/index.rst @@ -13,6 +13,7 @@ Voorbeelden advanced_logic appointment_form prefill + objects_prefill calculations auth_static_variables repeating_groups diff --git a/docs/manual/forms/examples/objects_prefill.rst b/docs/manual/forms/examples/objects_prefill.rst new file mode 100644 index 0000000000..0e6989e320 --- /dev/null +++ b/docs/manual/forms/examples/objects_prefill.rst @@ -0,0 +1,170 @@ +.. _examples_objects_prefill: + +=========================================================== +Formulier met (product)gegevens voorinvullen (Objecten API) +=========================================================== + +In dit voorbeeld maken we een formulier bestaande uit één stap om een fictieve +vergunning aan te vragen. Er zijn gegevens van een eerdere aanvraag beschikbaar. + +In dit voorbeeld gaan we er van uit dat u een +:ref:`eenvoudig formulier ` kan maken. + +.. seealso:: De :ref:`technische configuratie ` moet + gedaan zijn om dit na te kunnen bouwen. + +Objecttype inrichten +==================== + +**Objecttypen API** + +:external+objecttypes:ref:`Maak een objecttype ` aan met het volgende +JSON Schema: + +.. code-block:: json + + { + "type": "object", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "required": [ + "bsn", + "identifier", + "startDate", + "endDate" + ], + "properties": { + "bsn": { + "type": "string", + "pattern": "^[0-9]{9}$", + "description": "A valid Dutch BSN (Burger Service Number) must be exactly 9 digits." + }, + "endDate": { + "type": "string", + "format": "date", + "description": "The end date in YYYY-MM-DD format." + }, + "remarks": { + "type": "string", + "description": "Optional remarks or notes for additional information." + }, + "startDate": { + "type": "string", + "format": "date", + "description": "The start date in YYYY-MM-DD format." + }, + "identifier": { + "type": "string", + "pattern": "^[A-Z0-9-]+$", + "description": "Unique identifier, typically composed of alphanumeric characters and dashes." + } + }, + "additionalProperties": false + } + +**Objecten API** + +Zorg dat het bovenstaande objecttype geregistreerd is, en maak dan in de Objecten API +een record aan met de volgende gegevens: + +.. code-block:: json + + { + "bsn": "123456782", + "endDate": "2024-12-31", + "remarks": "Test initieel object aanmaken.", + "startDate": "2024-12-13", + "identifier": "VOORBEELD-123" + } + +In de Objecten API zie je in de beheeromgeving van elke record het UUID, bijvoorbeeld +``05a0972b-c604-4b58-bd7d-6d456fb2987b``. + +.. tip:: Schrijf ergens het UUID van het object op - deze hebben we straks nodig. + +Formulier aanmaken +================== + +#. Maak een formulier aan met de volgende componenten in een formulierstap: + + * Tekstveld met label **Referentienummer**, niet verplicht. + * Datumveld met label **Van**, verplicht. + * Datumveld met label **Tot**, verplicht. + * Tekstvlak met label **Opmerkingen / extra informatie** + +#. Vink "Vereist authenticatie" aan op de formulierstap. +#. Selecteer één van de (demo) DigiD inlogopties bij de formulierauthenticatiemethoden. +#. Maak een gebruikersvariabele aan met de naam **Aanvraaggegevens** en datatype + ``object``. +#. Klik het potlood-icoontje aan in de kolom "Prefill" van de gebruikersvariabele. Je + kan nu de opties instellen. + + * Bij **Plugin** selecteer je "Objecten API". Er komen nu extra opties in beeld. + * Voor **API-groep** selecteer je de groep die aangemaakt is door een beheerder. + * Selecteer bij **Objecttype** het vergunning-objecttype wat eerder aangemaakt is. + * Selecteer bij **Versie** de meest recente versie. + * Bij **Path to auth attribute** kies je voor ``bsn``. De opties in deze lijst komen + uit het geselecteerde objecttype. + + De instellingen moeten op de onderstaande screenshot lijken: + + .. image:: _assets/product_prefill_options_1.png + :alt: Screenshot van de geselecteerde opties in de dropdowns. + + Vervolgens stellen we in waar de individuele attributen toegekend worden. + + * Scroll omlaag bij de instellingen totdat de "Variabelekoppleingen" in beeld staan. + * Klik op **Variabele toevoegen**, en kies voor de formuliervariabele + "Referentienummer", met brondpad ``identifier`` uit het objecttype. + * Klik op **Variabele toevoegen**, en kies voor de formuliervariabele + "Van", met brondpad ``startDate`` uit het objecttype. + * Klik op **Variabele toevoegen**, en kies voor de formuliervariabele + "Tot", met brondpad ``endDate`` uit het objecttype. + * Klik op **Variabele toevoegen**, en kies voor de formuliervariabele + "Opmerkingen / extra informatie", met brondpad ``remarks`` uit het objecttype. + + .. image:: _assets/product_prefill_options_2.png + :alt: Screenshot met de variabelekoppelingen in een tabel. + + * Klik op "Opslaan" om de instellingen te bewaren. + +#. Sla het formulier op. + +Formulier invullen +================== + +Om de vooringevulde gegevens te zien moet je de gegevensreferentie meegeven in de +formulierlink. Stel dat het formulier normaal beschikbaar is op +``https://forms.example.com/voorbeeld/``, dan wordt de nieuwe URL met +voorinvullen: + +.. code-block:: none + + https://forms.example.com/voorbeeld/?initial_data_reference=05a0972b-c604-4b58-bd7d-6d456fb2987b + +Hier gebruik je het UUID van het Object dat de brongegevens bevat. + +.. todo:: Fix https://github.com/open-formulieren/open-forms/issues/4918 as these URLs + aren't currently working as intended. + +Bonus: registreren in de Objecten API +===================================== + +Je kan dit formulier ook weer registreren in de Objecten API. Belangrijk hierbij is dat +je dan: + +* Bij de variabelen de ``auth_bsn`` statische variabele aan het ``bsn``-attribuut in het + objecttype koppelt. +* Bij de variabelen de registratievariabele ``public_reference`` aan het + ``identifier``-attribuut in het objecttype koppelt. + +Nu kan je objecten aanmaken, en deze gelijk weer gebruiken als bron voor +prefill-gegevens. + +.. tip:: Je kan ook het oorspronkelijke object wat voor prefill gebruikt is weer + bijwerken tijdens de registratie! Open hiervoor de registratie-opties voor de + Objecten API plugin en scroll naar "Update existing objects". Vink + **Bestaand object bijwerken** aan, en selecteer bij **Path to auth attribute** weer + het ``bsn``-attribuut. + + .. image:: _assets/product_prefill_options_3.png + :alt: Screenshot van registratieopties die "bijwerken" in ingeschakelde stand toont. diff --git a/src/openforms/conf/locale/nl/LC_MESSAGES/django.po b/src/openforms/conf/locale/nl/LC_MESSAGES/django.po index 2833b36a78..687b86e928 100644 --- a/src/openforms/conf/locale/nl/LC_MESSAGES/django.po +++ b/src/openforms/conf/locale/nl/LC_MESSAGES/django.po @@ -11663,7 +11663,7 @@ msgstr "Geeft aan of gevoelige gegevens verwijders zijn van deze inzending." #: openforms/submissions/models/submission.py:263 msgid "initial data reference" -msgstr "ongeldige data-referentie" +msgstr "startdata-referentie" #: openforms/submissions/models/submission.py:266 msgid "" diff --git a/src/openforms/prefill/contrib/objects_api/plugin.py b/src/openforms/prefill/contrib/objects_api/plugin.py index 6414f02172..ee710fd688 100644 --- a/src/openforms/prefill/contrib/objects_api/plugin.py +++ b/src/openforms/prefill/contrib/objects_api/plugin.py @@ -9,7 +9,6 @@ from openforms.contrib.objects_api.clients import get_objects_client from openforms.contrib.objects_api.models import ObjectsAPIGroupConfig from openforms.contrib.objects_api.ownership_validation import validate_object_ownership -from openforms.registrations.contrib.objects_api.models import ObjectsAPIConfig from openforms.submissions.models import Submission from openforms.typing import JSONEncodable, JSONObject @@ -73,16 +72,7 @@ def get_config_actions(self): return [ ( _("Manage API groups"), - reverse( - "admin:registrations_objects_api_objectsapigroupconfig_changelist" - ), - ), - ( - _("Defaults configuration"), - reverse( - "admin:registrations_objects_api_objectsapiconfig_change", - args=(ObjectsAPIConfig.singleton_instance_id,), - ), + reverse("admin:objects_api_objectsapigroupconfig_changelist"), ), ]