DOSIS

Inleiding

DOSIS staat voor DOssier Status Informatie Systeem. DOSIS verzamelt en ontsluit informatie over de aanwezigheid en status van een dossier bij een Vlaamse of lokale overheidsdienst. Het is mogelijk om je dienstverlening aan te sluiten op DOSIS en statusupdates voor concrete dossiers door te geven via API. De dossierstatus wordt dan zichtbaar op platformen als Mijn Burgerprofiel, het Verenigingsloket of het eLoket voor ondernemingen.

Protocol

Onboardingprocedure gebeurt per dienstverlening die je met DOSIS wil koppelen en staat beschreven op de documentatiesite van de Digitaal Vlaanderen. Grosso modo doorloop je onderstaande stappen.

Vul het aansluitingsformulier in bij elke nieuwe aansluiting.
DOSIS zet de testomgeving op en bezorgt je een OAuth clientId voor toegang tot de testomgeving.
Log in bij het beheerdersportaal om de OAuth clientID te beheren en er een gevalideerde public key (certificaat onder de vorm van .jwks-bestand) op te laden.
Koppelen met testomgeving en valideren van de connectie.
DOSIS zet de productieomgeving op en bezorgt je een OAuth clientId voor toegang tot de productieomgeving.
Log in bij het beheerdersportaal om de OAuth clientID te beheren en er een gevalideerde public key (certificaat onder de vorm van .jwks-bestand) op te laden.
Koppelen met productieomgeving en verder operationaliseren.

Deze stappen zijn in grote lijnen dezelfde als voor aansluiting met MAGDA.

Applicatie eigenschappen

Specifiek voor DOSIS (los van de eigenschappen die de toegang regelen).

Eigenschap	Default	Beschrijving
DosisTechnicalConnectorConfig
`skryv.connectors.dosis.esb`	`false`	Use ESB endpoint
`skryv.connectors.dosis.esb.basicAuth.username`	null	ESB basic auth username
`skryv.connectors.dosis.esb.basicAuth.password`	null	ESB basic auth password
`skryv.connectors.dosis.esb.privateKey`	null	ESB private key
`skryv.connectors.dosis.esb.privateKeyPassword`	null	ESB private key password
`skryv.connectors.dosis.esb.certificate`	null	ESB certificate
`skryv.connectors.dosis.oauth2.client.*`	null	OAuth2 client credentials properties
DosisBusinessConnector
`skryv.connectors.dosis.status.update.url`	null	DOSIS status update URL
`skryv.connectors.dosis.status.delete.url`	null	DOSIS status delete URL
`skryv.connectors.dosis.bron`	null	Aanduiding van de bron van waaruit je applicatie statusupdates doorstuurt. Uitleg over het begrip ‘bron’.
`skryv.connectors.dosis.productId`	null	Productcode voor je dienstverlening. Uitleg over ProductId of IDPC.
DosisCredentialsTokenFetcher
`skryv.connectors.geosecure.dosis.scope`	`dv_dosis_import`	GeoSecure OAuth scope. Scope van je machtiging binnen DOSIS. Dit bepaalt welke acties je mag uitvoeren.
`skryv.connectors.geosecure.dosis.request-path`	`https://authenticatie-ti.vlaanderen.be/op/v1/token`	Url waar de applicatie op inlogt om vervolgens een token te verkrijgen waarmee de veilige communicatie tot stand gebracht kan worden.
`skryv.connectors.geosecure.dosis.appnumber`	null	GeoSecure app number. Client Id voor je applicatie. Hiermee moet je inloggen op het beheerdersportaal.
`skryv.connectors.geosecure.dosis.aws.keypath`	null	GeoSecure keypath. Pad naar private key in AWS Secrets Manager.
`skryv.connectors.geosecure.dosis.aws.seed.enabled`	`false`	Waarde: boolean. Indien `true` worden authenticatiegegevens opgehaald uit AWS Secrets Manager. Indien `false`, dan worden de lokaal opgeslagen authenticatiegegevens gebruikt.
`skryv.connectors.geosecure.dosis.keypath`	null	Pad naar lokale opslag van je key pair.
`skryv.connectors.geosecure.jwks`	null	GeoSecure JWKS URL.

Services en functies

sendDosisStatusUpdate

Functie gebruikt om een statusupdate door te sturen naar DOSIS. Alle parameters zijn instelbaar via de Studio service taak template ‘DOSIS - Verzend statusupdate’. Een verouderde implementatie maakt nog gebruik van een signal throw intermediate event (zie ook het concept mijlpaal).

Workflow expressies

CODE

// 1. Zonder modificationDate
${dosis.sendDosisStatusUpdate(agentIdentificatie, agentToegangsrecht, statusVlaamsFase, statusVlaamsCode, statusDetail1, statusActie, dossierLabel, dossierNaam, doorverwijzing, contactNaam, contactDepartement, contactTelefoon, contactEmail, contactWebsite, productId)}

// 2. Met modificationDate als String (formaat: YYYY-MM-DDTHH:MM:SSZ)
${dosis.sendDosisStatusUpdate(agentIdentificatie, agentToegangsrecht, statusVlaamsFase, statusVlaamsCode, statusDetail1, statusActie, dossierLabel, dossierNaam, doorverwijzing, contactNaam, contactDepartement, contactTelefoon, contactEmail, contactWebsite, productId, modificationDate)}

// 3. Via map (verouderd - voor gebruik in combinatie met mijlpaal)
${dosis.sendDosisStatusUpdate(dosisMap, dosisAgents, milestoneId)}

Input

Zie signaturen 1 en 2 bij workflow expressies.

Parameters in te stellen via de service taak template verzend statusupdate.

Inputparameters	Data type	Verplicht?	Voorbeeld	Uitleg
agentIdentificatie	String	Ja	80102529724	Identificatie van de agent die het dossier mag raadplegen. Rijksregisternummer voor burgers, KBO-nummer voor ondernemingen, V-code voor verenigingen.
agentToegangsrecht	String	Ja	[Raadpleger]	Toegangsrecht van de agent. Vaste waarde `Raadpleger` voor burgers (case-sensitive). Voor ondernemers de ACM/IDM-rol, bv. `Wettelijk vertegenwoordiger`. Meerdere rechten mogelijk als kommalijst tussen vierkante haken: `[Raadpleger, Beheerder]`. De waarde wordt als string doorgegeven met vierkante haken, ook bij één recht. De connector splitst deze intern op.
statusVlaamseFase	String	Ja	Behandeling	Fase in de levenscyclus van het dossier. Zie Vlaamse Fasen. Mogelijke waarden: `Samenstelling`, `Behandeling`, `Beslissing`, `Uitvoering`, `Afgerond`.
statusVlaamseCode	String	Ja	InBehandeling	Gedetailleerde statuscode binnen de fase. Zie Vlaamse Codes. Voorbeelden: `Aangevraagd`, `InBehandeling`, `Goedgekeurd`, `Geweigerd`. Let op: technische codes bevatten geen spaties of trema's (bv. `Geinitieerd`, niet `Geïnitieerd`).
statusDetail1	String	Optie	Uw dossier is in behandeling bij de bevoegde ambtenaar.	Vrije tekst die de huidige status verder toelicht voor de burger of ondernemer. Optioneel.
statusActie	String	Optie	U dient nog ontbrekende documenten aan te leveren via het loket.	Omschrijving van de actie die de burger/ondernemer moet ondernemen. Enkel invullen als er effectief een actie vereist is; leeglaten indien niet van toepassing.
dossierLabel	String	Ja	VRG-2024-001234	Uniek dossiernummer zoals het in het eigen systeem gekend is. Vormt samen met `bron` de unieke dossieridentificatie binnen DOSIS.
dossierNaam	String	Ja	Vergunning tuinhuis Molenstraat 12	Leesbare naam van het dossier, zichtbaar voor de burger in Mijn Burgerprofiel. Bv. `Bossubsidie Molenstraat`, `Jobbonus 2024`.
doorverwijzing	String	Optie	https://loket.gemeente.be/dossier/VRG-2024-001234	URL naar de detailpagina van het dossier in het eigen systeem. Bij voorkeur een SSO-beveiligde link zodat de burger meteen toegang krijgt. Optioneel.
contactNaam	String	Optie *	Jan Janssen	Naam van de dossierbeheerder of contactpersoon. Zichtbaar voor de burger als aanspreekpunt bij vragen.
contactDepartement	String	Optie *	Dienst Ruimtelijke Ordening	Dienst of afdeling verantwoordelijk voor het dossier.
contactTelefoon	String	Optie *	025537202	Telefoonnummer van de dossierbeheerder.
contactEmail	String	Optie *	ro@gemeente.be	E-mailadres van de dossierbeheerder.
contactWebsite	String	Optie *	https://www.gemeente.be/bouwen-verbouwen	Website met meer informatie over de dienstverlening.
productId	String	Ja	1710	IPDC-productnummer van de dienstverlening. Verplicht veld. Raadpleeg de IPDC-productencatalogus voor het correcte nummer. Indien geconfigureerd via applicatie-eigenschap `skryv.connectors.dosis.productId`, wordt die waarde gebruikt en wordt deze parameter genegeerd.
modificationDate	String	Optie **	2024-03-19T10:30:00Z	Tijdstip waarop de statuswijziging effectief plaatsvond. Formaat: `YYYY-MM-DDTHH:MM:SSZ` (tijdzone verplicht). Indien weggelaten, wordt de huidige systeemtijd gebruikt.

Opmerking 1 bij signaturen 1 & 2 *

Contactgegevens als groep: de volledige dossierbeheerder-sectie (contactNaam, contactDepartement, contactTelefoon, contactEmail, contactWebsite) is optioneel. Indien je echter één of meerdere van deze velden invult, moet minstens één contactgegeven een waarde hebben — een volledig lege dossierbeheerder wordt door DOSIS geweigerd.

Opmerking 2 bij signaturen 1 & 2 **

Standaard gebruikt de connector de huidige systeemtijd als tijdstip van de statuswijziging. Dit kan tot onjuiste informatie leiden wanneer een DOSIS-call mislukt en pas later opnieuw wordt uitgevoerd — bv. via een retry-mechanisme of na manuele interventie.

Voorbeeld: een dossier bereikt op dinsdag de status "Goedgekeurd", maar de DOSIS-call faalt. De call slaagt uiteindelijk pas op donderdag. Zonder modificationDate toont Mijn Burgerprofiel donderdag als datum van de statuswijziging, wat inhoudelijk onjuist is.

Geef in dat geval de modificationDate expliciet mee met het werkelijke tijdstip waarop de status bereikt werd. De waarde wordt dan zowel als wijzigingsdatum van het dossier als van de status naar DOSIS doorgestuurd.

De modificationDate vul je best in met een procesvariabele die je aanmaakt via een listener op basis van een workflow script.

CODE

// JavaScript script task (scriptFormat="javascript")
var Instant = java.time.Instant;
execution.setVariable('dosisTimestamp', Instant.now().toString());

Zie signatuur 3 (met mijlpaal) bij workflow expressies.

Deze signatuur is verouderd en maakt gebruik van deze intermediate signal throw event Skryv template. Gebruik signatuur 1 en 2 via service taak template.

Inputparameters	Data type	Verplicht?	Voorbeeld	Uitleg
dosisMap	Map<String, String>	Ja	Zie opmerking 1 hieronder, vereiste sleutels in `dosisMap`.	Inhoudelijke info voor DOSIS-call.
dosisAgents	List<Map<String, String>>	Ja	Zie opmerking 1 hieronder, vereiste sleutels in `dosisAgents`.	Inhoudelijke info voor DOSIS-call.
milestoneId	String	Ja	3f2a9c74-8b61-4e15-a2d9-5c7e1fb0de42	Unieke Id (GUID) voor de mijlpaal.

Opmerking 1 bij signatuur 3 (met mijlpaal)

Sleutels in dosisMap.

Verplicht	Optioneel
VlaamsCode	Detail
VlaamsFase	DossierLink
Actie	modificationDate ***
DossierLabel	Naam1 *
Naam **	Department *
Product id	Telefoon *
	Email *
	Website *

Contactgegevens (zie * ) zijn optioneel, maar van zodra je er één meegeeft, moet je ze allemaal meegeven.
Met Naam (**) bedoelen we de naam van het dossier zoals dit in Mijn Burgerprofiel zichtbaar zal zijn.
De modificationDate (***) is het expliciet gedefinieerde tijdstip voor de DOSIS-update. Indien niet toegevoegd gebruiken we de systeemtijd.

Sleutels in dosisAgents.

Verplicht	Optioneel
Identificatie	-
Toegangsrechten	-

Opmerking 2 bij signatuur 3 (met mijlpaal)

Bij afwezigheid van een milestoneId kan je de composite service bean aanroepen.

CODE

connDosis.sendDosisStatusUpdate(dosisMap, dosisAgents, dossierId)

Output

De methode retourneert een DosisResponse-object. Omdat DOSIS asynchroon verwerkt, betekent een succesvolle response (HTTP 200) enkel dat de statusupdate correct ontvangen is — niet dat de verwerking al voltooid is.

Veld	Java type	JSON-key	Uitleg
status	String	“Status”	Verwerkingsstatus van de DOSIS-aanroep (bv. `"OK"`)
uploadId	String	“UploadId”	De UUID die bij de request meegestuurd werd; bruikbaar om het verwerkingsresultaat asynchroon op te vragen

Het uploadId dat bij de request meegestuurd wordt (intern gegenereerd als UUID), kan gebruikt worden om via de DOSIS API achteraf het verwerkingsresultaat op te vragen:

CODE

GET /api/v1/dosis/resultaten/perUploadId?uploadId={uploadId}

Foutafhandeling

Bij een HTTP 4xx of 5xx gooit de connector respectievelijk een BpmnError met code dosis-client-error of dosis-server-error, die je in het BPMN-proces kan opvangen via een error catch boundary event.

Indien je deze BPMN-errors niet opvangt, dan moet je verplicht volgende Camunda workflow eigenschap instellen: skryv.camunda.enableExceptionsAfterUnhandledBpmnError=true. Zoniet leidt dit tot ongewenst gedrag binnen het dossier.

deleteDossier

Functie gebruikt om een in DOSIS gekend dossier te schrappen.

Workflow expressie

${dosis.deleteDossier(dossierNummer)}

Input

Inputparameters	Data type	Voorbeeld	Uitleg
dossierNummer	String	-	Dossier Id die je doorgegeven hebt aan DOSIS.

Output

Geen output.