From 0bca4af2375d1caea96b5089b70d998b23259bd7 Mon Sep 17 00:00:00 2001 From: Giedrius Grabauskas <43740166+Grabauskas@users.noreply.github.com> Date: Mon, 19 Jan 2026 11:05:39 +0200 Subject: [PATCH 1/3] Update documentation titles, descriptions, and keywords for clarity and consistency across various OneGround API guides --- docs/about-oneground.md | 19 +---- docs/api-versions.md | 18 +--- docs/authorizations.md | 15 +--- .../example-document-upload.md | 4 +- ...bruik-van-subscriptions-in-autorisaties.md | 6 ++ docs/notifications-architecture.md | 83 +++++++++++++++++++ docs/usage-of-clientids.md | 15 +--- docs/version-header.md | 5 +- docs/ztc1_3problemsandsolutions.md | 4 +- 9 files changed, 110 insertions(+), 59 deletions(-) create mode 100644 docs/notifications-architecture.md diff --git a/docs/about-oneground.md b/docs/about-oneground.md index 79ba2a6..ebe8e70 100644 --- a/docs/about-oneground.md +++ b/docs/about-oneground.md @@ -1,20 +1,7 @@ --- -title: "About OneGround - Complete ZGW API Implementation" -description: "OneGround is a comprehensive implementation of Dutch ZGW APIs for case management (Zaakgericht Werken). Learn about ZRC, DRC, ZTC, BRC, NRC, AC components, features, and how to get started with OneGround." -keywords: - - OneGround - - ZGW API - - Zaakgericht Werken - - Dutch case management - - ZRC - - DRC - - ZTC - - BRC - - NRC - - AC - - VNG standards - - government APIs - - API documentation +title: "About OneGround" +description: "Overview of OneGround, a case-oriented API implementation by Roxit, covering its attended and unattended versions, key characteristics, and compliance with ZGW standards." +keywords: ["OneGround", "Roxit", "ZGW", "API", "Case Oriented", "VNG", "SaaS", "Open Source", "ISO-16175"] --- # About OneGround diff --git a/docs/api-versions.md b/docs/api-versions.md index 072dcfb..0662d3c 100644 --- a/docs/api-versions.md +++ b/docs/api-versions.md @@ -1,19 +1,7 @@ --- -title: "ZGW API Versions Supported by OneGround" -description: "Complete overview of supported ZGW API versions in OneGround including ZRC, DRC, ZTC, BRC, NRC, and AC. View current, maintenance, and end-of-life versions with release dates and migration timelines." -keywords: - - ZGW API versions - - OneGround versions - - ZRC versions - - DRC versions - - ZTC versions - - BRC versions - - NRC versions - - AC versions - - API compatibility - - version support - - migration guide -hide_table_of_contents: true +title: "Supported ZGW API Versions" +description: "A list of supported ZGW API versions (AC, NRC, DRC, ZRC, BRC, ZTC) in OneGround, including their current support status and release dates." +keywords: ["API Versions", "ZGW", "AC", "NRC", "DRC", "ZRC", "BRC", "ZTC", "Support Status", "Lifecycle"] --- # Supported ZGW API's versions by OneGround diff --git a/docs/authorizations.md b/docs/authorizations.md index 73436d2..288ef84 100644 --- a/docs/authorizations.md +++ b/docs/authorizations.md @@ -1,16 +1,7 @@ --- -title: "Authorization Management for ZGW APIs in OneGround" -description: "Learn how to configure and manage authorizations for ClientIDs in OneGround ZGW APIs. Set up application permissions, authorization profiles, and secure access controls for your ZGW components." -keywords: - - authorization - - permissions - - ClientID authorization - - ZGW security - - OneGround access control - - application permissions - - authorization profiles - - API security - - access management +title: "Authorizations" +description: "Explanation of how authorizations, applications, and Client IDs function within OneGround, including configuration guidelines and tool limitations." +keywords: ["Authorizations", "OneGround", "ClientID", "Application", "ZGW", "Configuration", "Security"] --- # Authorizations diff --git a/docs/example-document-upload/example-document-upload.md b/docs/example-document-upload/example-document-upload.md index 1ca4842..9aabdab 100644 --- a/docs/example-document-upload/example-document-upload.md +++ b/docs/example-document-upload/example-document-upload.md @@ -1,5 +1,7 @@ --- -title: "Example document upload" +title: "Example Document Upload" +description: "Step-by-step guide and Postman example for uploading documents in parts (bestandsdelen) to the DRC API in OneGround." +keywords: ["Document Upload", "DRC", "ZGW", "OneGround", "File Parts", "Bestandsdelen", "Postman", "API"] --- Attached is an example [Postman project](./examplepm.json) with a sequence for document upload in parts (bestandsdelen). diff --git a/docs/gebruik-van-subscriptions-in-autorisaties.md b/docs/gebruik-van-subscriptions-in-autorisaties.md index ef191cf..fc7451c 100644 --- a/docs/gebruik-van-subscriptions-in-autorisaties.md +++ b/docs/gebruik-van-subscriptions-in-autorisaties.md @@ -1,3 +1,9 @@ +--- +title: "Use of Subscriptions for Notifications" +description: "A comprehensive guide on creating and managing subscriptions for ZGW API notifications, detailing filter options for various channels like Zaken, Besluiten, and Documenten." +keywords: [subscriptions, notifications, filters, ZGW, API, webhooks, callbacks, Zaken, Besluiten, Documenten, OneGround, Roxit] +--- + # Use of Subscriptions for Notifications ## What is a subscription? diff --git a/docs/notifications-architecture.md b/docs/notifications-architecture.md new file mode 100644 index 0000000..4f18a4a --- /dev/null +++ b/docs/notifications-architecture.md @@ -0,0 +1,83 @@ +--- +title: "Notifications Architecture" +description: "Overview of the Notifications system architecture, detailing retry strategies with Polly and Hangfire, circuit breaker patterns, and HTTP status code handling." +keywords: [notifications, architecture, polly, hangfire, circuit breaker, retry, webhook, OneGround, ZGW] +--- + +# Notifications + +When creating, modifying, or deleting each ZGW entity, a notification is sent. Clients (client apps) can subscribe to these notifications. This requires a client (client app) webhook receiver to which the notifications can be delivered. The URL (and authentication) of this webhook receiver is stored in the client's subscription in our Notifications database. +There are four key components to the Notifications system: + +1. Polly retries +2. Hangfire retries and priority queue +3. Circuit breaker +4. Http codes that lead to retries + +## Polly retries + +If a notification cannot be delivered to a client webhook receiver, for example, because the service is (temporarily) down, a new attempt will be made to deliver the notification within a few seconds. Both the interval pattern (linear/exponential) and the number of attempts can be configured. An important aspect of Polly retry is that it is a blocking call, so it is important to ensure that the total retry sequence is not too long (<8 seconds). Another important aspect of Polly retry is that retries are not persistent (i.e., they take place in memory). A typical Polly retry looks like this: + +![alt text](image.png) + +## Hangfire retries and priority queue + +The second level of retries is based on the Hangfire Scheduler. It's possible that the client webhook receiver is down for an extended period. In this case, the Polly retry won't work. The Hangfire retry offers a solution because retries are scheduled and picked up and processed at a (much) later time, for example, after four hours or even after several days. Unlike Polly retries, Hangfire retries are persistent (stored as jobs in the Notification database). Hangfire retries use two queues: the MAIN and RETRY queues. New notifications are placed in the MAIN queue, while scheduled retries are placed in the RETRY queue. This prevents new notifications from having to wait until all retries have been processed, as only a limited number of jobs can be executed. More importantly, the retry period can be long, for example, one day. + +After the last failed retry, Hangfire will move the retry(job) to Failed Jobs. + +A nice feature is that Hangfire includes a Dashboard that displays all jobs (Retry Jobs, Successfully Executed Jobs, Failed Jobs, and Deleted Jobs). Failed jobs can even be restarted manually. + +A typical Hangfire retry configuration looks like this: + +![alt text](image-1.png) + +The retry pattern (configured in RetrySchedule) is: + +* 15 minutes +* 30 minutes +* 1 hour +* 4 hours +* 1 day + +There are two other settings intended for automatically cleaning up failed retry jobs: + +* ExpireFailedJobsScanAt (scan interval or the value: 'never', 'disabled', 'n/a') +* ExpireFailedJobAfter (period that failed jobs must continue to exist) + +## Circuit breaker + +Another component of the notification system is the circuit breaker. The circuit breaker prevents unresponsive (or faulty) webhook receivers from repeatedly reporting an error over a period of time. This can severely and unnecessarily block the system (think of unnecessary timeouts). The idea is that a webhook receiver is only allowed to fail a limited number of times. If a webhook receiver fails, it is MONITORED, and the number of failures is recorded. For example, after 10 failures, the webhook receiver is marked as BLOCKED (and therefore no longer MONITORED). The circuit breaker maintains this block for a specified period, for example, 5 minutes. After this, it tries to deliver the notification again. If the receiver fails again (maximum 10 times), the block occurs again. This mechanism prevents unnecessary calls to unresponsive webhook receivers, which helps improve system performance. + +All webhook receiver blocks will be automatically released after a certain period of time (unless called within this time). + +A typical Circuit breaker configuration looks like this: + +![alt text](image-2.png) + +The possible settings under CircuitBreaker are: + +* FailureThreshold (number of times you can fail before the BLOCKADE takes effect) +* BreakDuration (time of the BLOCKADE) +* CacheExpirationMinutes (time that MONITORING and BLOCKS are lifted unless called) + +## Http codes that lead to retries + +### Polly retry + +Polly will perform retries according to the configured policy for the following HTTP status codes: + +* HttpRequestException +* All HTTP 5xx codes +* 408 Request Timeout +* 429 TooManyRequests + +With the other HTTP status codes, the error is returned immediately. + +It's possible to perform a retry on HTTP status codes that aren't supported by Polly. This can be done using the AddRetryOnHttpStatusCodes setting directly under PollyConfig. Multiple codes are supported. So, if you want to perform a retry on a NotFound (404) error, you can configure this with the following line: + +![alt text](image-3.png) + +### Hangfire retry + +Hangfire retry makes no distinction and will always perform a retry. diff --git a/docs/usage-of-clientids.md b/docs/usage-of-clientids.md index ad04fa0..7891975 100644 --- a/docs/usage-of-clientids.md +++ b/docs/usage-of-clientids.md @@ -1,16 +1,7 @@ --- -title: "ClientID Management and JWT Authentication in OneGround" -description: "Complete guide to ClientID creation, management, and JWT bearer token authentication for OneGround ZGW APIs. Learn how to obtain credentials, generate tokens, and configure secure API access." -keywords: - - ClientID - - JWT authentication - - bearer token - - OneGround authentication - - ZGW API security - - API credentials - - client configuration - - authentication guide - - secret management +title: "Usage of ClientIDs" +description: "Learn how to obtain or generate JWT bearer tokens using ClientIDs for OneGround APIs in both Community and Unlimited editions." +keywords: ["ClientID", "JWT", "OneGround", "API", "Authentication", "ZGW"] --- # ClientID's diff --git a/docs/version-header.md b/docs/version-header.md index df6d4fe..1b36a74 100644 --- a/docs/version-header.md +++ b/docs/version-header.md @@ -1,6 +1,7 @@ --- -title: "Version Headers" -description: "Usage of version headers in OneGround" +title: "Usage of Version Headers" +description: "Guidelines and best practices for using the Api-version header in OneGround APIs, including compliance with the API Strategy standard." +keywords: ["Api-version", "Header", "OneGround", "ZGW", "API Strategy", "Versioning"] --- # Usage of version headers in OneGround diff --git a/docs/ztc1_3problemsandsolutions.md b/docs/ztc1_3problemsandsolutions.md index 7abfefc..b8d0611 100644 --- a/docs/ztc1_3problemsandsolutions.md +++ b/docs/ztc1_3problemsandsolutions.md @@ -1,5 +1,7 @@ --- -title: "Problems in and solutions for ZTC 1.3" +title: "ZTC 1.3 Problems and Solutions" +description: "A comprehensive list of known issues within the ZTC 1.3 standard and how Roxit components address them." +keywords: ["ZTC 1.3", "ZGW", "Roxit", "Issues", "Solutions", "Workarounds"] --- # Problems in and solutions for ZTC 1.3 From 64b11e44ff60defe3caa6f84107b8cca6ced0474 Mon Sep 17 00:00:00 2001 From: Giedrius Grabauskas <43740166+Grabauskas@users.noreply.github.com> Date: Mon, 19 Jan 2026 11:06:42 +0200 Subject: [PATCH 2/3] Removed new file --- docs/notifications-architecture.md | 83 ------------------------------ 1 file changed, 83 deletions(-) delete mode 100644 docs/notifications-architecture.md diff --git a/docs/notifications-architecture.md b/docs/notifications-architecture.md deleted file mode 100644 index 4f18a4a..0000000 --- a/docs/notifications-architecture.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Notifications Architecture" -description: "Overview of the Notifications system architecture, detailing retry strategies with Polly and Hangfire, circuit breaker patterns, and HTTP status code handling." -keywords: [notifications, architecture, polly, hangfire, circuit breaker, retry, webhook, OneGround, ZGW] ---- - -# Notifications - -When creating, modifying, or deleting each ZGW entity, a notification is sent. Clients (client apps) can subscribe to these notifications. This requires a client (client app) webhook receiver to which the notifications can be delivered. The URL (and authentication) of this webhook receiver is stored in the client's subscription in our Notifications database. -There are four key components to the Notifications system: - -1. Polly retries -2. Hangfire retries and priority queue -3. Circuit breaker -4. Http codes that lead to retries - -## Polly retries - -If a notification cannot be delivered to a client webhook receiver, for example, because the service is (temporarily) down, a new attempt will be made to deliver the notification within a few seconds. Both the interval pattern (linear/exponential) and the number of attempts can be configured. An important aspect of Polly retry is that it is a blocking call, so it is important to ensure that the total retry sequence is not too long (<8 seconds). Another important aspect of Polly retry is that retries are not persistent (i.e., they take place in memory). A typical Polly retry looks like this: - -![alt text](image.png) - -## Hangfire retries and priority queue - -The second level of retries is based on the Hangfire Scheduler. It's possible that the client webhook receiver is down for an extended period. In this case, the Polly retry won't work. The Hangfire retry offers a solution because retries are scheduled and picked up and processed at a (much) later time, for example, after four hours or even after several days. Unlike Polly retries, Hangfire retries are persistent (stored as jobs in the Notification database). Hangfire retries use two queues: the MAIN and RETRY queues. New notifications are placed in the MAIN queue, while scheduled retries are placed in the RETRY queue. This prevents new notifications from having to wait until all retries have been processed, as only a limited number of jobs can be executed. More importantly, the retry period can be long, for example, one day. - -After the last failed retry, Hangfire will move the retry(job) to Failed Jobs. - -A nice feature is that Hangfire includes a Dashboard that displays all jobs (Retry Jobs, Successfully Executed Jobs, Failed Jobs, and Deleted Jobs). Failed jobs can even be restarted manually. - -A typical Hangfire retry configuration looks like this: - -![alt text](image-1.png) - -The retry pattern (configured in RetrySchedule) is: - -* 15 minutes -* 30 minutes -* 1 hour -* 4 hours -* 1 day - -There are two other settings intended for automatically cleaning up failed retry jobs: - -* ExpireFailedJobsScanAt (scan interval or the value: 'never', 'disabled', 'n/a') -* ExpireFailedJobAfter (period that failed jobs must continue to exist) - -## Circuit breaker - -Another component of the notification system is the circuit breaker. The circuit breaker prevents unresponsive (or faulty) webhook receivers from repeatedly reporting an error over a period of time. This can severely and unnecessarily block the system (think of unnecessary timeouts). The idea is that a webhook receiver is only allowed to fail a limited number of times. If a webhook receiver fails, it is MONITORED, and the number of failures is recorded. For example, after 10 failures, the webhook receiver is marked as BLOCKED (and therefore no longer MONITORED). The circuit breaker maintains this block for a specified period, for example, 5 minutes. After this, it tries to deliver the notification again. If the receiver fails again (maximum 10 times), the block occurs again. This mechanism prevents unnecessary calls to unresponsive webhook receivers, which helps improve system performance. - -All webhook receiver blocks will be automatically released after a certain period of time (unless called within this time). - -A typical Circuit breaker configuration looks like this: - -![alt text](image-2.png) - -The possible settings under CircuitBreaker are: - -* FailureThreshold (number of times you can fail before the BLOCKADE takes effect) -* BreakDuration (time of the BLOCKADE) -* CacheExpirationMinutes (time that MONITORING and BLOCKS are lifted unless called) - -## Http codes that lead to retries - -### Polly retry - -Polly will perform retries according to the configured policy for the following HTTP status codes: - -* HttpRequestException -* All HTTP 5xx codes -* 408 Request Timeout -* 429 TooManyRequests - -With the other HTTP status codes, the error is returned immediately. - -It's possible to perform a retry on HTTP status codes that aren't supported by Polly. This can be done using the AddRetryOnHttpStatusCodes setting directly under PollyConfig. Multiple codes are supported. So, if you want to perform a retry on a NotFound (404) error, you can configure this with the following line: - -![alt text](image-3.png) - -### Hangfire retry - -Hangfire retry makes no distinction and will always perform a retry. From 23a2002f4f111d7faa145bd1b2856f536836b626 Mon Sep 17 00:00:00 2001 From: Giedrius Grabauskas <43740166+Grabauskas@users.noreply.github.com> Date: Mon, 19 Jan 2026 11:06:53 +0200 Subject: [PATCH 3/3] Versions bump --- package-lock.json | 8 ++++---- package.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/package-lock.json b/package-lock.json index d1700f4..fda6a37 100644 --- a/package-lock.json +++ b/package-lock.json @@ -21,7 +21,7 @@ "@docusaurus/module-type-aliases": "3.9.2", "@docusaurus/tsconfig": "3.9.2", "@docusaurus/types": "3.9.2", - "prettier": "^3.7.4", + "prettier": "^3.8.0", "typescript": "~5.9.3" }, "engines": { @@ -14694,9 +14694,9 @@ } }, "node_modules/prettier": { - "version": "3.7.4", - "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.7.4.tgz", - "integrity": "sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA==", + "version": "3.8.0", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.0.tgz", + "integrity": "sha512-yEPsovQfpxYfgWNhCfECjG5AQaO+K3dp6XERmOepyPDVqcJm+bjyCVO3pmU+nAPe0N5dDvekfGezt/EIiRe1TA==", "dev": true, "license": "MIT", "bin": { diff --git a/package.json b/package.json index 361f26a..3757e6a 100644 --- a/package.json +++ b/package.json @@ -30,7 +30,7 @@ "@docusaurus/module-type-aliases": "3.9.2", "@docusaurus/tsconfig": "3.9.2", "@docusaurus/types": "3.9.2", - "prettier": "^3.7.4", + "prettier": "^3.8.0", "typescript": "~5.9.3" }, "browserslist": {