OMC Documentatie

Introduction
- Open services
- Notify
- 1.1. Swagger UI
  - 1.1.1. Using web browser
  - 1.1.2. Using IDE (Visual Studio)
    1.1.2.1. Customizing profile
    1.1.2.2. Running profile
- 1.2. Docker
Architecture
Setup
- 3.1. Configurations
  - 3.1.1. appsettings.json
    3.1.1.1. Example
  - 3.1.2. Environment variables
    3.1.2.1. Example
    3.1.2.2. Get environment variables
    3.1.2.3. Set environment variables
    3.1.2.4. Overriding appsettings.json
    3.1.2.5. Using HELM Charts
Authorization and authentication
- 4.1. JSON Web Tokens
  - 4.1.1. Generating
  - 4.1.2. Required components
    4.1.2.1. Header (algorithm + type)
    4.1.2.2. Payload (claims)
    4.1.2.3. Signature (secret)
  - 4.1.3. Mapping of JWT claims from environment variables
  - 4.1.4. Using generated JSON Web Token (JWT)
    4.1.4.1. Postman (authorization)
    4.1.4.2. Swagger UI (authorization)
OMC Workflow
- 5.1. Versions
  - 5.1.1. Dependencies
    5.1.1.1. OMC workflow v1 (default)
    5.1.1.1. OMC workflow v2
- 5.2. Scenarios
  - 5.2.1. General introduction
    5.2.1.1. Notification
    5.2.1.2. Environment variables
    5.2.1.3. Requirements
    5.2.1.4. Template placeholders
  - Examples
  - 5.2.2. Case Created
    5.2.2.1. Notification
    5.2.2.2. Environment variables
    5.2.2.3. Requirements
    5.2.2.4. Template placeholder
  - 5.2.3. Case Updated
    5.2.3.1. Notification
    5.2.3.2. Environment variables
    5.2.3.3. Requirements
    5.2.3.4. Template placeholders
  - 5.2.4. Case Closed
    5.2.4.1. Notification
    5.2.4.2. Environment variables
    5.2.4.3. Requirements
    5.2.4.4. Template placeholders
  - 5.2.5. Task Assigned
    5.2.5.1. Notification
    5.2.5.2. Environment variables
    5.2.5.3. Requirements
    5.2.5.4. Template placeholders
  - 5.2.6. Decision Made
    5.2.6.1. Notification
    5.2.6.2. Environment variables
    5.2.6.3. Requirements
    5.2.6.4. Template placeholders
  - 5.2.7. Message Received
    5.2.7.1. Notification
    5.2.7.2. Environment variables
    5.2.7.3. Requirements
    5.2.7.4. Template placeholders
  - 5.2.99. Not Implemented
Errors
- 6.1. Events Controller
  - 6.1.1. Possible errors
- 6.2. Notify Controller
  - 6.2.1. Possible errors
- 6.3. Test Controller
  - 6.3.1. Testing Notify
    6.3.1.1. Possible errors
    a) Common for SendEmail + SendSms
    b) SendEmail
    c) SendSms
  - 6.3.2. Testing Open services
    6.3.2.1. Possible errors

1. Introduction

Go back

OMC (Output Management Component) is a central point and the common hub of the communication workflow between third parties software such as:

ZGW / Open Services (repositories)

ZGW | Open Notificaties (Web API service)
ZGW | Open Zaak (Web API service) NOTE: Older version of Open Zaak contains also "Contact Momenten v1"
ZGW | Open Klant (Web API service)
ZGW | Besluiten (Web API service) NOTE: It's part of Open Zaak repository
ZGW | Objecten (Web API service)
ZGW | ObjectTypen (Web API service)
ZGW | Klantinteracties (Web API service) NOTE: "Contact Momenten v2" (extracted from Open Zaak)

Notify

Notify NL (Web API service) => based on Notify UK
- Web API service (Python)
- Language-specific clients (e.g., C#, JavaScript, PHP)
OMC is written in C# and using .NET Client for Notify.
- Webpage: admin portal

NOTE: Different versions of these external API services are handled by, so-called "OMC Workflows".

1.1. Swagger UI

Since the OMC project is just an API, it would not have any user-friendly graphic representation if used as a standalone RESTful ASP.NET Web API project.

That's why ASP.NET projects are usually exposing a UI presentation layer for the convenience of future users (usually developers). To achieve this effect, we are using so called Swagger UI, a standardized HTML/CSS/JavaScript-based suite of tools and assets made to generate visualized API endpoints, API documentation, data models schema, data validation, interaction with user (API responses), and other helpful hints on how to use the certain API.

Swagger UI can be accessed just like a regular webpage, or when you are starting your project in your IDE (preferably Visual Studio).

NOTE: Check the section dedicated to requests authorization when using Swagger UI.

1.1.1. Using web browser

The URL to Swagger UI can be recreated in the following way:

[Protocol*] + [Domain**] + /swagger/index.html

For example: https://omc.acc.notifynl.nl/swagger/index.html

* Usually https ** Where your OMC Web API application is deployed

1.1.2. Using IDE (Visual Studio)

To run the application locally (using Visual Studio) select one of the launchSettings.json profiles to start Swagger UI page in your browser (which will be using /localhost:... address).

By default these profiles are already defined:

http
https
IIS Express

And all of them have Swagger UI specified as the default start option.

NOTE: In this example application will start in "Development" mode.

1.1.2.1. Customizing profile

Full content of launchSettings.json file for Events Handler project.

{
  "profiles": {
    "http": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "dotnetRunMessages": true,
      "applicationUrl": "http://localhost:0000"
    },
    "https": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "dotnetRunMessages": true,
      "applicationUrl": "https://localhost:0001;http://localhost:0000"
    },
    "IIS Express (Development)": {  // NOTE: Name of the profile can be changed
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",  // NOTE: Application mode can be changed
		 
        "OMC_AUTH_JWT_SECRET": "",
        "OMC_AUTH_JWT_ISSUER": "",
        "OMC_AUTH_JWT_AUDIENCE": "",
        "OMC_AUTH_JWT_EXPIRESINMIN": "",
        "OMC_AUTH_JWT_USERID": "OMC (Development)",  // NOTE: Optional place to reflect application mode
        "OMC_AUTH_JWT_USERNAME": "OMC (Development)",  // NOTE: Optional place to reflect application mode

        "OMC_FEATURE_WORKFLOW_VERSION": "",
        
        "ZGW_AUTH_JWT_SECRET": "",
        "ZGW_AUTH_JWT_ISSUER": "",
        "ZGW_AUTH_JWT_AUDIENCE": "",
        "ZGW_AUTH_JWT_EXPIRESINMIN": "",
        "ZGW_AUTH_JWT_USERID": "",
        "ZGW_AUTH_JWT_USERNAME": "",
        
        "ZGW_AUTH_KEY_OPENKLANT": "", // NOTE: Not required if OMC Workflow v1 is used
        "ZGW_AUTH_KEY_OBJECTEN": "",
        "ZGW_AUTH_KEY_OBJECTTYPEN": "",
        
        "ZGW_ENDPOINT_OPENNOTIFICATIES": "",
        "ZGW_ENDPOINT_OPENZAAK": "",
        "ZGW_ENDPOINT_OPENKLANT": "",
        "ZGW_ENDPOINT_OBJECTEN": "",
        "ZGW_ENDPOINT_OBJECTTYPEN": "",
        "ZGW_ENDPOINT_CONTACTMOMENTEN": "",

        "ZGW_WHITELIST_ZAAKCREATE_IDS": "",
        "ZGW_WHITELIST_ZAAKUPDATE_IDS": "",
        "ZGW_WHITELIST_ZAAKCLOSE_IDS": "",
        "ZGW_WHITELIST_TASKASSIGNED_IDS": "",
        "ZGW_WHITELIST_DECISIONMADE_IDS": "",
        "ZGW_WHITELIST_MESSAGE_ALLOWED": "false",

        "ZGW_VARIABLE_OBJECTTYPE_TASKOBJECTTYPE_UUID": "",
        "ZGW_VARIABLE_OBJECTTYPE_MESSAGEOBJECTTYPE_UUID": "",
        "ZGW_VARIABLE_OBJECTTYPE_MESSAGEOBJECTTYPE_VERSION" : "",
        "ZGW_VARIABLE_OBJECTTYPE_DECISIONINFOOBJECTTYPE_UUIDS": "",
        
        "NOTIFY_API_BASEURL": "",
        "NOTIFY_API_KEY": "",
        
        "NOTIFY_TEMPLATEID_DECISIONMADE": "",

        "NOTIFY_TEMPLATEID_EMAIL_ZAAKCREATE": "",
        "NOTIFY_TEMPLATEID_EMAIL_ZAAKUPDATE": "",
        "NOTIFY_TEMPLATEID_EMAIL_ZAAKCLOSE": "",
        "NOTIFY_TEMPLATEID_EMAIL_TASKASSIGNED": "",
        "NOTIFY_TEMPLATEID_EMAIL_MESSAGERECEIVED": "",

        "NOTIFY_TEMPLATEID_SMS_ZAAKCREATE": "",
        "NOTIFY_TEMPLATEID_SMS_ZAAKUPDATE": "",
        "NOTIFY_TEMPLATEID_SMS_ZAAKCLOSE": "",
        "NOTIFY_TEMPLATEID_SMS_TASKASSIGNED": "",
        "NOTIFY_TEMPLATEID_SMS_MESSAGERECEIVED": "",
        
        "SENTRY_DSN": "",
        "SENTRY_ENVIRONMENT": "Worth Systems (Development)"  // NOTE: Optional place to reflect application instance and mode
      }
    },
    "Docker": {
      "commandName": "Docker",
      "launchBrowser": true,
      "launchUrl": "{Scheme}://{ServiceHost}:{ServicePort}/swagger",
      "publishAllPorts": true,
      "useSSL": true
    }
  },
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:00002",
      "sslPort": 00003
    }
  }
}

Full content of launchSettings.json file for Secrets Manager project.

{
  "profiles": {
    "SecretsManager": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production",

        "OMC_AUTH_JWT_SECRET": "",
        "OMC_AUTH_JWT_ISSUER": "",
        "OMC_AUTH_JWT_AUDIENCE": "",
        "OMC_AUTH_JWT_EXPIRESINMIN": "",
        "OMC_AUTH_JWT_USERID": "OMC (Development)",  // NOTE: Optional place to reflect application mode
        "OMC_AUTH_JWT_USERNAME": "OMC (Development)",  // NOTE: Optional place to reflect application mode
      }
    }
  }
}

NOTE: An example of customized "IIS Express (Development)" profile (with environment variables overruling those defined directly in Windows OS).

The developer can create more than one launch profile:

e.g., for testing OMC Workflow v1 (pointing to older domains) and OMC Workflow vXYZ (pointing to newer domains). Both using different credentials, template IDs, application modes (Production, Development, Test), names, logging identifiers (Sentry.io), etc.

1.1.2.2. Running profile

1.2. Docker

After cloning OMC Git repository:

git@github.com:Worth-NL/NotifyNL-OMC.git

Go to the root catalog:

.../NotifyNL-OMC

And run the following docker command:

docker build -f OMC/Infrastructure/WebApi/EventsHandler/Dockerfile --force-rm -t omc .
NOTE: omc is just a name of your docker image and it can be anything you want.

The command from above is addressing the issue with building docker image from the Dockerfile location: ERROR: failed to solve: failed to compute cache key: failed to calculate checksum of ref

From this moment follow the HELM Chart documentation to set up environment variables in order to run an already created docker container.

2. Architecture

Go back

Scenarios implemented in OMC are following Strategy Design Pattern, and they are using JSON data deserialized into POCO (Plain Old CLR Object) models, and passed as DTO (Data Transfer Object) models to query services (reflecting the external micro-services architecture of third-party "Open Services"). Query services are aggregated under IQueryContext and its implementation QueryContext - following Adapter Design Pattern thanks to which queries can be agnostic (dependencies resolved internally) and organized within a single testable abstraction, giving the developers access to all available API query methods.

3. Setup

Go back

3.1. Configurations

OMC API and related sub-systems (e.g., Secrets Manager) are using two types of configurations:

public (appsettings.json)
private (environment variables)

Which can also be divided into other two categories:

universal settings (not changing very often; basic/default behavior of OMC)
customizable settings (which may vary between OMC instances; business)

Easier to monitor, test, modify, and maintain by developers are appsettings.json, but environment variables are easier to be adjusted by the end users of OMC.

3.1.1. appsettings.json

Made for public configurations (can be safely preserved in the code, without causing confidentiality issues). They are not meant to be changed very often.

NOTE: Here are defined settings related to HTTP connection, encryption used for JWT tokens to authorize HTTP requests to / from other Web API services, or default variables defining OMC domain setup - adjusting how the generic and agnostic Open Services will be utilized.

3.1.1.1. Example

Full content of appsettings.json file for Events Handler project.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Information"
    }
  },
  "Network": {
    "ConnectionLifetimeInSeconds": 90,
    "HttpRequestTimeoutInSeconds": 60,
    "HttpRequestsSimultaneousNumber": 20
  },
  "Encryption": {
    "IsAsymmetric": false
  },

  // Predefined variables based on which the application workflow currently relies.
  // NOTE: Their default values should not be changed, unless they are also adopted on
  //       the OpenZaak and OpenKlant API sides (which are more dynamic than OMC API).
  "Variables": {
    // ENG: Subject type (e.g., person or organization)
    "BetrokkeneType": "natuurlijk_persoon",
    // ENG: General description => "initiator role"
    "OmschrijvingGeneriek": "initiator",
    // ENG: Party identifier => e.g., "citizen identifier"
    "PartijIdentificator": "Burgerservicenummer",
    // ENG: Email general description (e.g., "email", "e-mail", "Email"...)
    "EmailOmschrijvingGeneriek": "Email",
    // ENG: Phone general description (e.g., "phone", "mobile", "nummer"...)
    "TelefoonOmschrijvingGeneriek": "Telefoon",

    "OpenKlant": {
      "CodeObjectType": "Zaak",
      "CodeRegister": "ZRC",
      "CodeObjectTypeId": "identificatie"
    },

    // User communication: Messages to be put into register exposed to citizens
    "UxMessages": {
      "SMS_Success_Subject": "Notificatie verzonden",
      "SMS_Success_Body": "SMS notificatie succesvol verzonden.",

      "SMS_Failure_Subject": "We konden uw notificatie niet afleveren.",
      "SMS_Failure_Body": "Het afleveren van een SMS bericht is niet gelukt. Controleer het telefoonnumer in uw profiel.",

      "Email_Success_Subject": "Notificatie verzonden",
      "Email_Success_Body": "E-mail notificatie succesvol verzonden.",

      "Email_Failure_Subject": "We konden uw notificatie niet afleveren.",
      "Email_Failure_Body": "Het afleveren van een email bericht is niet gelukt. Controleer het emailadres in uw profiel."
    }
  },
  "AllowedHosts": "*"
}

Full content of manager.appsettings.json file for Secrets Manager project.

{
  "Encryption": {
    "IsAsymmetric": false
  }
}

You can determine which appsettings[...].json configuration will be used by setting a respective value of ASPNETCORE_ENVIRONMENT property in environmentVariables in your launch profile defined in launchSettings.json. The supported values are:

"Production"
"Development"
"Test"

During the start of the OMC application the content of appsettings.[ASPNETCORE_ENVIRONMENT].json file will be loaded.

NOTE: Sometimes, in the documentation or in the code, when referring to this value a name "application mode(s)" might be used - because this environment variable is usually defining the global setup / behavior of any .NET application.

3.1.2. Environment variables

Meant to store sensitive configurations and / or customizable per instances of the OMC application).

3.1.2.1. Example

Name*

.NET Type

Example

Is sensitive

Validation

Notes

.NET settings

---

ASPNETCORE_ENVIRONMENT

string

"Development", "Production", "Test"

false

Cannot be missing and have null or empty value

Defines in which mode (environment) the OMC applicatio is running

---

OMC settings

OMC_AUTH_JWT_SECRET

string

"abcd123t2gw3r8192dewEg%wdlsa3e!"

true

Cannot be missing and have null or empty value

For security reasons it should be at least 64 bytes long

OMC_AUTH_JWT_ISSUER

string

"OMC"

true

Cannot be missing and have null or empty value

Something identifying Notify NL (OMC Web API) service (it will be used internally) - The OMC is the issuer

OMC_AUTH_JWT_AUDIENCE

string

"OMC"

true

Cannot be missing

Something identifying Notify NL (OMC Web API) service (it will be used internally) - The OMC is the audience

OMC_AUTH_JWT_EXPIRESINMIN

ushort

"60"

true

Cannot be missing and have null or empty value

The OMC JWT tokens are generated by OMC and authorized by Open services. New JWT token has to be generated manually, using OMC dedicated library, if the token validity expire (by default it is 60 minutes)

OMC_AUTH_JWT_USERID

string

"tester"

false

Cannot be missing and have null or empty value

OMC_AUTH_JWT_USERNAME

string

"Charlotte Sanders"

false

Cannot be missing and have null or empty value

---

OMC_FEATURE_WORKFLOW_VERSION

byte

"1"

false

Cannot be missing and have null or empty value. It also needs to correspond to already supported OMC Workflows

The list of supported OMC workflows can be found here

---

ZGW settings (Open Services)

ZGW_AUTH_JWT_SECRET

string

"abcd123t2gw3r8192dewEg%wdlsa3e!"

true

Cannot be missing and have null or empty value

Internal implementation of Open services is regulating this, however it's better to use something longer as well

ZGW_AUTH_JWT_ISSUER

string

"Open Services"

true

Cannot be missing and have null or empty value

Something identifying "OpenZaak" / "OpenKlant" / "OpenNotificatie" Web API services (token is shared between of them)

ZGW_AUTH_JWT_AUDIENCE

string

"OMC"

true

Cannot be missing

Something identifying OMC Web API service (it will be used internally) - The OMC is the audience

ZGW_AUTH_JWT_EXPIRESINMIN

ushort

"60"

true

Cannot be missing and have null or empty value

This JWT token will be generated from secret, and other JWT claims, configured from UI of OpenZaak Web API service. Identical details (secret, iss, aud, exp, etc) as in Open services needs to be used here

ZGW_AUTH_JWT_USERID

string

"admin"

false

Cannot be missing and have null or empty value

ZGW_AUTH_JWT_USERNAME

string

"Municipality of Rotterdam"

false

Cannot be missing and have null or empty value

---

ZGW_AUTH_KEY_OPENKLANT

string

"43dcba52d312d1e00bc..."

true

Cannot be missing and have null or empty value (if you are using OMC Workflow v2 and above; otherwise, it's not mandatory)

It needs to be generated for OMC Workflow v2 and above from "OpenKlant" 2.0 Web API service UI

ZGW_AUTH_KEY_OBJECTEN

string

"56abcd24e75c02d44ee..."

true

Cannot be missing and have null or empty value

It needs to be generated from "Objecten" Web API service UI

ZGW_AUTH_KEY_OBJECTTYPEN

string

"647c4eg120f98ed5f5a..."

true

Cannot be missing and have null or empty value

It needs to be generated from "ObjectTypen" Web API service UI

---

ZGW_ENDPOINT_OPENNOTIFICATIES

string

"opennotificaties.mycity.nl/api/v1"

false

Cannot be missing and have null or empty value + only domain should be used: without protocol (http / https). Without slash at the end

You have to use the domain part from URLs where you are hosting the dedicated Open services

ZGW_ENDPOINT_OPENZAAK

string

"openzaak.mycity.nl/zaken/api/v1"

false

Cannot be missing and have null or empty value + only domain should be used: without protocol (http / https). Without slash at the end

You have to use the domain part from URLs where you are hosting the dedicated Open services

ZGW_ENDPOINT_OPENKLANT

string

"openklant.mycity.nl/klanten/api/v1"

false

Cannot be missing and have null or empty value + only domain should be used: without protocol (http / https). Without slash at the end

You have to use the domain part from URLs where you are hosting the dedicated Open services

ZGW_ENDPOINT_BESLUITEN

string

"besluiten.mycity.nl/besluiten/api/v1"

false

Cannot be missing and have null or empty value + only domain should be used: without protocol (http / https). Without slash at the end

You have to use the domain part from URLs where you are hosting the dedicated Open services

ZGW_ENDPOINT_OBJECTEN

string

"objecten.mycity.nl/api/v2"

false

Cannot be missing and have null or empty value + only domain should be used: without protocol (http / https). Without slash at the end

You have to use the domain part from URLs where you are hosting the dedicated Open services

ZGW_ENDPOINT_OBJECTTYPEN

string

"objecttypen.mycity.nl/api/v2"

false

Cannot be missing and have null or empty value + only domain should be used: without protocol (http / https). Without slash at the end

You have to use the domain part from URLs where you are hosting the dedicated Open services

ZGW_ENDPOINT_CONTACTMOMENTEN

string

"openklant.mycity.nl/contactmomenten/api/v1"

false

Cannot be missing and have null or empty value + only domain should be used: without protocol (http / https). Without slash at the end

You have to use the domain part from URLs where you are hosting the dedicated Open services

---

ZGW_WHITELIST_ZAAKCREATE_IDS

string[]

"1, 2, 3, 4" or "*" (allow everything)

false

Is provided by the user based on "Identificatie" property of case type retrieved from case URI ("zaak") from "OpenZaak" Web API service

ZGW_WHITELIST_ZAAKUPDATE_IDS

string[]

"1, 2, 3, 4" or "*" (allow everything)

false

Is provided by the user based on "Identificatie" property of case type retrieved from case URI ("zaak") from "OpenZaak" Web API service

ZGW_WHITELIST_ZAAKCLOSE_IDS

string[]

"1, 2, 3, 4" or "*" (allow everything)

false

Is provided by the user based on "Identificatie" property of case type retrieved from case URI ("zaak") from "OpenZaak" Web API service

ZGW_WHITELIST_TASKASSIGNED_IDS

string[]

"1, 2, 3, 4" or "*" (allow everything)

false

Is provided by the user based on "Identificatie" property of case type retrieved from case URI ("zaak") from "OpenZaak" Web API service

ZGW_WHITELIST_DECISIONMADE_IDS

string[]

"1, 2, 3, 4" or "*" (allow everything)

false

Is provided by the user based on "Identificatie" property of case type retrieved from case URI ("zaak") from "OpenZaak" Web API service

ZGW_WHITELIST_MESSAGE_ALLOWED

bool

"true" or "false"

false

Cannot be missing and have null or empty value

Is provided by the user

---

ZGW_VARIABLE_OBJECTTYPE_TASKOBJECTTYPE_UUID

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Is provided by the user based on "objectType" from "kenmerken" from the initial notification received from "Notificaties" Web API service

ZGW_VARIABLE_OBJECTTYPE_MESSAGEOBJECTTYPE_UUID

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Is provided by the user based on "objectType" from "kenmerken" from the initial notification received from "Notificaties" Web API service

ZGW_VARIABLE_OBJECTTYPE_MESSAGEOBJECTTYPE_VERSION

ushort

"1"

false

Cannot be missing and have null or empty value

It can be taken from "version" value set in "ObjectTypen" Web API service

ZGW_VARIABLE_OBJECTTYPE_DECISIONINFOOBJECTTYPE_UUIDS

GUID[]

"00000000-0000-..., 00000000-0000-..."

false

Cannot be missing and have null or empty value + must be in UUID format

Is provided by the user based on "informatieobjecttype" from "informatieobject" retrieved from "OpenZaak" Web API service when querying "besluiten"

---

Notify settings

NOTIFY_API_BASEURL

URI

"https://api.notify.nl"

false

Cannot be missing and have null or empty value

The domain where your Notify API instance is listening (e.g.: "https://api.notifynl.nl")

NOTIFY_API_KEY

string

"name-8-4-4-4-12-8-4-4-4-12" (ID + UUID x2)

true

Cannot be missing and have null or empty value + must be in name-UUID-UUID format + must pass Notify NL validation

It needs to be generated from "Notify NL" Admin Portal

---

NOTIFY_TEMPLATEID_DECISIONMADE

GUID**

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

---

NOTIFY_TEMPLATEID_EMAIL_ZAAKCREATE

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

NOTIFY_TEMPLATEID_EMAIL_ZAAKUPDATE

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

NOTIFY_TEMPLATEID_EMAIL_ZAAKCLOSE

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

NOTIFY_TEMPLATEID_EMAIL_TASKASSIGNED

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

NOTIFY_TEMPLATEID_EMAIL_MESSAGE

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

---

NOTIFY_TEMPLATEID_SMS_ZAAKCREATE

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

NOTIFY_TEMPLATEID_SMS_ZAAKUPDATE

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

NOTIFY_TEMPLATEID_SMS_ZAAKCLOSE

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

NOTIFY_TEMPLATEID_SMS_TASKASSIGNED

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

NOTIFY_TEMPLATEID_SMS_MESSAGE

GUID

"00000000-0000-0000-0000-000000000000"

false

Cannot be missing and have null or empty value + must be in UUID format

Should be generated per specific business use case from "Notify NL" Admin Portal

---

Monitoring settings

SENTRY_DSN

URI

"https://1abxxx@o1xxx.sentry.io/xxx"

false

Validated internally by Sentry.SDK

It points out to the Sentry project configured to store captured events from the app (messages, exceptions)

SENTRY_ENVIRONMENT

string

"MyCompany-prod"

false

Validated internally by Sentry.SDK

It's the identifier used by Sentry external logging system to distinguish instance and mode of the application (it can contains name of the company, or specific environment: prod, acc, dev, test...)

* Copy-paste the environment variable name and set the value of respective type like showed in the Example column from the above. ** GUID and UUID are representing the same data type in the following format: 8-4-4-4-12 and using Hexadecimal values (0-f). The difference is that UUID is used in cross-platform context, while GUID is the data type used in .NET

3.1.2.2. Get environment variables

OMC_AUTH_JWT_SECRET - To be generated from any passwords manager. Like other OMC_AUTH_[...] configurations it's meant to be set by the user.

ZGW_AUTH_JWT_SECRET - Like other ZGW_AUTH_[...] configurations to be configured and set by the user after logging to OpenZaak Web API service.

NOTIFY_API_KEY - To be generated from NotifyNL Admin Portal => API Integration section.

NOTIFY_TEMPLATEID_SMS_ZAAKCREATE - All Template IDs (SMS and Email) will be generated (and then you can copy-paste them into environment variables) when the user create (one-by-one) new templates from NotifyNL Admin Portal => Templates section.

3.1.2.3. Set environment variables

On Windows:

Additionally, environment variables can be also defined in Visual Studio's launchSettings.json file. Check the example here.

On Linux:

To be finished...

On Mac:

To be finished...

3.1.2.4. Overriding appsettings.json

As mentioned earlier, one of the two main differences between appsettings.json and environment variables is that appsettings.json are meant to hold some predefined, rarely-changing values and modifying them is not as easy for end-users as modifying environment variables.

Configurations inside of appsettings.json file are included as an embeded resource with the .NET solution and read from this file whenever requested by OMC. This means, that changing such configurations requires updating appsettings.json file, rebuilding the solution, re-creating Docker image, and then re-deploying it afterwards.

However, there is an option to override a specific appsettings.json configuration with respective environment variable, if that's intended.

To achieve this, the specific configuration needs to be set as environment variable using the UNDERSCORE_CAPITAL_CASE environment variables naming convention (similar to the one used in Python or C++ languages when defining constants) and matching the configuration name from the original appsettings.json file.

When OMC will attempt to read a configuration for the first time (before caching them), and about which it's internally known that it's present in appsettings.json, then a special "loader context" fallback strategy will prioritize checking if the environment variable overriden key is already existing in the system.

If it is existing:

then the value of this environment variable will be used;
otherwise, configuration will be taken from appsettings.json.

EXAMPLE:

You can check which configurations are present in appsettings.json file here.
Pick which configuration should be overriden.

Let's say the following "SMS_Success_Subject" configuration from appsettings.json needs to be overriden:

{
  "Variables": {
    "UxMessages": {
      "SMS_Success_Subject": "Notificatie verzonden"
    }
  }
}

Determine name of the new environment variable by translating JSON schema convention into environment variables naming convention:
3.1. Flattening the JSON schema structure to reduce the nesting:
Variables:UxMessages:SMS_Success_Subject
3.2. Replacing all special characters (:, .) by _ underscore:
Variables_UxMessages_SMS_Success_Subject
3.3. Capitalizing all remaining characters, using "upper case" convention:
VARIABLES_UXMESSAGES_SMS_SUCCESS_SUBJECT
NOTE: You can also use text editor such as Notepad++ for this task. There are even online converters available (e.g., https://convertcase.net/).
Adding new environment variable key to the system, and assigning a value to it.
Restart OMC Web API service, so the recent changes in environment variables can be reflected.
When running the application, the OMC "loader context" fallback strategy will do the same steps as stated in point 3, and try to access the given appsettings.json configuration, using its environment variable alternative key.

NOTE: The fallback strategy is working only for overriding appsettings.json configurations by environment variables, not the opposite.

3.1.2.5. Using HELM Charts

NotifyNL and OMC are meant to be used with HELM Charts (helping to install them on your local machine / server).

4. Authorization and authentication

Go back

All of the API services involved in the notifying process (OpenServices, OMC, Notify) requires some type of authorization and authentication procedure.

NOTE: some external Web API services (e.g. Open Klant v2.0 or Objecten APIs) are using predefined API keys to authenticate users and authorize them to access the service. In other cases, JWT have to be generated (and refreshed if needed).

The user of OMC doesn't have to worry which authorization method will be used behind the hood, as long as you provide valid credentials and specify which version of "OpenServices" workflow is used.

4.1. JSON Web Tokens

In the normal business workflow OMC API will ensure that valid JWT tokens would be used internally (based on the provided credentials (environment variables). However, developers testing or maintaining the solution need to generate their own JWT tokens (e.g., to access the OMC API endpoints from Swagger UI or Postman) using one of the following approaches.

4.1.1. Generating

JSON Web Token (JWT) can be generated using:

SecretsManager.exe from CLI (Command Line Interface) externally (e.g., CMD.exe on Windows, using valid credentials defined in environment variables)

The commands are defined in the Secrets Manager's documentation. NOTE: Do not use PowerShell.

An example of a simple .cmd script using one of the commands responsible for creating JWT token valid for 24 hours:

"C:\[...]\NotifyNL-OMC\EventsHandler\Logic\SecretsManager\bin\Debug\net8.0\OMC.SecretsManager.exe" 1440

pause

Users can also execute their commands directly in the catalog where SecretsManager.exe is located.

SecretsManager.dll (after referencing and importing the library) from the code (using valid credentials defined in environment variables OR overruled from launch profile in launchSettings.json in the project consuming the Secrets Manager project)

To learn more, read the documentation dedicated to Secrets Manager.

By running Secrets Manager project in Visual Studio (after selecting "Set as Startup Project" option in Solution Explorer and using valid credentials defined in environment variables OR overruled from launch profile in launchSettings.json in the Secrets Manager project)
Through the external https://jwt.io webpage (using the same credentials as those defined in environment variables).

4.1.2. Required components

Knowing all required environment variables you can fill these claims manually and generate your own JWT tokens without using Secrets Manager. This approach might be helpful if you are using OMC Web API service only as a Web API service (Swagger UI), during testing its functionality from Postman, or when using only the Docker Image.

4.1.2.1. Header (algorithm + type)

{ "alg": "HS256", "typ": "JWT" }

4.1.2.2. Payload (claims)

{ "client_id": "", "user_id": "", "user_representation": "", "iss": "", "aud": "", "iat": 0000000000, "exp": 0000000000 }

4.1.2.3. Signature (secret)

NOTE: To be filled in https://jwt.io.

4.1.3. Mapping of JWT claims from environment variables

JWT claims

OMC Environment Variables

client_id

OMC_AUTH_JWT_ISSUER

user_id

OMC_AUTH_JWT_USERID

user_representation

OMC_AUTH_JWT_USERNAME

iss

OMC_AUTH_JWT_ISSUER

aud

OMC_AUTH_JWT_AUDIENCE

iat

To be filled manually using current time

exp

iat + OMC_AUTH_JWT_EXPIRESINMIN

secret

OMC_AUTH_JWT_SECRET

NOTE: "iat" and "exp" times requires Unix formats of timestamps. The Unix timestamp can be generated using Unix converter.

4.1.4. Using generated JSON Web Token (JWT)

4.1.4.1. Postman (authorization)

After generating the JWT token you can copy-paste it in Postman to authorize your HTTP requests.

4.1.4.2. Swagger UI (authorization)

If you are using OMC Swagger UI from browser (graphic interface for OMC Web API service) then you need to copy the generated token in the following way:

And then click "Authorize".

5. OMC Workflow

Go back

Version of OMC <= 1.7.4 (using "OMC workflow v1").

5.1. Versions

The OMC API is using different configurations and setups to handle multiple complex business cases. Sometimes, it is even required to support multiple versions of the same external API services (which might be very different from each other).

NOTE: The OMC workflow can be changed using a respective environment variable in the section of features.

5.1.1. Dependencies

Here are the details which workflows are using which versions of the external API services:

OMC workflow v1 (default)

"OpenNotificaties" v1.6.0
"OpenZaak" v1.12.1
"OpenKlant" v1.0.0
"Besluiten" v1.1.0
"Objecten" v2.3.1
"ObjectTypen" v2.2.0
"Contactmomenten" v1.0.0

NOTE: This workflow is supporting only citizens (using BSN numbers).

OMC workflow v2

"OpenNotificaties" v1.6.0
"OpenZaak" v1.12.1
new "OpenKlant" v2.0.0
"Besluiten" v1.1.0
"Objecten" v2.3.1
"ObjectTypen" v2.2.0
new "Klantcontacten" v2.0.0

NOTE: This workflow is supporting both citizens (using BSN numbers) and organizations (using KVK numbers). The term used to describe such different entities is "party".

5.2. Scenarios

List of scenarios and the details how to use them with OMC (configurations, template personalizations, environment variables, business logic conditions, etc.).

5.2.1. General introduction

OMC "Scenarios" are specific processing workflows, set up in the code to handle certain business requirements: what, when, how, and which to process the "initial notification" received from a subscribed channel from a message queue implemented by Open Notificaties Web API service.

Using environment variables such as "Domains", "Whitelists", "TemplateIds", and most importantly "OMC Workflow version", the user of OMC can have some control:

what external third-party Web API services will be used (domains)
when the specific notification will be processed (whitelists)
how the recipient will see the notification (template IDs), and
which internal implementation will be used (OMC Workflow version)

Implementation of new business cases, obviously(!), requires ingeretion in the code (C#) and preparing new OMC scenarios and the processing logic (validation, conditioning, settings...).

Currently, the following business scenarios are implemented:

Opening a case
Updating a case status
Closing a case
Assignment of a task
Receiving a decision
Receiving a message

5.2.1.1. Notification

Any OMC workflow relies on receiving the (initial) notification event from Open Notificaties Web API service to trigger the processing business logic.

This notification is in JSON format.

Except of being awaited by OMC callback ([OMC]/events/listen endpoint) it can also be passed from outside to HTTP Requests while using Swagger UI or Postman - to test or simulate the desired OMC behavior. This way the initial event from Open Notificaties Web API service can be stubbed.

Using Swagger UI is recommended solution, because of its user-friendly User Interface, documentation of endpoints, parameters, remarks, JSON examples, model schemas, and validation; formatting of API responses is also better than in Postman.

5.2.1.2. Environment variables

To work properly OMC always requires these mandatory environment variables to be set:

NOTE: If some environment variable is missing but required by one of the countless scenarios, conditions, or workflows, the OMC application will return a readable and user-friendly API response with the name of the missing environment variable. This is the easiest way to figure out what else is required.

ASPNETCORE_ENVIRONMENT

Used by [OMC]/events/version endpoint and to determine which appsettings[.xxx].json will be used.

OMC_AUTH_JWT_SECRET

OMC_AUTH_JWT_ISSUER

OMC_AUTH_JWT_AUDIENCE

OMC_AUTH_JWT_EXPIRESINMIN

OMC_AUTH_JWT_USERID

OMC_AUTH_JWT_USERNAME

Required to get access to OMC and be able to use it. Moreover, Open Notificaties Web API service will use this method to make an authorized requests while sending notification events to OMC.

OMC_FEATURE_WORKFLOW_VERSION

Without this setting (the version needs to be supported) the OMC Web API will not even run and specific implementations of underlying services will not be resolved by Dependency Injection mechanism. By default you can always use "1" if you don't know yet which other OMC Workflow version you should use.

ZGW_AUTH_JWT_SECRET

ZGW_AUTH_JWT_ISSUER

ZGW_AUTH_JWT_AUDIENCE

ZGW_AUTH_JWT_EXPIRESINMIN

ZGW_AUTH_JWT_USERID

ZGW_AUTH_JWT_USERNAME

JWT authorization is required by some versions of external API services used in certain OMC Workflow versions.

ZGW_AUTH_KEY_OPENKLANT => Required only in certain OMC Workflow versions

ZGW_AUTH_KEY_OBJECTEN

ZGW_AUTH_KEY_OBJECTTYPEN

API key authorization is required by some versions of external API services used in certain OMC Workflow versions.

ZGW_ENDPOINT_OPENZAAK

ZGW_ENDPOINT_OPENKLANT

ZGW_ENDPOINT_BESLUITEN

ZGW_ENDPOINT_OBJECTEN

ZGW_ENDPOINT_OBJECTTYPEN

ZGW_ENDPOINT_CONTACTMOMENTEN

Endpoints might have different paths (e.g., domain/something/v1/) depends on version of external API service used in certain OMC Workflow. For example domains for OpenKlant and ContactMomenten depends on version of Open Klant Web API service. Moreover, domains and paths depends on the place where your version of Web API service was deployed (domain) and the way how it is internally structured (paths).

NOTIFY_API_BASEURL

NOTIFY_API_KEY

Values required to initialize Notify HTTP client.

These environment variables are optional:

SENTRY_DSN

SENTRY_ENVIRONMENT

Logging and analytics in third-party service (Sentry.io).

5.2.1.3. Requirements

To process certain notification the specific internal criteria must be met. Usually, they are some pre-validation (analyzing the "initial notification" received from Open Notificaties Web API service), post-validation (to determine the scenario suited for this type of the notification), and whitelisting steps (to ensure that OMC should continue processing this type of notification). Sometimes, additional checks have to be performed - which depends on the specific OMC scenario.

5.2.1.4. Template placeholders

When everything is already validated, prepared, and processed, the Notify NL Web API service needs to receive instruction how to format the upcoming notification. The way how to achieve this is to set up so called "template" (using Notify NL Admin portal webpage), define ((placeholders)) in the text (subject and/or body) - matching to the ones defined by the specific OMC scenario, and then use the ID of this freshly generated "template" in respective environment variable for OMC.

5.2.1.5. Parties and preferred addresses

Once the parties have been identified, the next step is to select a method and address for contacting them. The first selection is based on the case identifier (V2 CaseDetails Identification). If an address exists that matches the case identifier, it will be used. If no match is found, the system will check for a preferred address. If neither a preferred address nor a case identifier match is found, the fallback address will be used.

6. Errors

Go back

List of validation (format, requirements), connectivity or business logic processing errors that you might encounter during accessing OMC API endpoints.

General errors:

HTTP Status Code: 401 Unauthorized

Invalid JWT token:
Invalid JWT secret:

6.1. Events Controller

Endpoints:

POST .../Events/Listen
GET .../Events/Version

6.1.1. Possible errors

HTTP Status Code: 206 Partial Content

Test notification received:

NOTE: Open Notificaties API is sending test notifications to ensure whether OMC is able to receive incoming notifications.

Not implemented scenario:

HTTP Status Code: 422 Unprocessable Entity

Invalid JSON payload (syntax error):
Invalid data model (missing required fields):

NOTE: Multiple propertis are supported (comma-separated).

Invalid data model (unexpected fields):

NOTE: Multiple propertis are supported (comma-separated).

HTTP Status Code: 500 Internal Server Error

Any eventual (however unlike) unhandled exceptions will be reported as 500.

HTTP Status Code: 501 Not Implemented

Other cases (than not implemented business case scenarios) may raise 501 errors. This is however highly unlikely and might occur mainly in the development phase.

6.2. Notify Controller

Endpoints:

POST .../Notify/Confirm

6.2.1. Possible errors

HTTP Status Code: 400 Bad Request

HTTP Request error

Something went wrong when calling external API services: OpenZaak, OpenKlant, contactmomenten...

You woull get the following outcome (separated by pipes): OMC | Log severity (Error / Warning / Info / Debug) | The first possible error message* | Full URL to which request was tried to be send | The original JSON response from the called service** | Notification: The initial notification

* That interrupted the happy path workflow due to connectivity issues, invalid configuration values, or service being down. Unfortunately, due to complexity of the system, the variety of potential errors is quite broad.

** WARNING: For some mysterious reasons, authors of the third-party software (used in OMC-NotifyNL workflow) decided to communicate back with the user of their API (Application Public Interface - through publicly accessible World Wide Web network) by using one of the local languages. You might need to translate those received JSON Response messages into English.

NOTE: Unfortunately, OMC Development Team cannot provide meaningful guidance how the external services were developed or configured.

6.3. Test Controller

6.3.1. Testing Notify

Endpoints:

GET .../Test/Notify/HealthCheck
POST .../Test/Notify/SendEmail
POST .../Test/Notify/SendSms

6.3.1.1. Possible errors

a) Common for SendEmail + SendSms

HTTP Status Code: 403 Forbidden

Invalid base URL (NotifyNL API service):
Invalid format of API key or it is missing (NotifyNL API service):
Invalid API key - it was not registered for this NotifyNL API service:

HTTP Status Code: 400 Bad Request

Template UUID is invalid:
Template not found:
Missing required personalization (or the default example was used):

b) SendEmail

Missing required parameters:

HTTP Status Code: 400 Bad Request

Email is empty (only whitespaces):
Email is invalid (missing @, dot, domain, etc.):

c) SendSms

Missing required parameters:

HTTP Status Code: 400 Bad Request

Phone number is empty (only whitespaces):
Phone number contains letters or symbols:
Phone number contains not enough digits:
Phone number contains too many digits:
Phone number has incorrect format (e.g., country code is not supported):

6.3.2. Testing Open services

Endpoints:

POST .../Test/Open/ContactRegistration

6.3.2.1. Possible errors

To be finished...

PreviousNotify NL API Documentatie (REST)

Last updated 11 months ago

hashtag1. Introduction

hashtag1.1. Swagger UI

hashtag1.1.1. Using web browser

hashtag1.1.2. Using IDE (Visual Studio)

hashtag1.2. Docker

hashtag2. Architecture

hashtag3. Setup

hashtag3.1. Configurations

hashtag3.1.1. appsettings.json

hashtag3.1.2. Environment variables

hashtag4. Authorization and authentication

hashtag4.1. JSON Web Tokens

hashtag4.1.1. Generating

hashtag4.1.2. Required components

hashtag4.1.3. Mapping of JWT claims from environment variables

hashtag4.1.4. Using generated JSON Web Token (JWT)

hashtag5. OMC Workflow

hashtag5.1. Versions

hashtag5.1.1. Dependencies

hashtag5.2. Scenarios

hashtag5.2.1. General introduction

hashtag6. Errors

hashtag6.1. Events Controller

hashtag6.1.1. Possible errors

hashtag6.2. Notify Controller

hashtag6.2.1. Possible errors

hashtag6.3. Test Controller

hashtag6.3.1. Testing Notify

hashtag6.3.2. Testing Open services

1. Introduction

1.1. Swagger UI

1.1.1. Using web browser

1.1.2. Using IDE (Visual Studio)

1.2. Docker

2. Architecture

3. Setup

3.1. Configurations

3.1.1. appsettings.json

3.1.2. Environment variables

4. Authorization and authentication

4.1. JSON Web Tokens

4.1.1. Generating

4.1.2. Required components

4.1.3. Mapping of JWT claims from environment variables

4.1.4. Using generated JSON Web Token (JWT)

5. OMC Workflow

5.1. Versions

5.1.1. Dependencies

5.2. Scenarios

5.2.1. General introduction

6. Errors

6.1. Events Controller

6.1.1. Possible errors

6.2. Notify Controller

6.2.1. Possible errors

6.3. Test Controller

6.3.1. Testing Notify

6.3.2. Testing Open services