==========================

This is an alpha release, meaning it is not finished yet or suitable for production use.

Upgrade procedure
-----------------

To upgrade to 3.3, please:

* ⚠️ Ensure you upgrade to Open Forms 3.2.x before upgrading to the 3.3 release series.
* ⚠️ Plan an upgrade window to address the warnings below.
* ⚠️ An automatic Ogone-to-Wordline merchant migration requires unique merchant PSPIDs. This is
  automatically verified *before* performing the upgrade, but ideally you should run the check script of
  older patch versions in preparation.

.. warning:: Schedule the upgrade for off-peak hours. Some of the database migrations
   need to lock the entire table and/or can take a long time depending on the amount of
   data. Some benchmarks on one million of rows in the submission variables table
   (~ 120K submissions) showed a migration time of around 20 seconds, so anywhere
   between 10 seconds - 5 minutes can be expected as a normal completion time depending
   on your data and available resources for the database.

.. warning::

    In this release, we reworked the internal data type information. To ensure submitted
    data of existing submissions is formatted correctly, submitted variables need to be
    processed. Note that we include this script instead of a data migration, so it can be
    run separately, as it can take up to an hour to complete the entire operation for large
    environments.

    .. code-block:: bash

        # in the container via ``docker exec`` or ``kubectl exec``:
        python /app/bin/fix_submission_value_variable_missing_fields.py

.. warning::

    For the email and confirmation templates, and the registration backends, we changed
    the way that the data is generated. In case of key conflicts between static, component,
    and user-defined variables, the static variables will take precedence. Previously, the
    component and user-defined variables would override the static variables. Our validation
    guards against the use of keys that are already present in the static variables, but this
    does not cover old forms and newly-added static variables.

Detailed changes
----------------

**New features**

* [:backend:`5268`] The registration plugins now support the ``children`` component type.
* [:backend:`5095`] When authenticated via OpenID Connect (DigiD, eHerkenning, organization), upon
  submission completion you are now logged out at the identity provider.
* [:backend:`4951`] The map component in the summary PDF is now an image instead of the textual location
  coordinates.
* [:backend:`5269`] You can now use the ``children`` component data as source data for a
  repeating group to provide additional information with the new "synchronize variables" logic
  action type.
* [:backend:`5575`] Added support for WMS tile layers in the map component, along
  with import/export functionality.
* [:backend:`5479`] The eIDAS (via OIDC) configuration is now simplified - you can specify
  which claims can contain a BSN and/or Pseudo ID.
* [:backend:`5060`] Redis Sentinel is now supported as high availability strategy for the background
  jobs message broker.
* [:backend:`5419`] Added prefill plugins for the new Yivi and eIDAS authentication backends.
* [:backend:`5515`] Yivi Attribute groups now have a system-generated unique identifier.
* [:backend:`5515`] You can now export and import Yivi attribute groups.
* [:backend:`5253`] The BRT (grey, pastel, water) background tile layers are now available by
  default in an Open Forms instance.
* [:backend:`5251`] The identifier field from the map background tile layer is now automatically
  populated from its label.

* [:backend:`4879`] Finished the support for Worldline as payment provider:

    - Support for Worldline's ``variant`` and ``descriptor`` fields.
    - The merchant reference is generated by Open Forms, similar to the Ogone plugin.
    - Ogone merchants are automatically migrated where possible.
    - Webhook configuration (if configured in a older patch release) is automatically migrated.
    - Moved the location in the admin of the feedback URL's used for the Worldline
      payment webhooks to the webhook configuration page.
    - Added a bulk action to migrate forms from Ogone to Wordline.

* [:backend:`5133`] Added a feature flag to enable the new *experimental* renderer.
* [:backend:`3999`] Added support for Open Telemetry metrics. All available metrics and details can be
  found in the "Observability" documentation.

**Bugfixes**

* [:backend:`5574`] Authentication-related static variables are no longer exposed to the
  confirmation email context.
* [:backend:`5464`] Fixed a crash that occurred when incomplete options were used in JSON schema generation.
* [:backend:`5605`] Fixed missing default value for DigiD ``loa`` causing a crash when trying to login.
* [:backend:`5572`] Fixed a crash in the StUF-ZDS registration plugin when another
  form has family member components in its configuration.
* [:backend:`5557`] Fixed uploaded filename sanitization.
* [:backend:`5439`] Removed warning message for deprecated feature to retrieve
  location via text fields.

**Project maintenance**

* [:backend:`5513`] Updated the OTel documentation and added various examples:

    - Basic nginx metrics and traces.
    - PostgreSQL metrics.
    - Redis metrics.

* [:backend:`5544`] Added documentation and examples on how to collect Flower metrics.
* Updated the documentation regarding the used SOAP operations for the StUF-ZDS plugin.
* Updated backend dependencies:

  - Bumped Redis to version 8 for CI builds and the docker-compose setup.
  - Bumped zgw-consumers to version 1.0.
  - Bumped @open-formulieren/formio-builder to 0.43.0.
  - Bumped mozilla-django-oidc-db to 0.25.1.
  - Bumped django-digid-eherkenning to 0.24.0.
  - Upgraded to Django security release 4.2.24.