DIGITAAL VLAANDEREN
Overzicht generieke uitzonderingen MAGDA SOAP webservices
Deze pagina beschrijft de werking van de foutafhandeling voor MAGDA 2.0 webservices. Elke MAGDA 2.0 webservice werkt op het vlak van foutafhandeling op eenzelfde manier.
Hou bij de ontwikkeling van de toepassing rekening dat foutcodes kunnen toegevoegd worden. Onderstaande codes zijn dus “generiek” en kunnen bij de meeste MAGDA SOAP diensten voorkomen. In de handleiding van de specifieke diensten staan de uitzonderingen die meer specifiek met de dienst te maken hebben.
Deze pagina bavat niet alle mogelijke uitzonderingen van alle diensten, enkel de generieke uitzonderingen die in de meeste diensten voorkomen.
Opmerking:
Bij nieuwe MAGDA SOAP diensten waarbij de XSD van de bron wordt overgenomen voor de payload en de foutmeldingen is een nieuwe foutcode reeks van toepassing. Zie ook Overzicht uitzonderingen bij overname XSD van de bron.
Let op: het versienummer van de dienst zegt niets over het overnemen van de bron-XSD. Dit wordt vermeld in de handleiding van de dienst en kan voorkomen bij 2.x, 3.x of V1 diensten.
Uitzondering opbouw
Visueel
Identificatie
De identificatie is de MAGDA foutcode, numeriek, 5 lang. MAGDA streeft er naar foutcodes maximaal te hergebruiken over de diensten heen.
Oorsprong
De Oorsprong geeft aan wie de fout aangemaakt heeft. De oorsprong is (max) vijf karakters lang en uniek voor een bron. Op deze manier is het voor afnemers eenvoudig te bepalen bij welke partij de fout is opgetreden.
Daar foutcodes maximaal hergebruikt worden is de mogelijkheid dat een foutcode met een oorsprong MAGDA maar ook met een oorsprong bron kan voorkomen binnen een dienst.
Oorsprong | Richtlijn |
|---|---|
MAGDA | Elke uitzondering die door MAGDA zelf aangemaakt is:
|
Bron | Elke uitzondering (ruime zin), door de bron aangemaakt:
|
Type
Het type uitzondering duidt de zwaarte van uitzondering aan. Echter wordt aanbevolen enkel op de foutcode te werken.
Type | Definitie |
|---|---|
FOUT | De afnemer zal geen data object (Vb Persoon) ontvangen van de businessdienst doordat er een fout opgetreden is. Dit moet niet zozeer een technische fout zijn, maar kan ook een validatiefout zijn, autorisatiefout, … .. Vb: INSZ checksum is ongeldig, foutcode van de bron waarbij er geen data object terug komt, … |
INFORMATIE | De afnemer ontvangt een data object maar binnen de uitzondering is er extra informatie opgenomen met betrekking tot het data object of de verwerking. |
WAARSCHUWING | De afnemer ontvangt een data object, of zou er een kunnen ontvangen, maar moet actie ondernemen. Vb: Persoon heeft een nieuw INSZ verkregen |
Tijdstip
Datum en tijdstip van aanmaken uitzondering.
Diagnose
De diagnose is de tekstuele omschrijving van de opgetreden fout.
Omstandigheid
De omstandigheid wordt enkel gebruikt voor de foutcode van de bron door te geven. Enkel de foutcode, geen omschrijving of andere bijkomende gegevens.
Annotaties
Binnen een Uitzonderingen kunnen Annotatie-elementen voorkomen. Deze Annotatie-elementen, onder de vorm van een naam/waarde-paar, geven meer informatie rond de uitzonderingen.
De meest voorkomende annotatie is Oud INSZ en Nieuw INSZ.
Informatie:
Of een annotatie al dan niet voorkomt binnen een dienst wordt in de handleidingen van de diensten zelf beschreven. Het overzicht van alle diensten is te vinden op Handleidingen MAGDA-diensten per domein.
ElementReferenties
Dit element heeft enkel een interne functie en laat MAGDA toe om de uitzonderingen te filteren volgens de machtiging van de afnemer. Dit element zal nooit ingevuld zijn in het antwoord dat de afnemer ontvangt.
Generieke foutcodes
Generieke foutcodes, welke hieronder zijn opgelijst, kunnen in meerdere diensten voorkomen. Generiek betekent hier “veel voorkomend”. MAGDA probeert zoveel mogelijk foutcodes te hergebruiken zolang ze semantisch gelijk zijn. Dit zorgt ervoor dat er geen wildgroei is aan uitzondering-codes maar ook dat dezelfde codes bij verschillende diensten kunnen voorkomen. Daarnaast is het mogelijk dat een bepaalde “generieke” situatie veroorzaakt wordt door een situatie bij MAGDA, maar ook door een situatie bij de bron. Een generieke foutcode kan dus voorkomen met oorsprong MAGDA maar ook met de bron als oorsprong.
Informatie:
Codes die aan een specifieke dienst verbonden zijn wordt gedocumenteerd in de handleiding van de dienst zelf en zijn steeds op niveau 3.
Niveau uitzonderingen
Bij een MAGDA 2.0 webservice kunnen Uitzonderingen voorkomen op drie verschillende niveaus.
Niveau 1: SOAPFault
Een SOAPFault doet zich maar in beperkte omstandigheden voor:
een ongeldig bericht (XML niet geldig) ontvangen van de afnemer
MAGDA heeft een ongeldig bericht opgesteld voor de afnemer
een onverwacht technisch probleem heeft zich voorgedaan (een issue dat niet opgevangen werd door de JAVA code)
In onderstaande tabel zijn de mogelijke SOAPFault foutcodes opgekomen die zich binnen een MAGDA 2.0 webservice kunnen voordoen op dit niveau.
Faultcode | Verduidelijking |
|---|---|
10001 | Fout formaat in de vraag (XSD-validatie). Fout: [fout] |
10501 | Fout formaat in de vraag (XSD-validatie) |
10502 | Ongeldig aantal vragen |
12000 | Authenticatie gefaald: de opgegeven gebruikersnaam/paswoord is niet correct |
Niveau 2: Uitzondering op het niveau van Repliek
Uitzonderingen op niveau 2 doen zich voor op het niveau van Repliek en niet op het niveau van het Antwoord. Bij deze uitzonderingen zal nooit een Antwoorden-element terugkomen. Deze uitzonderingen hebben steeds als Oorsprong "MAGDA".
Deze uitzonderingen doen zich voor bij de validatie van de Context en hebben veelal te maken met autorisatieproblemen. Ook technische fouten kunnen op dit niveau teruggegeven worden.
De controle van de gegevens in de Vraag behoort niet tot Niveau 2 maar wel tot Niveau 3.
In onderstaande tabel zijn de mogelijke foutcodes opgekomen die binnen een MAGDA webservice kunnen voordoen op dit niveau.
Foutcode | Verduidelijking |
|---|---|
12006 | Persoonsnummer van de gebruiker beantwoordt niet aan de vormvereisten |
12014 | CommonName van certificaat niet opgegeven |
12015 | Afnemer niet geconfigureerd voor toegang met certifcaten |
12016 | CommonName van certificaat is niet geldig voor afnemer |
12501 | De validatie op de achterliggende businessdienst op de dienstnaam en dienstversie in de context is gefaald |
12503 | De validatie op de achterliggende businessdienst op het berichttype in de context is gefaald |
13001 | Geen machtiging van de afzender in deze hoedanigheid voor de gevraagde dienst. |
13101 | Combinatie van vraagelementen niet toegelaten of bepaald element niet aanwezig |
13201 | Gegevens niet opvraagbaar, geen ondernemingsdossier geregistreerd |
13202 | Gegevens niet opvraagbaar, geen persoonsdossier geregistreerd |
13501 | Geen autorisatie tot de achterliggende businessdienst door een validatieprobleem op de URI en hoedanigheid in de context |
99993 | Een MAGDA interne XSD validatie van het bericht gaf een fout vooraleer deze naar de achterliggende businessdienst gestuurd wordt |
99994 | Onverwachte fout bij de bron |
99997 | Een MAGDA interne XSD validatie van het bericht dat ontvangen wordt vanuit de achterliggende businessdienst gaf een fout |
99998 | Fout bij validatie van het bericht naar de afnemer |
99999 | Er heeft zich een technische fout voorgedaan |
Niveau 3: Uitzondering binnen het Antwoorden-element
Eens de Contextvalidatie - zijnde de autorisatie - ok is, zullen de functionele fouten op dit niveau getoond worden.
Er is steeds een Antwoorden-element
Een uitzondering op niveau 3 kan samen gaan met een Inhoud-element met gegevens
Meerdere uitzonderingen op niveau 3 kunnen terugkomen
Een uitzondering op niveau 3 kan nooit voorkomen tezamen met een uitzondering op niveau 2
In onderstaande tabel zijn de mogelijke foutcodes opgekomen die binnen een MAGDA webservice kunnen voordoen op dit niveau.
Foutcode | Verduidelijking |
|---|---|
13102 | Een vraagelement bevat een niet toegelaten waarde |
13252 | Registratie persoon dekt niet de gevraagde periode |
13302 | Gegevens niet opvraagbaar, geen persoonsdossier aanwezig voor bron De bron inschrijvingscontrole is in feite een controle in het personen inschrijvingsrepertorium (Pir) waarbij gecontroleerd wordt of de bron wel gegevens heeft van de persoon waarvoor de gebruiker een vraag gesteld heeft. Heeft de bron een inschrijving in het Pir, dan zal de vraag doorgestuurd worden naar die bron om de gegevens op te halen of verdere verwerking uit te voeren. Indien de BIC een negatief antwoord teruggeeft, stopt de verwerking en krijgt de gebruiker een gepaste foutcode. |
14001 | Geen vraagreferte opgegeven |
15021 | Geen gegevens in antwoord wegens filtering |
16010 | Mismatch tussen verwacht formaat en gekregen formaat van het antwoord vanuit de bron. |
25001 | De opgegeven taal wordt niet ondersteund door deze dienst |
30001 | Geen gegevens gevonden voor de vraag |
60003 | Fout formaat in de vraag naar de bron toe |
60004 | Onbekende fout bij de bron |
60006 | Geen antwoord van de bron ontvangen |
60007 | Kan antwoord van de bron niet interpreteren |
60008 | Fout bij validatie antwoord (XSD validatie) |
60009 | Er heeft zich een technisch probleem voorgedaan |
60010 | Dienst is tijdelijk niet beschikbaar |
60011 | Toegangsparameters voor bron niet opgezet in autorisatiedatabase |
60012 | Probleem met verbinding bron |
60013 | Fout in toegang naar de bron |
60014 | Niet bestaande versie van de dienst. |
60015 | Niet bestaande dienst |
60016 | Het aantal parallelle berichten ligt boven de toegestane waarde |
60017 | Er is een probleem met de logging van het bericht |
60018 | Routeringsconfiguratie niet (volledig) opgezet |
60019 | Dienst gepauzeerd. Probeer later opnieuw. Contacteer de MAGDA helpdesk. Deze uitzondering komt voor als de MAGDA Circuit Breaker de connectie naar de bron tijdelijk uitgeschakeld heeft omwille van een te groot aantal fouten. |
Runtime uitzonderingen worden verder in deze handleiding besproken | |
99981 | Runtime uitzondering: Ongekende landgegevens ontvangen |
99982 | Runtime uitzondering: Ongekende code opgegeven in de vraag |
99983 | Runtime uitzondering: Magda code niet aanwezig voor teruggekomen broncode |
99984 | Runtime uitzondering: MAGDA kan geen omschrijving vinden voor de broncode |
99985 | Runtime uitzondering: Annotatie niet gevonden |
99986 | Runtime uitzondering: Ongekende foutcode ontvangen van de bron |
Runtime uitzonderingen
De MAGDA diensten maken gebruik van een interne databank om de mappingen (d.w.z. omzettingen) van bron foutcodes en functionele fouten binnen de dienst om te zetten naar Magda-code en omschrijving. Om een optimale werking te garanderen kent deze component zijn eigen foutcodes die in principe binnen elke MAGDA dienst mogelijk zijn, zowel webservice als publicatie.
Op deze pagina
- 1 Uitzondering opbouw
- 1.1 Visueel
- 1.2 Identificatie
- 1.3 Oorsprong
- 1.4 Type
- 1.5 Tijdstip
- 1.6 Diagnose
- 1.7 Omstandigheid
- 1.8 Annotaties
- 1.9 ElementReferenties
- 2 Generieke foutcodes
- 3 Niveau uitzonderingen
- 4 Runtime uitzonderingen
Verbonden pagina’s
https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/1220968511
Voor vragen of opmerkingen kan u de MAGDA helpdesk contacteren
De MAGDA Gebruikersomgeving is een officiële website van de Vlaamse overheid
uitgegeven door Digitaal Vlaanderen