Skip to content

Commit 11af63d

Browse files
johannesbattjesjohannesbattjes
committed
subscription page
1 parent 2f483f0 commit 11af63d

File tree

2 files changed

+128
-0
lines changed

2 files changed

+128
-0
lines changed

‎docs/gebruik-van-subscriptions-in-autorisaties.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Use of Subscriptions for Notifications
2+
3+
4+
## What is a subscription?
5+
6+
A subscription (abonnement) is a registration that allows an application to be automatically notified of changes.
7+
8+
## Examples
9+
10+
- A client application that needs to update information when a case is closed can receive notifications when the end status of cases is set;
11+
- A client that indexes documents can receive a notification when documents are created or changed.
12+
13+
## Recommendations
14+
15+
- Only create subscriptions for objects or events that are relevant to your application;
16+
- Restrict the number of notitifcations by using filter values in your subscriptions;
17+
- Regularly check whether the subscriptions are still needed and remove unnecessary subscriptions;
18+
- Keep the authorization structure in mind: subscriptions do not grant access to objects for which you do not have rights.
19+
20+
## Fields in the Subscription Creation Message
21+
22+
| Field Name | Description | Value Type | Example |
23+
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------ |
24+
| callbackUrl | The URL to which notifications will be sent. | URL | https://myapp.zaakgerichtwerken.nl/webhook |
25+
| auth | Value of bearer token | String | 8a0WWCKMgh1EIBlD2g1b6yQDtTpIgFYE |
26+
| kanalen | Channels to which you can subscribe. Standard channels are zaken, besluiten, documenten, zaaktypen, besluittypen, informatieobjecttypen and autorisaties | Array of Objects. Each object consists of filters (explained below) and the name of the channel | See below |
27+
28+
## Possible Values for Filters
29+
30+
Filters allows your application to limit the notifications it receives to only those changes that match specific criteria. Each channel supports its own set of filter fields. When evaluating filter values, they are combined using AND logic, meaning that only changes matching _all_ specified filters will trigger a notification. Below you will find the possible filter fields for each channel. The vule of a filter field always is a single string. If you need to subscribe to multiple values you can either create multiple subscriptions or an array of channels within a subscription.
31+
32+
### Filters for the Zaken channel
33+
34+
| Filter Key | Description | Allowed/Example Values |
35+
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
36+
| `#resource` | The resources as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | zaak, status, zaakobject, zaakinformatieobject, zaakeigenschap, rol, resultaat, zaakbesluit |
37+
| `#action` | The actions as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | create, update, destroy |
38+
| `bronorganisatie` | The rsin of the organization that initiated or owns the case in the field bronorganisatie | 000001375 |
39+
| `zaaktype` | URL's of the casetype versions of the case in the field zaaktype | https://ztc.zgw.nl/api/v1/zaaktypen/b1fac1a1-7117-1e50-1d01-d155a715f1ed |
40+
| `vertrouwelijkheidaanduiding` | The confidentiality indication of the case in field vertrouwelijkheidaanduiding | openbaar, beperkt_openbaar, intern, zaakvertrouwelijk, vertrouwelijk, confidentieel, geheim, zeer_geheim |
41+
| `zaaktype_identificatie` | The case type in the field 'identificatie' of zaaktype | Aanvraag beschikking behandelen |
42+
| `archiefstatus` | The archival status of the case in field archiefstatus | nog_te_archiveren, gearchiveerd, gearchiveerd_procestermijn_onbekend, overgedragen |
43+
| `archiefnominatie` | The archival nomination of the case in field archiefnominatie. | blijvend_bewaren, vernietigen |
44+
| `opdrachtgevende_organisatie` | The rsin of the organization that commissioned the case in field opdrachtgevendeOrganisatie | 123443210 |
45+
| `catalogus` | The URL of the catalog to which the case type belongs. | https://ztc.zgw.nl/api/v1/catalogi/fe0ff0r5-fdd1-5011-1177-d15ac1d1f1ed456 |
46+
| `domein` | The domain of the catalog in field domein of catalogus | VTH |
47+
| `is_eindzaakstatus` | Indicates whether the case is in its final status in field isEindstatus of statustype. | True, False |
48+
49+
### Filters for the Besluiten channel
50+
51+
| Filter Key | Description | Allowed/Example Values |
52+
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
53+
| `#resource` | the resources as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | besluit, besluitinformatieobject |
54+
| `#action` | The actions as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | create, update, destroy |
55+
| `besluittype` | URL of the decision type version in the field besluittype | https://ztc.zgw.nl/api/v1/besluittypen/ce571dae-f0c1-a1e5-115a-f1acc1d171e5 |
56+
| `verantwoordelijke_organisatie` | Rsin ofthe organisation responsible for the decision in field verantwoordelijkeOrganisatie | 010110100 |
57+
| `besluittype_omschrijving` | The decision type in field omschrijving of besluittype | Beschikken op aanvraag |
58+
| `catalogus` | The URL of the catalog in field catalogus of besluittype | https://ztc.zgw.nl/api/v1/catalogi/fe0ff0r5-fdd1-5011-1177-d15ac1d1f1ed |
59+
| `domein` | The domain of the catalog in field domein of catalogus | VTH |
60+
61+
### Filters for the Documenten channel
62+
63+
| Filter Key | Description | Allowed/Example Values |
64+
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
65+
| `#resource` | the resources as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | enkelvoudiginformatieobject, gebruiksrechten, verzending |
66+
| `#action` | The actions as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | create, update, destroy |
67+
| `bronorganisatie` | The rsin of the organization that initiated or received and owns the document in the field bronorganisatie | 813264571 |
68+
| `informatieobjecttype` | URL of the information object type version in field informatieobjecttype | https://ztc.zgw.nl/api/v1/informatieobjecttypen/cadd1ce5-5a1a-7070-dabb-c1a551f1ab1e |
69+
| `vertrouwelijkheidaanduiding` | Confidentiality indication in field vertrouwelijkheidaanduiding | openbaar, beperkt_openbaar, intern, zaakvertrouwelijk, vertrouwelijk, confidentieel, geheim, zeer_geheim |
70+
| `informatieobjecttype_omschrijving` | Document type in field omschrijving of informatieobjecttype | Bijlage bij verzoek |
71+
| `catalogus` | The URL of the catalog in field catalogus of informatieobjecttype | https://ztc.zgw.nl/api/v1/catalogi/fe0ff0r5-fdd1-5011-1177-d15ac1d1f1ed |
72+
| `domein` | The domain of the catalog in field domein of catalogus | VTH |
73+
| `status` | Status of the document in field status | in_bewerking, ter_vaststelling, definitief, gearchiveerd |
74+
| `inhoud_is_vervallen` | Whether the content has expired in field inhoudIsVervallen | True, False |
75+
76+
### Filters for the Zaaktypen channel
77+
78+
| Filter Key | Description | Allowed/Example Values |
79+
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
80+
| `#resource` | the resources as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | zaaktype |
81+
| `#action` | The actions as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | create, update, destroy |
82+
| `catalogus` | The URL of the catalog in field catalogus | https://ztc.zgw.nl/api/v1/catalogi/fe0ff0r5-fdd1-5011-1177-d15ac1d1f1ed |
83+
| `domein` | The domain of the catalog in field domein of catalogus | VTH |
84+
85+
### Filters for the Informatieobjecttypen channel
86+
87+
| Filter Key | Description | Allowed/Example Values |
88+
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
89+
| `#resource` | the resources as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | informatieobjecttype |
90+
| `#action` | The actions as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | create, update, destroy |
91+
| `catalogus` | The URL of the catalog in field catalogus | https://ztc.zgw.nl/api/v1/catalogi/fe0ff0r5-fdd1-5011-1177-d15ac1d1f1ed |
92+
| `domein` | The domain of the catalog in field domein of catalogus | VTH |
93+
94+
### Filters for the Besluittypen channel
95+
96+
| Filter Key | Description | Allowed/Example Values |
97+
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
98+
| `#resource` | the resources as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | besluittype |
99+
| `#action` | The actions as listed in the ZGW Open Api Specification, and presented in the resource field in the notification message itself | create, update, destroy |
100+
| `catalogus` | The URL of the catalog in field catalogus | https://.../catalogi/fe0ff0r5-fdd1-5011-1177-d15ac1d1f1ed |
101+
| `domein` | The domain of the catalog in field domein of catalogus | VTH |
102+
103+
## Example: get a notification when the case in the VTH domain has closed
104+
105+
```json
106+
{
107+
"callbackUrl": "https://myapp.zaakgerichtwerken.nl/webhook",
108+
"auth": "8a0WWCKMgh1EIBlD2g1b6yQDtTpIgFYE",
109+
"kanalen": [
110+
{
111+
"filters": {
112+
"domein": "VTH",
113+
"is_eindzaakstatus": "True"
114+
},
115+
"naam": "zaken"
116+
}
117+
]
118+
}
119+
```
120+
121+
## More information
122+
123+
See the general documentation on [notifications](https://vng-realisatie.github.io/gemma-zaken/ontwikkelaars/handleidingen-en-tutorials/notificeren) and [API notifications](https://vng-realisatie.github.io/gemma-zaken/standaard/notificaties/redoc-1.0.0).

‎sidebars.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@ const sidebars: SidebarsConfig = {
66
"api-versions",
77
"usage-of-clientids",
88
"authorizations",
9+
{
10+
type: "doc",
11+
id: "gebruik-van-subscriptions-in-autorisaties",
12+
label: "Use of Subscriptions for Notifications"
13+
},
914
"version-header",
1015
"example-document-upload/example-document-upload",
1116
"ztc1_3problemsandsolutions"

0 commit comments

Comments
 (0)