.. SPDX-FileCopyrightText: 2024 Univention GmbH
..
.. SPDX-License-Identifier: AGPL-3.0-only

.. _data-objects-event:

Event objects
=============

The *Provisioning Service* produces *Event objects*
to notify interested consumers of changes in the :ref:`component-identity-store-directory-service`.
For every create, update, and delete operation on directory objects,
the *UDM Transformer* creates one *Event object*
that contains the object's state before and after the operation, along with some metadata.
This section provides detailed information about the *Event object*.

.. seealso::

   :ref:`overview-components-provision-service` in the components overview section
      for information about purpose and tasks.

   :ref:`data-objects-directory` in data objects section
      for information about *Directory objects*.

   :ref:`data-objects-udm` in data objects section
      for information about *UDM objects*.

.. _data-objects-event-structure:

Structure
---------

An *Event object* uses the following structure.
The structure and the fields are the same for each object realm.

:``publisher_name``: Name of component that generated the event data, for example ``"LDIF producer"``.

:``ts``: Timestamp in ISO 8601 format, for example ``"2024-09-12T17:34:43.441214"``.

:``realm``: The type of event. At the time of writing, only realm ``"udm"`` exists.

:``topic``: Sub-type of the event.
   In the case of the ``udm`` realm, this is the UDM object type.
   For example ``"users/user"``

:``body``: The payload of the message.
   Its content depends on the ``realm``.
   In the case of ``"udm"`` it's an object with two fields:

   :``old``: UDM object representation of the directory object before the operation.
   :``new``: UDM object representation of the directory object after the operation.

:``sequence_number``: The sequence number is an integer associated with the message.

:``num_delivered``: Number of times a consumer has retrieved the message from the *Provisioning Service* as integer value.
  A number higher than ``1`` may indicate that the consumer previously was unsuccessful to process the event and is retrying.

*Event objects* in the realm ``"udm"`` consist of two *UDM objects* in their body.
:numref:`data-objects-event-with-udm-objects-figure` shows this relationship.
The *UDM Transformer* in the *Provisioning Service* creates *Event objects* in the realm ``"udm"``.

.. _data-objects-event-with-udm-objects-figure:

.. figure:: /images/Event_data_with_UDM_object.*
   :target: ../_images/Event_data_with_UDM_object.svg
   :alt: Transformation from UDM data object to an event data object
   :width: 450px

   Transformation from UDM data object to an event data object

.. seealso::

   `ISO 8601 - Wikipedia <https://en.wikipedia.org/wiki/ISO_8601>`_
      for information about the internal standard covering the worldwide exchange
      and communication fo data and time-related data.

.. _data-objects-event-relations:

Consumers of Event objects
--------------------------

Consumers of the *Event object* are the *Provisioning Service* itself,
third-party applications and other Nubus components as consumers of the *Provisioning Service*.
The *Provisioning Service* uses the objects in different components:

* The :ref:`component-provisioning-service-prefill` provides initial data with the *Event object* for the consumer.
* The :ref:`component-provisioning-service-udm-transformer` creates the UDM object data of an *Event object* from LDAP data.
* The :ref:`component-provisioning-service-dispatcher` distributes *Event objects* to consumers based on the events ``realm`` and ``topic``.
* The :ref:`component-provisioning-service-consumer-messages-http-rest-api` allows consumers to retrieve event objects.

.. _data-objects-event-relations-figure:

.. figure:: /images/Event_data_object_relations.*
   :target: ../_images/Event_data_object_relations.svg
   :alt: Consumer of Event data object

   Consumer of Event data object

.. _data-objects-event-details:

Queues holding Event objects
----------------------------

In the *Provisioning Service* functional component,
the *Event object* passes through the following queues,
as shown in :numref:`data-objects-event-details-figure`.

#. Incoming queue
#. Queue for each consumer
#. Prefill Service queue for each consumer

After transforming directory objects to *UDM objects*,
the *UDM Transformer* adds an *Event object* to the *Incoming queue*.
The *Dispatcher* consumes the *Incoming queue* and
distributes the *Event objects* to the *Queue for each consumer*.
If multiple consumers have interest in the *Event object*,
the *Filter and duplicate events for consumers* function of the *Dispatcher* duplicates the *Event object*.
If the consumer registration asks for an initial data load,
the *Prefill Service* runs the *Populate initial data for each consumer*
and writes *Event objects* to the *Prefill Service queue for each consumer*.

.. _data-objects-event-details-figure:

.. figure:: /images/Event_data_object_details.*
   :target: ../_images/Event_data_object_details.svg
   :alt: Event data object queues

   Event data object queues

.. seealso::

   :ref:`component-provisioning-service-consumer-registration-http-rest-api` in Provisioning Service section
      for information about the consumer registration process.

   :ref:`component-provisioning-service-prefill` in Provisioning Service section
      for information about the *Prefill Service*.