.. _configuration_prefill_communication_preferences:

=========================
Communication preferences
=========================

The **Communication preferences** prefill plugin stores data records for digital addresses based
on a person's BSN or organization's KVK number, retrieved from a `Customer Interactions API`_.
These records can be used to populate the "customerProfile" form component.

.. note::

   The `Customer Interactions API`_ stores data related to the contacts between clients and the
   municipality. The API specifications aren't standardized, therefore Open Forms follows the
   `Customer Interactions API`_ specifications of `Open Klant`_.

   Information about the architecture and the vision of the API can also be found on the
   `VNG github`_.


What does the Open Forms administrator need?
============================================

* An instance of the `Open Klant`_ with:

    - an API token to access the API from Open Forms

* A form with a "Profile" component.

  .. note::

      The "Profile" component works only when the new renderer is enabled.


Configuration
=============

To use the Communication Preferences prefill plugin you need to configure the access to
`Customer Interactions API`_.

#. In Open Forms, navigate to: **Configuration** > **Services**
#. Create a service for the Customer Interactions API.

   a. Click **Add service**.
   b. Fill out the form:

      * **Label**: *Fill in a human readable label*, for example: ``My Customer Interactions API``
      * **Type**: Select the type: ``Klanten API``
      * **API root url**: The root of this API, *for example* ``https://example.com/klantinteracties/api/v1/``

      * **Authorization type**: Select the option: ``API Key``
      * **Header key**: Fill in ``Authorization``
      * **Header value**: Fill in ``Token <tokenValue>`` where ``<tokenValue>`` is replaced
        by the token provided by the Open Klant

   c. Click **Save**.

#. Navigate to **Configuration** > **Configuration overview**. In the
   **Prefill plugins** group, click on **Manage API groups** for the **Communication preferences**
   line.

#. Create a new API group for the `Customer Interactions API`_:

   a. Click **Add customer interactions API group**.
   b. Enter the following details:

      * **Name**: Enter a recognizable name, it will be displayed in various dropdowns.
      * **Customer Interactions API**: Select the service created above.

   c. Click **Save**


How it works
============

In order to enable the plugin you need to complete the configuration above. Next step is
to add the relevant component and a **user defined** form variable:

  * The component you need to add to the form is "Profile" from the special fields.
    This will automatically create a form variable of data type ``array``.
    This form variable will hold the data which the user submits.

  * Next step is to add a user defined variable that we call ``profilePrefill``.
    This variable is used for configuring the plugin and holding the pre-filled data from
    the `Customer Interactions API`_. In the Configuration popup select the API group
    created in the "Configuration" section and the profile form variable.

.. _configuration_prefill_communication_preferences_writing:

Writing to the Customer Interactions API
========================================

The communication preferences prefill configuration is also used to update communication preferences in the
Customer Interactions API. To enable it you need to check "Open Forms should update customer data after submission"
in the "Profile" component configuration.

When the form is submitted Open Forms records following data in the Customer Interactions API:

* klantcontact
* betrokkene
* onderwerpobject, where a public reference of the submission is stored
* digitaleadressen, where new communication preferences are stored if user has chosen "Sla mijn gegevens op
  voor de volgende keer." while filling the form.
* partij, if user is authenticated in the form, but unknown in the Customer Interactions API.

Technical
=========

========================= ==================
Service                   Supported versions
========================= ==================
Open Klant                2.14
========================= ==================


.. _`Customer Interactions API`: https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/maykinmedia/open-klant/master/src/openklant/components/klantinteracties/openapi.yaml
.. _`Open Klant`: https://open-klant.readthedocs.io/en/latest/
.. _`VNG github`: https://vng-realisatie.github.io/klantinteracties/