MAGDA Repertorium

Inleiding

Dienst waarmee je bij Magda een melding kan maken van een lopend dossier over een persoon voor een bepaalde periode. De inschrijving van de persoon voor je dossiertype in het register vormt een absolute voorwaarde om identiteitsgegevens te kunnen opvragen.

Use cases

• Een melding maken van een lopend dossier voor een burger bij de opstart van een aanvraag, als voorwaarde om vervolgens identiteitsgegevens te kunnen opvragen via andere MAGDA-connectoren (bv. Persoon, Gezin).

• Zich tijdig registreren bij de KSZ voor een burger waarvoor een periodieke opvolging nodig is (bv. een lopend onderzoek naar een sociaal voordeel of een periodiek te herbevestigen recht).

• Voorafgaand aan een geplande gegevensopvraging (bv. bij de start van een onderzoeksperiode) de betrokken burger inschrijven, zodat de raadpleging achteraf niet wordt geweigerd wegens ontbrekende inschrijving.

Setup

Idem als bij alle MAGDA-connectoren. Zie MAGDA algemene setup.

Specifieke applicatie eigenschappen

Geen.

Services en functies

registreerInschrijving

Maak melding voor een persoon. Dit gebeurt dus bij opstart van het dossier vlak voordat je gegevens ophaalt voor die persoon. De begindatum van de inschrijving wordt automatisch ingesteld op de datum van de aanroep — je kan deze niet zelf meegeven. Er wordt geen einddatum ingesteld, waardoor de inschrijving van onbepaalde duur is (of tot je ze expliciet stopzet).

Workflow expressie

${magda.registreerInschrijving(String identifier, String uri, String hoedanigheid, String dossierId)}

Java-code

RegistreerInschrijvingResponse response = magda.registreerInschrijving(identifier, uri, hoedanigheid, dossierId);

Input

Magda-documentatie

Technische documentatie over RegistreerInschrijving-02.00.

Output

Je krijgt een RegistreerInschrijvingResponse-object terug met een Resultaat-veld (0 of 1, met bijhorende omschrijving "Niet geslaagd" of "Wel geslaagd"). Controleer dit veld altijd — een niet-geslaagde inschrijving levert geen uitzondering op het niveau van het antwoord op, enkel Resultaat=0. Enkel bij een technisch of functioneel probleem (zie Error-handling) krijg je een effectieve uitzondering in plaats van een gewoon antwoord.

Voorbeeld geslaagde inschrijving

<Antwoorden>
    <Antwoord>
        <Referte>550e8400-e29b-41d4-a716-446655440000</Referte>
        <Inhoud>
            <Resultaat Beschrijving="Wel geslaagd">1</Resultaat>
        </Inhoud>
    </Antwoord>
</Antwoorden>

Voorbeeld niet-geslaagde inschrijving

<Antwoorden>
    <Antwoord>
        <Referte>550e8400-e29b-41d4-a716-446655440000</Referte>
        <Inhoud>
            <Resultaat Beschrijving="Niet geslaagd">0</Resultaat>
        </Inhoud>
        <Uitzonderingen>
            <Uitzondering>
                <Identificatie>20002</Identificatie>
                <Oorsprong>MAGDA</Oorsprong>
                <Type>FOUT</Type>
                <Diagnose>INSZ in de vraag heeft een ongeldige structuur</Diagnose>
            </Uitzondering>
        </Uitzonderingen>
    </Antwoord>
</Antwoorden>

Error-handling

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina. Uitzonderingen kunnen hier op twee plaatsen voorkomen: op Repliek-niveau, voor fouten vóór de verwerking van de vraag (bv. XSD-validatiefouten), en op Antwoord-niveau, voor fouten na verwerking (bv. een ongeldig INSZ). Controleer dus beide, niet enkel het Antwoord-niveau zoals bij de meeste andere MAGDA-diensten.

Aan deze functie gerelateerde foutcodes:

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

// Voorbeeld: uitzondering opvangen en gooien als BpmnError
RegistreerInschrijvingResponse response = magda.registreerInschrijving(identifier, uri, hoedanigheid, dossierId);

// Niveau 1: Repliek (vóór verwerking van de vraag)
List<UitzonderingType> repliekUitzonderingen = response.getRepliek().getUitzonderingen().getUitzondering();
for (UitzonderingType uitzondering : repliekUitzonderingen) {
    throw new BpmnError("MAGDA_ONGELDIGE_VRAAG", uitzondering.getDiagnose());
}

// Niveau 2: Antwoord (na verwerking)
List<UitzonderingType> antwoordUitzonderingen = response.getRepliek().getAntwoorden().getAntwoord()
    .getUitzonderingen().getUitzondering();
for (UitzonderingType uitzondering : antwoordUitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("30002".equals(code) || "30003".equals(code) || "30004".equals(code)) {
        throw new BpmnError("MAGDA_INSZ_PROBLEEM", uitzondering.getDiagnose());
    }
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", uitzondering.getDiagnose());
    }
}

// Daarnaast: controleer altijd het Resultaat, ook zonder uitzondering
String resultaat = response.getRepliek().getAntwoorden().getAntwoord().getInhoud().getResultaat().getValue();
if ("0".equals(resultaat)) {
    throw new BpmnError("MAGDA_INSCHRIJVING_NIET_GESLAAGD", "Inschrijving niet geslaagd, geen specifieke uitzondering opgegeven");
}

Kanttekeningen:

• Als de inschrijving niet specifiek bij de KSZ gebeurt, kan MAGDA een geannuleerd INSZ niet detecteren — de inschrijving "slaagt" dan alsnog (Resultaat=1), ook al is het INSZ ongeldig. Enkel bij inschrijving via KSZ krijg je effectief 30002/30003/30004 terug.

• Ter referentie: in een bestaand project wordt dit soms eenvoudiger opgevangen — elke exception generiek afvangen met een enkele BpmnError("registreer-failed"), zonder onderscheid naar foutcode. Dat is een geldig alternatief als je geen nood hebt aan foutcode-specifieke afhandeling, maar minder informatief voor verdere procesafhandeling.