OneGround ZGW-APIs

Production-ready APIs for Case Management (Zaakgericht Werken) in C#

About OneGround ZGW-APIs

This repository contains the source code and documentation for production-ready APIs implementing the VNG Standards for Case Management (Zaakgericht Werken). This is a C# implementation of the ZGW-APIs standard.

Case Management (Zaakgericht Werken)

Case Management (Zaakgericht Werken) is a process-oriented work method used by Dutch municipalities and increasingly by national government bodies to handle requests from citizens and businesses. This implementation provides the necessary APIs to support this way of working in a common ground architecture. Common ground architecture originally consisted of 5 layers:

• UI (not in this project)
• process logic (not in this project)
• middleware (not in this project)
• APIs including business rules (in this project)
• storage (in this project)

API Standards Implementation

This implementation follows the VNG Realisatie standard "APIs for Zaakgericht Werken" and includes the following core APIs:

• Catalogi API - For registering case type catalogs, case types, and all related types
• Zaken API - For case registration, including relationships with documents, decisions, and contacts
• Documenten API - For registration of information objects (documents, photos, videos, etc.)
• Besluiten API - For registration of decisions made in the context of case management

Supporting APIs:

• Notifications API - For managing subscriptions and notifications of data changes
• Authorization API - For managing application access to data
• Reference API - Process types and result types for archiving based on selection lists

Message Listeners

The system includes two message listeners for asynchronous processing:

• Notifications Listener (NRC) - OneGround.ZGW.Notificaties.Messaging.Listener - Processes notification messages and handles subscription-based event notifications
• Documenten Listener (DRC) - OneGround.ZGW.Documenten.Messaging.Listener - Processes document-related messages for asynchronous document operations

Technical Features

• Built with C# and .NET - Utilizing modern C# features and .NET best practices
• Microservices Architecture - Each API is designed as an independent microservice
• Docker Support - Containerized deployment ready
• Swagger/OpenAPI - Complete API documentation using Swagger/OpenAPI
• Authentication & Authorization - Security implementation according to the standard (machine to machine)
• Audit Trail - Logging of changes according to the standard
• Archiving Support - Built-in support for archiving according to Dutch standards
• Ceph Support - Built-in support for storage of document contents on Ceph
• Multi-tenant - One installation can serve multiple instances or organisations

Getting Started

Prerequisites

• .NET: 8.0
• Docker: Version 24.0.0 or higher
• Docker Compose: Version 2.20.0 or higher

Installation

1. Clone the repository:

   git clone https://github.com/OneGround/ZGW-APIs.git
   cd ZGW-APIs
   

2. Build the solution:

   dotnet build ./src/ZGW.all.sln
   

3. Run the tests:

   dotnet test ./src/ZGW.UnitTests.slnf
   

Docker Deployment

We offer two primary methods for running the ZGW APIs using Docker:

• Running from Docker Images: For a quick and easy setup, follow our recommended Getting Started guide.
• Running from Source Code: For local development or contributing to the project, follow our localdev setup guide.

Configuration

Configuration can be done through:

• appsettings.json files
• Environment variables
• Docker environment files

For more information, visit our documentation portal.

Project Structure

• src: source code
• localdev: everything needed to set up your own development environment including Ceph and Databases

Documentation

Complete documentation is available at: https://dev.oneground.nl

Additional Documentation

• General Documentation - Additional documentation resources
• Authentication Guide - Complete guide for authenticating against the ZGW APIs
• Logging Configuration - Detailed logging strategy using Serilog
• HMAC + DataProtection encryption guide - Explains encryption strategy (HMAC for search + DataProtection for at-rest), with key generation scripts

Contributing

We welcome contributions to the OneGround ZGW-APIs. Please read our contribution guidelines for details on our code of conduct and the process for submitting pull requests.

Links

• VNG Standards for ZGW-APIs
• OneGround Documentation

Support

For support questions, please contact:

• Email: [email protected]
• Create an issue

Acknowledgments

• VNG Realisatie for the ZGW-APIs standard
• The Dutch municipalities contributing to the standard
• The open-source community for inspiration and tools

---

Built with pleasure by Roxit