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.

Use cases

• Een burger via Mijn Burgerprofiel automatisch laten zien in welke fase zijn aanvraag zich bevindt (bv. "In behandeling", "Goedgekeurd"), zonder dat hij daarvoor moet inloggen op het eigen Skryv-platform.

• Een ondernemer via het eLoket voor ondernemingen informeren dat er een actie van hem verwacht wordt (bv. ontbrekende documenten aanleveren), met een directe link naar het dossier.

• Bij het definitief afsluiten of intrekken van een dossier de status hiervan proactief bijwerken, zodat dit correct weerspiegeld wordt op Mijn Burgerprofiel of het Verenigingsloket.

• Een dossier dat per vergissing werd aangemaakt (of dat niet langer relevant is) volledig verwijderen uit DOSIS.

Setup

Opmerking vooraf

Standaard verbindt de connector rechtstreeks met DOSIS via OAuth2 (client credentials of een JWT-token via GeoSecure). Voor organisaties die via een centrale Enterprise Service Bus (ESB) moeten communiceren, biedt de connector een alternatieve configuratie met basic authentication en mTLS (een client-certificaat en private key). Activeer dit door skryv.connectors.dosis.esb=true in te stellen, samen met de esb-gerelateerde applicatie-eigenschappen. Deze modus is enkel relevant als je organisatie specifiek via een ESB met Digitaal Vlaanderen moet verbinden. In de meeste gevallen volstaat de standaard OAuth2-configuratie.

Dependency toevoegen aan pom.xml bestand

Voeg onderstaande dependency toe aan het pom.xml bestand van je applicatie. Dit zorgt ervoor dat de connector code ingeladen wordt bij de build van de applicatie.

 <dependency>
      <groupId>com.skryv.connectors</groupId>
      <artifactId>dosis</artifactId>
 </dependency>

Onboardingsprocedure

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.

1. Vul het aansluitingsformulier in bij elke nieuwe aansluiting.

2. DOSIS zet de testomgeving op en bezorgt je een OAuth clientId voor toegang tot de testomgeving.

3. 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.

4. Koppelen met testomgeving en valideren van de connectie.

5. DOSIS zet de productieomgeving op en bezorgt je een OAuth clientId voor toegang tot de productieomgeving.

6. 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.

7. Koppelen met productieomgeving en verder operationaliseren.

Applicatie eigenschappen

Setup van de connector gebeurt via onderstaande applicatie eigenschappen.

Externe documentatie

Klik hier voor alle technische documentatie langs de kant van DOSIS.

Services en functies

Overzicht

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 expressie 1

Zonder modificationDate.

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

Workflow expressie 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)}

Workflow expressie 3

Via map (verouderd - voor gebruik in combinatie met mijlpaal).

${dosis.sendDosisStatusUpdate(dosisMap, dosisAgents, milestoneId)}

Java-code 1

Zonder modificationDate.

DosisResponse response = dosis.sendDosisStatusUpdate(agentIdentificatie, agentToegangsrecht, statusVlaamsFase, statusVlaamsCode, statusDetail1, statusActie, dossierLabel, dossierNaam, doorverwijzing, contactNaam, contactDepartement, contactTelefoon, contactEmail, contactWebsite, productId);

Java-code 2

Met modificationDate als String (formaat: YYYY-MM-DDTHH:MM:SSZ).

DosisResponse response = dosis.sendDosisStatusUpdate(agentIdentificatie, agentToegangsrecht, statusVlaamsFase, statusVlaamsCode, statusDetail1, statusActie, dossierLabel, dossierNaam, doorverwijzing, contactNaam, contactDepartement, contactTelefoon, contactEmail, contactWebsite, productId, modificationDate);

Java-code 3

Via map (verouderd - voor gebruik in combinatie met mijlpaal).

DosisResponse response = dosis.sendDosisStatusUpdate(dosisMap, dosisAgents, milestoneId);

Input

Zie signaturen 1 en 2 bij workflow expressies en Java-code snippets.

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.

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

Zie signatuur 3 (met mijlpaal) bij workflow expressies.

Opmerking 1 bij signatuur 3 (met mijlpaal)

Sleutels in dosisMap.

• 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.

Opmerking 2 bij signatuur 3 (met mijlpaal)

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

connDosis.sendDosisStatusUpdate(dosisMap, dosisAgents, dossierId)

Opmerking 3

De onderliggende DOSIS-aanvraag ondersteunt meer velden dan wat via deze workflow-expressies bereikbaar is — bijvoorbeeld ProjectBedrag, IsVertrouwelijk, IsPubliek, IsNietRaadpleegbaar, TypeSubsidieCode en een volledig Adres bij de dossierbeheerder. Deze velden worden door de standaardconnector niet ingevuld en zijn dus niet beschikbaar via de Studio-taaktemplate of workflow-expressie. Heb je deze nodig (bijvoorbeeld voor een subsidiedossier met een ProjectBedrag), dan moet je buiten de standaardconnector om werken en zelf een aanvraag opbouwen richting de onderliggende DosisBusinessConnector — neem in dat geval contact op met het dev-team

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.

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:

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

Error-handling

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.

Naast de twee BpmnErrors hierboven kan de connector ook een ValidationException gooien, vóór de aanroep naar DOSIS zelfs vertrekt. Bijvoorbeeld als agentToegangsrecht leeg is, of als een ander verplicht veld ontbreekt. Deze exceptie wordt niet omgezet naar een BpmnError en leidt dus tot een Camunda-incident in plaats van een opvangbare foutafhandeling in je proces. Zorg er daarom voor dat alle verplichte velden (zie Input-tabel) correct ingevuld zijn vóór je deze service-taak aanroept.

deleteDossier

Functie gebruikt om een in DOSIS gekend dossier te schrappen.

Workflow expressie

${dosis.deleteDossier(dossierNummer)}

Java-code

dosis.deleteDossier(dossierNummer);

Input

Output

Geen output (Void).

Error-handling

In tegenstelling tot sendDosisStatusUpdate vangt deze functie geen enkele fout op en zet die dus ook niet om naar een dosis-client-error/dosis-server-error-BpmnError. Een mislukte verwijdering (bijvoorbeeld omdat het dossiernummer niet bestaat, of een technisch probleem bij DOSIS) resulteert rechtstreeks in een Camunda-incident. Er is geen manier om dit via een error boundary event in je BPMN-proces op te vangen. Voorzie zelf voldoende controle (bijvoorbeeld door vooraf te verifiëren dat het dossier bestaat) als je dit risico wil beperken.