Merge pull request #556 from maykinmedia/feature/555-Send-zaakontkoppeld-events

[#555] Send zaak-ontkoppeld events

Author: stevenbal

docs/functionality/cloud_events.rst

@@ -8,7 +8,7 @@ Open Klant can emit cloud events when configured to do so via the
 
 Currently, Open Klant emits the following cloud event:
 
-* ``nl.overheid.zaken.zaak-gelinkt``: emitted when an ``Onderwerpobject`` is created that links to a
+* ``nl.overheid.zaken.zaak-gekoppeld``: emitted when an ``Onderwerpobject`` is created or updated that links to a
   Zaak (i.e. when ``codeObjecttype="zaak"`` in the ``onderwerpobjectidentificator`` field).
 
 Cloud events are only sent when both of the following are true:
@@ -18,14 +18,14 @@ Cloud events are only sent when both of the following are true:
 
 If either of these settings is missing, cloud events will **not** be emitted.
 
-Example of a ``nl.overheid.zaken.zaak-gelinkt`` cloud event in its current shape:
+Example of a ``nl.overheid.zaken.zaak-gekoppeld`` cloud event in its current shape:
 
 .. code-block:: json
 
     {
         "specversion": "1.0",
-        "type": "nl.overheid.zaken.zaak-gelinkt",
-        "source": "urn:nld:oin:01823288444:openzaak",
+        "type": "nl.overheid.zaken.zaak-gekoppeld",
+        "source": "urn:nld:oin:01823288444:openklant",
         "subject": "a7b3c8d9-e4f5-6a7b-8c9d-e0f1a2b3c4d5",
         "id": "f347fd1f-dac1-4870-9dd0-f6c00edf4bf7",
         "time": "2025-10-10T00:00:00Z",
@@ -42,3 +42,37 @@ Example of a ``nl.overheid.zaken.zaak-gelinkt`` cloud event in its current shape
 
 The shape of these cloud events and the actions that trigger them are still subject to
 change.
+
+In addition to linking events, Open Klant can also emit *unlink* events when a Zaak
+is no longer related to an Onderwerpobject.
+
+* ``nl.overheid.zaken.zaak-ontkoppeld``: emitted when a Zaak that was previously
+  linked becomes unlinked. This happens when an ``Onderwerpobject`` that pointed
+  to a Zaak is deleted, or otherwise changed such that the relationship with the
+  Zaak disappears.
+
+The payload of a ``nl.overheid.zaken.zaak-ontkoppeld`` event matches the shape of
+the original ``zaak-gekoppeld`` event so that Open Zaak can correctly identify
+and remove the corresponding ZaakObject relation.
+
+Example of a ``nl.overheid.zaken.zaak-ontkoppeld`` cloud event:
+
+.. code-block:: json
+
+    {
+        "specversion": "1.0",
+        "type": "nl.overheid.zaken.zaak-ontkoppeld",
+        "source": "urn:nld:oin:01823288444:openklant",
+        "subject": "a7b3c8d9-e4f5-6a7b-8c9d-e0f1a2b3c4d5",
+        "id": "f347fd1f-dac1-4870-9dd0-f6c00edf4bf7",
+        "time": "2025-10-10T00:00:00Z",
+        "datacontenttype": "application/json",
+        "data": {
+            "zaak": "urn:uuid:a7b3c8d9-e4f5-6a7b-8c9d-e0f1a2b3c4d5",
+            "linkTo": "http://open-klant.local:8000/klantinteracties/api/v1/onderwerpobjecten/5fee9673-216c-41e7-91d2-69a8d1526b9f",
+            "label": "Mijn Klantcontact Onderwerp",
+            "linkObjectType": "Onderwerpobject"
+        }
+    }
+
+*Note:* The ``subject`` field again contains the UUID of the Zaak.

src/openklant/cloud_events/constants.py

@@ -0,0 +1,2 @@
+ZAAK_GEKOPPELD = "nl.overheid.zaken.zaak-gekoppeld"
+ZAAK_ONTKOPPELD = "nl.overheid.zaken.zaak-ontkoppeld"