Ga naar hoofdinhoud

Als bronorganisatie

Benodigde componenten

De voor de bronorganisatie benodigde componenten worden weergegeven in onderstaand model. Dit model is opgebouwd volgens de vijf-lagen architectuur van Common Ground.

Componenten bronorganisatie

Componenten voor beheer

Binnen het domein van de bronorganisatie zijn de volgende componenten nodig:

  • bk-management-ui - bevat de user interface voor het functioneel beheer van de configuratie van de bronorganisatie en de aansluiting op het stelsel.
  • bk-management-process - bevat de business logica voor het beheer van de configuratie van de bronorganisatie en de aansluiting op het stelsel.
  • bk-config-service - ontsluit het register met de configuratie van de bronorganisatie.
  • bk-config-db - het register voor het persisteren van de configuratie van de bronorganisatie.

Component voor het discoveren van de externe addresseerbare componenten

  • service-discovery-process - bevat de urls naar de extern addresserbaar componenten citizen-financial-claim-process en session-process.

Componenten voor het opzetten van veilige verbindingen

  • session-process - bevat de business logica voor de processen om beveiligde sessies tussen de burger en de bronorganisatie op te zetten en te beheren.
  • session-service - ontsluit het register met informatie over beveiligde sessies tussen de burger en bronorganisatie (in de referentie-implementatie is dit een statefull service met in-memory register van deze sessie informatie)

Componenten voor het afhandelen van verzoeken van burgers

  • citizen-financial-claim-process - bevat de business logica voor de processen van het verzoeken om en ophalen van gegevens over financiële verplichtingen door burgers.
  • financial-claim-request-service - ontsluit het register van de ingediende verzoeken van burgers om gegevens over financiële verplichtingen op te halen.
  • financial-claim-request-db - het register voor het persisteren van de ingediende verzoeken van burgers om gegevens over financiële verplichtingen op te halen.

Voorbeeld van een bronsysteem API (mock-source-system)

In de referentie-implementatie wordt gebruik gemaakt van het financial-claim-service component als voorbeeld-implementatie van een bronsysteem. In de afbeelding hierboven zijn als voorbeeld twee instanties van dat component getoond, één waarbij een API als apart component boven het bronsysteem is gezet, en één waarbij de API geïmplementeerd is als onderdeel van het bronsysteem.

Databasecomponenten

Voor alle *-db-componenten wordt in de referentie-implementatie een postgres database server gebruikt. De afzonderlijke *-db-componenten bevatten migraties om deze databases in te richten.

Beschikbaarheid en afhankelijkheden

De componenten service-discovery-process, citizen-financial-claim-process en session-process moeten publiek addresseerbaar zijn via internet, zodat de burger er mee kan verbinden.

De componenten bk-management-ui en bk-management-process moeten intern addresseerbaar zijn voor de functioneel beheerder.

De componenten citizen-financial-claim-process en bk-management-process moeten naar buiten toe contact op kunnen nemen met de stelselbeheerder.

Het installeren en configureren van componenten

Postgres database server

De postgres database server kan als volgt worden opgestart. De postgres docker image biedt ook mogelijkheden voor optionele configuratie.

docker run \
-e POSTGRES_PASSWORD=SECRET_POSTGRES_PASSWORD \
postgres

bk-config-db

Het bk-config-db kan geconfigureerd worden met een aantal environment variables

Het bk-config-db component kan gestart worden met behulp van docker:

docker run \
-e PGHOST="postgres-host" \
-e PGUSER="postgres-user" \
-e PGPASSWORD="SECRET_POSTGRES_PASSWORD" \
-e PGDATABASE="bk_config_db" \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/bk-config-db

Toelichting op de configuratie:

ParameterToelichting
PGHOSTMoet ingesteld staan op het intern adres waar de postgres database server van de bronorganisatie bereikbaar is.
PGUSERMoet ingesteld staan op de gebruikersnaam waarmee er ingelogd kan worden op de postgres database server van de bronorganisatie.
PGPASSWORDMoet ingesteld staan op het wachtwoord waarmee er ingelogd kan worden op de postgres database server van de bronorganisatie.
PGDATABASEMoet ingesteld staan op bk_config_db.

Een voorbeeld helm chart is beschikbaar op GitLab

bk-config-service

Het bk-config-service kan geconfigureerd worden met een aantal environment variables

Het bk-config-service component kan gestart worden met behulp van docker:

docker run -p 8082:80 \
-e APIKey="SECRET_API_KEY" \
-e BK_CONFIG_DB_HOST="postgres-host" \
-e BK_CONFIG_DB_USERNAME="postgres-user" \
-e BK_CONFIG_DB_PASSWORD="SECRET_POSTGRES_PASSWORD" \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/bk-config-service

Toelichting op de configuratie:

ParameterToelichting
API_KEYMoet ingesteld staan op een geheime API key waarmee de andere componenten toegang kunnen krijgen tot deze service.
BK_CONFIG_DB_HOSTMoet ingesteld staan op het intern adres waar de postgres database server van de bronorganisatie bereikbaar is.
BK_CONFIG_DB_USERNAMEMoet ingesteld staan op de gebruikersnaam waarmee er ingelogd kan worden op de postgres database server van de bronorganisatie.
BK_CONFIG_DB_PASSWORDMoet ingesteld staan op het wachtwoord waarmee er ingelogd kan worden op de postgres database server van de bronorganisatie.

Een voorbeeld helm chart is beschikbaar op GitLab

bk-management-process

Het bk-management-process kan geconfigureerd worden met een aantal environment variables

Het bk-management-process component kan gestart worden met behulp van docker:

docker run -p 8080:80 \
-e SCHEME_DISCOVERY_URL="https://demo-scheme-manager-scheme-process" \
-e BK_CONFIG_SERVICE_ADDRESS="http://bk-config-service" \
-e BK_CONFIG_SERVICE_API_KEY="SECRET_BK_CONFIG_SERVICE_API_KEY" \
-e ORGANIZATION_NAME="Demo Organization" \
-e ORGANIZATION_OIN="00000000000000000001" \
-e ORGANIZATION_DISCOVERY_URL="https://demo-organization-service-discovery-process" \
-e ORGANIZATION_LOGO_URL="https://demo-organization-logo-url" \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/bk-management-process

Toelichting op de configuratie:

ParameterToelichting
SCHEME_DISCOVERY_URLMoet ingesteld staan op het extern adres waar het scheme-process component van de stelselbeheerder bereikbaar is. De url van de Vorderingenoverzicht Rijk Demo omgeving is https://api.stelsel.vorijk-demo.blauweknop.app/v1.
BK_CONFIG_SERVICE_ADDRESSMoet ingesteld staan op het interne adres waar het bk-config-service component van de bronorganisatie bereikbaar is.
BK_CONFIG_SERVICE_API_KEYMoet ingesteld staan op de API key waarmee bk-management-process toegang kan krijgen tot het bk-config-service van de bronorganisatie.
ORGANIZATION_NAMEMoet ingesteld staan op de naam van de bronorganisatie.
ORGANIZATION_OINMoet ingesteld staan op het organisatie-identificatienummer (OIN) van de bronorganisatie.
ORGANIZATION_DISCOVERY_URLMoet ingesteld staan op het extern adres waar het service-discovery-process component van de bronorganisatie bereikbaar is.
ORGANIZATION_LOGO_URLMoet ingesteld staan op de een url naar de logo van de bronorganisatie.
Helm chart

Een voorbeeld helm chart is beschikbaar op GitLab

bk-management-ui

Het bk-management-ui kan geconfigureerd worden met een aantal environment variables

Het bk-management-ui component kan gestart worden met behulp van docker:

docker run -p 8081:80 \
-e BK_MANAGEMENT_URL="https://demo-organization-bk-management-process" \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/bk-management-ui

Toelichting op de configuratie:

ParameterToelichting
BK_MANAGEMENT_URLMoet ingesteld staan op het extern adres (intranet) waar het bk-management-process component van de bronorganisatie bereikbaar is.

Een voorbeeld helm chart is beschikbaar op GitLab

service-discovery-process

Het service-discovery-process kan geconfigureerd worden met een json bestand.

Creëer een map config, met daarin een bestand genaamd bk-configuration.json:

{
"financialClaimRequestApi": {
"v3": "https://demo-organization-citizen-financial-claim-process"
},
"sessionApi": {
"v1": "https://demo-organization-session-process"
}
}

Het service-discovery-process component kan gestart worden met behulp van docker:

docker run -p 8088:80 \
-v "$PWD/config":/var/www/.well-known \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/service-discovery-process

Een voorbeeld helm chart is beschikbaar op GitLab

session-service

Het session-service kan geconfigureerd worden met een aantal environment variables

Het session-service component kan gestart worden met behulp van docker:

docker run -p 8083:80 \
-e APIKey="SECRET_API_KEY" \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/session-service

Toelichting op de configuratie:

ParameterToelichting
API_KEYMoet ingesteld staan op een geheime API key waarmee de andere componenten toegang kunnen krijgen tot deze service.

Een voorbeeld helm chart is beschikbaar op GitLab

session-process

Het session-process kan geconfigureerd worden met een aantal environment variables

Het session-process component kan gestart worden met behulp van docker:

docker run -p 8084:80 \
-e SESSION_SERVICE_ADDRESS="http://demo-organization-session-service" \
-e SESSION_SERVICE_API_KEY="SECRET_SESSION_SERVICE_API_KEY" \
-e BK_CONFIG_SERVICE_ADDRESS="http://demo-organization-bk-config-service" \
-e BK_CONFIG_SERVICE_API_KEY="SECRET_BK_CONFIG_SERVICE_API_KEY" \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/session-process

Toelichting op de configuratie:

ParameterToelichting
SESSION_SERVICE_ADDRESSMoet ingesteld staan op het interne adres waar het session-service component van de bronorganisatie bereikbaar is.
SESSION_SERVICE_API_KEYMoet ingesteld staan op de API key waarmee session-process toegang kan krijgen tot het session-service van de bronorganisatie.
BK_CONFIG_SERVICE_ADDRESSMoet ingesteld staan op het interne adres waar het bk-config-service component van de bronorganisatie bereikbaar is.
BK_CONFIG_SERVICE_API_KEYMoet ingesteld staan op de API key waarmee session-process toegang kan krijgen tot het bk-config-service van de bronorganisatie.

Een voorbeeld helm chart is beschikbaar op GitLab

financial-claim-request-db

Het financial-claim-request-db kan geconfigureerd worden met een aantal environment variables

Het financial-claim-request-db component kan gestart worden met behulp van docker:

docker run \
-e PGHOST="postgres-host" \
-e PGUSER="postgres-user" \
-e PGPASSWORD="SECRET_POSTGRES_PASSWORD" \
-e PGDATABASE="financial_claim_request_db" \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/financial-claim-request-db

Toelichting op de configuratie:

ParameterToelichting
PGHOSTMoet ingesteld staan op het intern adres waar de postgres database server van de bronorganisatie bereikbaar is.
PGUSERMoet ingesteld staan op de gebruikersnaam waarmee er ingelogd kan worden op de postgres database server.
PGPASSWORDMoet ingesteld staan op het wachtwoord waarmee er ingelogd kan worden op de postgres database server.
PGDATABASEMoet ingesteld staan op financial_claim_request_db.

Een voorbeeld helm chart is beschikbaar op GitLab

financial-claim-request-service

Het financial-claim-request-service kan geconfigureerd worden met een aantal environment variables

Het financial-claim-request-service component kan gestart worden met behulp van docker:

docker run -p 8085:80 \
-e APIKey="SECRET_API_KEY" \
-e FINANCIAL_CLAIM_REQUEST_DB_HOST="postgres-host" \
-e FINANCIAL_CLAIM_REQUEST_DB_USERNAME="postgres-user" \
-e FINANCIAL_CLAIM_REQUEST_DB_PASSWORD="SECRET_POSTGRES_PASSWORD" \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/financial-claim-request-service

Toelichting op de configuratie:

ParameterToelichting
API_KEYMoet ingesteld staan op een geheime API key waarmee de andere componenten toegang kunnen krijgen tot deze service.
FINANCIAL_CLAIM_REQUEST_DB_HOSTMoet ingesteld staan op het intern adres waar de postgres database server van de bronorganisatie bereikbaar is.
FINANCIAL_CLAIM_REQUEST_DB_USERNAMEMoet ingesteld staan op de gebruikersnaam waarmee er ingelogd kan worden op de postgres database server van de bronorganisatie.
FINANCIAL_CLAIM_REQUEST_DB_PASSWORDMoet ingesteld staan op het wachtwoord waarmee er ingelogd kan worden op de postgres database server van de bronorganisatie.

Een voorbeeld helm chart is beschikbaar op GitLab

mock-source-system (Voorbeeld van een bronsysteem API)

Het mock-source-system kan geconfigureerd worden met een aantal environment variables

Het mock-source-system component kan gestart worden met behulp van docker:

docker run -p 8087:80 \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/mock-source-system

Toelichting op de configuratie:

ParameterToelichting

Een voorbeeld helm chart is beschikbaar op GitLab

citizen-financial-claim-process

Het citizen-financial-claim-process kan geconfigureerd worden met een aantal environment variables

Het citizen-financial-claim-process component kan gestart worden met behulp van docker:

docker run -p 8086:80\
-e SCHEME_DISCOVERY_URL="https://demo-scheme-manager-scheme-process" \
-e FINANCIAL_CLAIM_REQUEST_SERVICE_ADDRESS="http://demo-organization-financial-claim-request-service" \
-e FINANCIAL_CLAIM_REQUEST_SERVICE_API_KEY="SECRET_FINANCIAL_CLAIM_REQUEST_SERVICE_API_KEY" \
-e SESSION_SERVICE_ADDRESS="http://demo-organization-session-service" \
-e SESSION_SERVICE_API_KEY="SECRET_SESSION_SERVICE_API_KEY" \
-e BK_CONFIG_SERVICE_ADDRESS="http://demo-organization-bk-config-service" \
-e BK_CONFIG_SERVICE_API_KEY="SECRET_BK_CONFIG_SERVICE_API_KEY" \
-e SOURCE_SYSTEM_ADDRESSES="https://demo-organization-discovery-url" \
registry.gitlab.com/blauwe-knop/vorderingenoverzicht/citizen-financial-claim-process

Toelichting op de configuratie:

ParameterToelichting
SCHEME_DISCOVERY_URLMoet ingesteld staan op het extern adres waar het scheme-process component van de stelselbeheerder bereikbaar is. De url van de Vorderingenoverzicht Rijk Demo omgeving is https://api.stelsel.vorijk-demo.blauweknop.app/v1.
FINANCIAL_CLAIM_REQUEST_SERVICE_ADDRESSMoet ingesteld staan op het interne adres waar het financial-claim-request-service component van de bronorganisatie bereikbaar is.
FINANCIAL_CLAIM_REQUEST_SERVICE_API_KEYMoet ingesteld staan op de API key waarmee citizen-financial-claim-process toegang kan krijgen tot het financial-claim-request-service van de bronorganisatie.
SESSION_SERVICE_ADDRESSMoet ingesteld staan op het interne adres waar het session-service component van de bronorganisatie bereikbaar is.
SESSION_SERVICE_API_KEYMoet ingesteld staan op de API key waarmee citizen-financial-claim-process toegang kan krijgen tot het session-service van de bronorganisatie.
BK_CONFIG_SERVICE_ADDRESSMoet ingesteld staan op het interne adres waar het bk-config-service component van de bronorganisatie bereikbaar is.
BK_CONFIG_SERVICE_API_KEYMoet ingesteld staan op de API key waarmee session-process toegang kan krijgen tot het bk-config-service van de bronorganisatie.
SOURCE_SYSTEM_ADDRESSESMoet ingesteld staan op het interne adressen waar het source-system component van de bronorganisatie bereikbaar zijn. Gebruik bij meerdere bronsystemen een ; tussen de adressen

Een voorbeeld helm chart is beschikbaar op GitLab

Voorbeeld helm installatie voor de Vorderingenoverzicht Rijk demo omgeving

Hieronder kun je een voorbeeld implemenatie vinden als bronorganisatie om te kunnen communiceren met de Vorderingenoverzicht Rijk demo omgeving.

In deze voorbeeldinstallatie (op basis van helm) gebruiken we als bronorganisatie Testorganisatie. Vervang alle testorganisatie waarden door die van je eigen bronorganisatie en vervang ook het organisatie-identificatienummer (OIN) in de componenten demo-source-system en bk-management-process door je eigen OIN.

Kubernetes operator voor PostgreSQL, CloudNativePG:

helm repo add cnpg https://cloudnative-pg.github.io/charts

helm upgrade --install cnpg \
--namespace cnpg-system \
--create-namespace \
cnpg/cloudnative-pg

Vorderingenoverizcht Rijk componenten:

helm repo add vorijk https://blauwe-knop.gitlab.io/vorderingenoverzicht/charts

helm upgrade --install bk-config-db \
--namespace testorganisatie \
--create-namespace \
vorijk/bk-config-db

helm upgrade --install financial-claim-request-db \
--namespace testorganisatie \
vorijk/financial-claim-request-db

helm upgrade --install bk-config-service \
--namespace testorganisatie \
--set config.containerPort=8008 \
vorijk/bk-config-service

helm upgrade --install financial-claim-request-service \
--namespace testorganisatie \
--set config.containerPort=8008 \
vorijk/financial-claim-request-service

helm upgrade --install session-service \
--namespace testorganisatie \
--set config.containerPort=8008 \
vorijk/session-service

helm upgrade --install demo-source-system \
--namespace testorganisatie \
--set config.organizationOin="00000004000000044000" \
--set config.containerPort=8008 \
vorijk/demo-source-system

helm upgrade --install session-process \
--namespace testorganisatie \
--set config.hostAddress=session-api.testorganisatie.vorijk-demo.blauweknop.app \
--set config.tlsSecretName=session-api.testorganisatie.vorijk-demo.blauweknop.app-tls \
--set config.containerPort=8008 \
vorijk/session-process

helm upgrade --install service-discovery-process \
--namespace testorganisatie \
--set config.hostAddress=testorganisatie.vorijk-demo.blauweknop.app \
--set config.tlsSecretName=testorganisatie.vorijk-demo.blauweknop.app-tls \
--set config.bkConfigurationJson='{"financialClaimRequestApi":{"v3":"https://financial-claim-request-api.testorganisatie.vorijk-demo.blauweknop.app/v3"},"sessionApi":{"v1":"https://session-api.testorganisatie.vorijk-demo.blauweknop.app/v1"}}' \
vorijk/service-discovery-process

helm upgrade --install bk-management-process \
--namespace testorganisatie \
--set config.hostAddress=management-api.testorganisatie.vorijk-demo.blauweknop.app \
--set config.tlsSecretName=management-api.testorganisatie.vorijk-demo.blauweknop.app-tls \
--set config.schemeDiscoveryUrl="https://api.stelsel.vorijk-demo.blauweknop.app/v1" \
--set config.organizationName="Testorganisatie [Demo]" \
--set config.organizationOin="00000004000000044000" \
--set config.organizationDiscoveryUrl="https://testorganisatie.vorijk-demo.blauweknop.app/.well-known/bk-configuration.json" \
--set config.organizationLogoUrl="https://blauweknop.app/images/organizations/testorganisatie.svg" \
--set config.containerPort=8008 \
vorijk/bk-management-process

helm upgrade --install citizen-financial-claim-process \
--namespace testorganisatie \
--set config.hostAddress=financial-claim-request-api.testorganisatie.vorijk-demo.blauweknop.app \
--set config.tlsSecretName=financial-claim-request-api.testorganisatie.vorijk-demo.blauweknop.app-tls \
--set config.schemeDiscoveryUrl="https://api.stelsel.vorijk-demo.blauweknop.app/v1" \
--set config.sourceSystemAddress="http://demo-source-system/v3" \
--set config.containerPort=8008 \
vorijk/citizen-financial-claim-process

helm upgrade --install demo-simulation-process \
--namespace testorganisatie \
--set config.hostAddress=demo-simulation-api.testorganisatie.vorijk-demo.blauweknop.app \
--set config.tlsSecretName=demo-simulation-api.testorganisatie.vorijk-demo.blauweknop.app-tls \
--set config.demoSourceSystemAddress="http://demo-source-system" \
--set config.containerPort=8008 \
vorijk/demo-simulation-process

helm upgrade --install bk-management-ui \
--namespace testorganisatie \
--set config.hostAddress=beheer.testorganisatie.vorijk-demo.blauweknop.app \
--set config.tlsSecretName=beheer.testorganisatie.vorijk-demo.blauweknop.app-tls \
--set config.bkManagementAddress="https://management-api.testorganisatie.vorijk-demo.blauweknop.app/v1" \
--set config.containerPort=8008 \
vorijk/bk-management-ui

Dit voorbeeld bevat 2 componenten die wij voor de demo omgeving gebruiken om data te simuleren. Deze componenten zijn demo-source-system en demo-simulation-process. In plaats hiervan dient elke bronorganisatie een eigen component welke de Financial claims information document retourneert. Dat component dient de OpenAPI specificatie van het mock-source-system te implementeren.

Toch aan de slag met de demo-source-system? Bekijk dan de volgende scripts om de demo-source-system te voorzien van data, inclusief de bijbehorende json bestanden: