Skip to content

Commit 945ce40

Browse files
GrabauskasGrabauskas
committed
Refactor notifications documentation structure and enhance content clarity
1 parent 13ea9ad commit 945ce40

File tree

7 files changed

+191
-108
lines changed

7 files changed

+191
-108
lines changed

‎docs/notifications/nrc-db-subscriptions.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: "Explanation of the Notification Database Tables for Subscriptions"
3+
description: "This document describes the subscription data model in the NRC database. It clarifies the usage of tables like kanalen, abonnementen, and filtervalues."
4+
keywords: [NRC, database, subscriptions, notifications, data model, kanalen, abonnementen, filtervalues, ZGW, webhook]
5+
slug: /notifications/notification-subscription-database-model
6+
---
7+
8+
# Notification Database: Subscription Data Model
9+
10+
This document outlines the subscription data model within the NRC database.
11+
12+
**Goal:** To clarify the relationship between tables, specifically focusing on the `abonnementkanalen` table. While this table may appear to contain duplicate records, this design is intentional and necessary for the flexible functioning of notification filters.
13+
14+
![ERD: Subscription Data Model](./nrc_db_subscriptions-1.png)
15+
16+
---
17+
18+
## 1. Kanalen
19+
20+
**OAS Resource:** [`kanaal`](https://vng-realisatie.github.io/gemma-zaken/standaard/notificaties/redoc-1.0.0#tag/kanaal/operation/kanaal_create)
21+
22+
The `kanalen` table represents the source of notifications (e.g., 'zaken' or 'besluiten' in the ZRC).
23+
24+
| Column | Description |
25+
| :--- | :--- |
26+
| **`id`** | **Primary Key.** Unique identifier for the kanaal. |
27+
| **`naam`** | The name of the channel (e.g., `zaken`, `besluiten`). |
28+
| **`documentatielink`** | URL pointing to the documentation for this specific channel. |
29+
| **`filters`** | A list of available attributes that can be used to filter subscriptions for this channel. |
30+
31+
---
32+
33+
## 2. Abonnementen
34+
35+
**OAS Resource:** [`abonnement`](https://vng-realisatie.github.io/gemma-zaken/standaard/notificaties/redoc-1.0.0#tag/abonnement/operation/abonnement_create)
36+
37+
The `abonnementen` table stores the actual subscriptions for ZGW notifications received via POST requests.
38+
39+
| Column | Description |
40+
| :--- | :--- |
41+
| **`id`** | **Primary Key.** Unique identifier for the subscription. |
42+
| **`callbackurl`** | The full webhook URL of the application where the notification must be sent. |
43+
| **`auth`** | The bearer token required by the webhook receiver for authorization. |
44+
| **`owner`** | The RSIN of the organization granting access to the application. |
45+
46+
---
47+
48+
## 3. Abonnementkanalen
49+
50+
**OAS Element:** `kanalen` array within `abonnement`.
51+
52+
This table establishes an **N:M (Many-to-Many)** relationship between `abonnementen` and `kanalen`.
53+
54+
> **Key Concept:** The Primary Key (`id`) of this table is referenced by the `filtervalues` table. This architecture allows a single subscription to link to the *same* `kanaal` multiple times. While this looks like duplicate data, it allows different sets of `filtervalues` to be applied to the same channel within one subscription.
55+
56+
| Column | Description |
57+
| :--- | :--- |
58+
| **`id`** | **Primary Key.** Referenced by `filtervalues`. |
59+
| **`abonnement_id`** | **Foreign Key.** Points to the parent subscription in `abonnementen`. |
60+
| **`kanaal_id`** | **Foreign Key.** Points to the source channel in `kanalen`. |
61+
62+
---
63+
64+
## 4. Filtervalues
65+
66+
**OAS Element:** `filters` element within `abonnement`.
67+
68+
To prevent message flooding, subscriptions often restrict which notifications they receive. The `filtervalues` table stores these restrictions.
69+
70+
| Column | Description |
71+
| :--- | :--- |
72+
| **`id`** | **Primary Key.** |
73+
| **`abonnement_kanaal_id`** | **Foreign Key.** Links to the `abonnementkanalen` table. |
74+
| **`key`** | The filter name. Valid values are listed in `kanalen.filters`. <br /> Special values include:<br />• `#resource`: The resource triggering the event.<br />• `#actie`: The event type (e.g., create, destroy). |
75+
| **`value`** | The specific value to match against. |
76+
77+
### Example Usage
78+
79+
If you want to filter for a specific domain, the definition for the **zaken** channel might look like this:
80+
81+
* **Key:** `domein`
82+
* **Value:** `VTH`
83+
84+
*Result: The notification is delivered only if the 'zaak' belongs to a 'zaaktype' within the 'VTH' domain.*
85+
86+
---
87+
88+
## Logic: Combining Filters
89+
90+
The data model supports complex filtering logic by combining multiple `filtervalues` and multiple `abonnementkanalen`.
91+
92+
### The Logic Rule
93+
94+
> 1. **Inside** a single `abonnementkanaal`: Filters are combined with **AND**.
95+
> 2. **Between** different `abonnementkanalen` (for the same subscription): Logic is combined with **OR**.
96+
97+
### Scenario: "Create OR Delete"
98+
99+
A client application wants to receive notifications from the `zaken` channel *only* when a `zaakinformatieobject` is **created** OR **deleted**.
100+
101+
**Abonnementkanalen ID: 1** (The "Create" Condition)
102+
103+
* Filter A: `key='#resource'`, `value='zaakinformatieobject'`
104+
* Filter B: `key='#actie'`, `value='create'`
105+
* *Logic: Resource is object **AND** action is create.*
106+
107+
**Abonnementkanalen ID: 2** (The "Delete" Condition)
108+
109+
* Filter A: `key='#resource'`, `value='zaakinformatieobject'`
110+
* Filter B: `key='#actie'`, `value='destroy'`
111+
* *Logic: Resource is object **AND** action is destroy.*
112+
113+
**Final Result:**
114+
If (Object created) **OR** (Object destroyed) then **Send Notification**.

‎docs/notifications/nrc-introduction.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: "Introduction to Notifications"
3+
description: "Overview of the ZGW Notifications (NRC) system, enabling real-time updates via webhooks."
4+
keywords: [notifications, introduction, NRC, webhooks, ZGW, API, OneGround, subscription]
5+
slug: /notifications/introduction
6+
---
7+
8+
# Introduction to Notifications
9+
10+
The Notifications system (often referred to as **NRC** or Notification Routing Component) is a crucial part of the ZGW API landscape provided by OneGround. It allows client applications to stay synchronized with the state of data within the ZGW APIs without the need for constant polling.
11+
12+
## How it works
13+
14+
When a relevant event occurs within a ZGW API (such as the creation of a Case/Zaak, or an update to a Document/EnkelvoudigInformatieObject), a notification is generated. The NRC is responsible for routing these notifications to the appropriate subscribers.
15+
16+
1. **Events**: Changes occur in the source systems (OpenZaak, OpenNotificaties, etc.).
17+
2. **Notifications**: A notification message is published.
18+
3. **NRC**: The component enables the routing and delivery of these messages.
19+
4. **Subscribers**: External applications receive these updates via **webhooks**.
20+
21+
## Getting Started
22+
23+
To receive notifications, your application needs to:
24+
25+
1. **Expose a Webhook Endpoint**: A public or internally accessible URL that can accept HTTP POST requests containing the notification payload.
26+
2. **Create a Subscription**: Register your interest in specific events (channels) and define filters to receive only relevant updates.
27+
28+
## Documentation Overview
29+
30+
We have detailed guides to help you integrate with the Notifications system:
31+
32+
* **[Usage Guide](./nrc-subscriptions-use)**: Learn how to create subscriptions and filter messages for specific channels like Zaken or Documenten.
33+
* **[Data Models](./nrc-db-subscriptions)**: Understand the underlying database structure for subscriptions if you need deep insight into how channels and filters are stored.
34+
* **[Retries & Reliability](./nrc-retry-architecture)**: Information on how the system ensures delivery, including retry policies (Polly, Hangfire) and circuit breakers.
35+
36+
## Key Concepts
37+
38+
* **Kanaal (Channel)**: Represents a stream of messages, usually tied to a specific resource type (e.g., 'zaken', 'documenten').
39+
* **Abonnement (Subscription)**: The registration that links a receiving application (via a callback URL) to a channel and set of filters.
40+
* **Notificatie**: The actual message payload describing the event.
41+
42+
## Official Standards (VNG)
43+
44+
The OneGround Notifications system is implemented according to the standards defined by VNG Realisatie. While this documentation covers the specific implementation and usage within OneGround, the official standards provide the complete specification:
45+
46+
* **[VNG Notificaties Standard](https://vng-realisatie.github.io/gemma-zaken/standaard/notificaties/)**
47+
The core specification for the Notifications API (Notificaties services). It defines the resources, behavior, and architecture of the notification system.
48+
49+
* **[VNG Notificaties Consumer Guide](https://vng-realisatie.github.io/gemma-zaken/standaard/notificaties-consumer/)**
50+
A guide specifically for "consumers" — applications that subscribe to and receive notifications. This resource provides sequence diagrams and rules for handling notifications correctly.
51+
52+
For further technical details, please refer to the specific pages in this section.

docs/notifications-architecture.md renamed to docs/notifications/nrc-retry-architecture.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
title: "How does the retry system for notitifations work?"
33
description: "Overview of the Notifications system architecture, detailing retry strategies with Polly and Hangfire, circuit breaker patterns, and HTTP status code handling."
44
keywords: [notifications, architecture, polly, hangfire, circuit breaker, retry, webhook, OneGround, ZGW]
5+
slug: /notifications/notification-retry-architecture
56
---
67

78
# How does the retry system for notifications work?

docs/gebruik-van-subscriptions-in-autorisaties.md renamed to docs/notifications/nrc-subscriptions-use.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
title: "Use of Subscriptions for Notifications"
33
description: "A comprehensive guide on creating and managing subscriptions for ZGW API notifications, detailing filter options for various channels like Zaken, Besluiten, and Documenten."
44
keywords: [subscriptions, notifications, filters, ZGW, API, webhooks, callbacks, Zaken, Besluiten, Documenten, OneGround, Roxit]
5+
slug: /notifications/notification-subscription-usage-guide
56
---
67

78
# Use of Subscriptions for Notifications

docs/nrc_db_subscriptions-1.png renamed to docs/notifications/nrc_db_subscriptions-1.png

File renamed without changes.

‎docs/nrc-db-subscriptions.md‎

Lines changed: 0 additions & 90 deletions
This file was deleted.

‎sidebars.ts‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -7,28 +7,33 @@ const sidebars: SidebarsConfig = {
77
"usage-of-clientids",
88
"authorizations",
99
{
10-
type: "doc",
11-
id: "nrc-db-subscriptions",
12-
label: "Notification database tables for subscriptions"
13-
},
14-
{
15-
type: "doc",
16-
id: "gebruik-van-subscriptions-in-autorisaties",
17-
label: "Use of Subscriptions for Notifications"
18-
},
19-
{
20-
type: "doc",
21-
id: "notifications-architecture",
22-
label: "How does the retry system for notitifations work?"
10+
type: "category",
11+
label: "Notifications",
12+
link: {
13+
type: 'doc',
14+
id: 'notifications/nrc-introduction'
15+
},
16+
items: [
17+
{
18+
type: "doc",
19+
id: "notifications/nrc-subscriptions-use",
20+
label: "Usage Guide"
21+
},
22+
{
23+
type: "doc",
24+
id: "notifications/nrc-db-subscriptions",
25+
label: "Data Models"
26+
},
27+
{
28+
type: "doc",
29+
id: "notifications/nrc-retry-architecture",
30+
label: "Retries & Reliability"
31+
}
32+
]
2333
},
2434
"version-header",
2535
"example-document-upload/example-document-upload",
2636
"ztc1_3problemsandsolutions"
27-
// {
28-
// type: 'category',
29-
// label: 'Category',
30-
// items: ['usage-of-clientids'],
31-
// },
3237
]
3338
};
3439

0 commit comments

Comments
 (0)