Creëer rol en contactadres conform OpenZaak API
Op het endpoint base-url/api/zgw/zaken/api/v1/rollen/ kan een POST worden geplaatst waarmee OpenWave een contactpersoon onder een rol bij een zaak kan toevoegen.
De base_url is de implementatie van OpenWave waar tegenaan gepraat moet worden, bijvoorbeeld: https://acc.rommeldam.open-wave.nl
Whitelist
De zender die hier een creëer rolbericht POST zal gewhitelist moeten worden. Dit kan in de tabellen tbendpointlist en tbipauthorisationlist onder de tegel Endpoints whitelist op het nieuwe beheerportaal onder de kolom Gebruikers.
In de tabel tbendpointlist zal minimaal het endpoint /api/zgw gedefinieerd moeten zijn met daaronder (in de tabel tbipauthorisationlist) het IP-adres van de zender.
Authorisation Token
In de Authorization header van dit POST bericht moet een valide JWT-token worden meegegeven onder Bearer Token. Zie voorbeeld bij Creëer ZGW zaak conform OpenZaak API
Voor het verkrijgen van een token (met beperkte geldigheidsduur!) zie: ZGW OpenZaak API Functionaliteit
De token wordt opgezocht in de tabel tbaccesstoken en het tijdstip van aanvraag wordt getoetst aan de geldigheidsduur van de gevonden rij.
(robot) medewerker moet gelinkt zijn aan endpoint
De gevonden token is gelinkt aan een (robot)-medewerker (degene onder wiens credentials het token is gecreëerd), Bij de betreffende medewerkers kaart moet de kolom Endpoint (robotmedewerker is gedefinieerd voor binnenkomende berichten op endpoint) (dnkeyendpointlist) in blok login verwijzen naar een kaart in tbendpointlist waarvan de inhoud van de kolom dvendpointurl een substring is van dit endpoint api/zgw/zaken/api/v1/rollen/ / waarop dit creerrolbericht wordt gepost: bijvoorbeeld: /api/zgw
Headers
De enige verplichte header variabele is: Content-Type met als waarde application/json
Body
In application/json.
voorbeeld
{
"zaak": "https://acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/zaken/dc594a1a-61ac-49d2-88cd-535029033fe3",
"betrokkeneType": "natuurlijk_persoon",
"roltype": "https://acc.rommeldam.open-wave.nl/api/zgw/catalogi/api/v1/roltypen/049ce308-5d74-4bfa-a0f9-3e72d3d17a13",
"roltoelichting": "Belanghebbende",
"contactpersoonRol": {
"emailadres": "smulders@rem.nl",
"functie": "",
"telefoonnummer": "",
"naam": "Smulders, Harry"
},
"betrokkeneIdentificatie": {
"inpBsn": "",
"anpIdentificatie": "",
"inpA_nummer": "",
"geslachtsnaam": "Smulders",
"voorvoegselGeslachtsnaam": "",
"voorletters": "M.H.",
"voornamen": "",
"geslachtsaanduiding": "m",
"geboortedatum": "",
"verblijfsadres": {
"aoaIdentificatie": "1234567890",
"wplWoonplaatsNaam": "Assendelft",
"gorOpenbareRuimteNaam": "Bakkerstraat",
"aoaPostcode": "1074XK",
"aoaHuisnummer": "13",
"aoaHuisletter": "s",
"aoaHuisnummertoevoeging": "",
"inpLocatiebeschrijving": ""
}
}
}
Zie Github: zie POST Maak een ROL aan bij een ZAAK op https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/vng-Realisatie/zaken-api/1.5.1/src/openapi.yaml#tag/rollen/operation/rol_create
De verwerking van het bericht door OpenWave wordt gelogd in tbmessagelog indien
- de instelling Sectie: ZGW en Item: Messagelog aangevinkt staat
- EN de instelling Sectie: OWB en Item: MessageLog aangevinkt staat
In principe leidt de inhoud van de body tot de aanmaak van een nieuwe contactpersoon of het koppelen van een bestaande contactpersoon onder een rol (tbomgvergcontactennn) bij een omgevingzaak die eerder is aangemaakt en voorzien is van een gevulde kolom tbomgvergunning.dvzgwuuid. Dit, mits aan de nodige voorwaarden in de OpenWave implementatie is voldaan:
- Er moet tenminste één valide kaart zijn in de OpenWave adrescodes/roltype tabel (tbadressoort) met een gevulde unieke UUID-code in de kolom dvzgwuuid die gelijk is aan de waarde (een UUID-code) vanaf de laatste slash van item roltype.
- De robotmedewerker die verbonden is aan de uitgereikte token moet gekoppeld zijn aan de rechtengroep die het functionele recht tbomgrechten.dlbomgins (insertrecht op de omgevingstabel) aangevinkt heeft staan.
- Er moet een unieke kaart zijn in tbomgvergunning waarvoor geldt dat tbomgvergunning.dvzgwuuid gelijk is aan de waarde (een UUID-code) vanaf de laatste slash van item zaak.
- Indien de instelling Sectie: ZGW en Item: CheckEenRolContactPerZaak bestaat en aangevinkt is dan mag er nog geen kaart aanwezig zijn in tbomgvergcontactennn bij de gevonden omgevingzaak. Hiermee kan het dubbel verwerken van een zelfde bericht voorkomen worden.
- De instelling Getal1 van Sectie: ZGW en Item: KeyAnoniemContactadres moet verwijzen naar de dnkey van een valide contactadreskaart (tbcontactadressen) die gebruikt gaat worden voor een anoniem contactadres bij ontbreken van de nodige informatie.
uuid bij adresrol
In de adresroltabel tbadresssoort (beheerportaal, kolom Administratie, tegel Adressoorten) moet dus door de functioneel beheerder bij één of meer rollen een unieke UUID-code worden gegenereerd (on line zijn er diverse programma's die dat kunnen) en geplaatst worden in de kolom dvzgwuuid. Deze code(s) moeten vervolgens buiten OpenWave om eenmalig gecommuniceerd worden met de zender zodat deze het item roltype in de body kan vullen.
Er wordt dan een nieuwe kaart gemaakt in tbomgvergcontactennn met dnkeyomgverg = de dnkey van de gevonden rij uit tbomgvergunning en dvcodeadressoort = de dvcode uit de gevonden rij in tbadressooort en dnkeycontactadressen = de dnkey van een rij in tbcontactadressen (zie hieronder voor de bepaling hiervan daarvan).
Er wordt een unieke UUID-code uitgetrokken voor de aangemaakte rij en deze code komt in kolom tbomgvergcontactennn.dvzgwuuid.
Bepaling contactadreskaart
In de Open Zaak API hoeven de items “contactpersoonRol” en “betrokkeneIdentificatie” niet in de body zijn opgenomen en de onderliggende items daarvan hoeven ook niet opgenomen te zijn en de waardes daarvan mogen leeg zijn.
OpenWave redeneert daarom als volgt voor de bepaling van het contactadres:
Indien
- item betrokkeneIdentificatie niet bestaat
- EN binnen item contactpersoonRol is:
- item naam leeg of bestaat niet
- EN/OF item emailadres leeg of bestaat niet
dan zoekt OpenWave naar de dnkey van de contactadreskaart (tbcontactadressen) gedefinieerd door Getal1 van de instelling Sectie: ZGW en Item: KeyAnoniemContactadres
Anders, indien
- item betrokkeneIdentificatie niet bestaat
- EN binnen item contactpersoonRol is item naam gevuld en item emailadres gevuld
dan zoekt OpenWave naar een geldige kaart in tbcontacadressen met dvemail = contactpersoonRol emailadres (indien gevuld) EN dvachternaam = contactpersoonRol naam. Indien niet gevonden dan wordt een nieuwe kaart aangemaakt in tbcontactadressen op basis van naam en email en dvtelefoonnummer
Anders, - item betrokkeneIdentificatie bestaat - dan zoekt OpenWave naar een geldige kaart in tbcontactadressen met respectievelijk dvsofinummer = betrokkeneIdentificatie inpBsn.
Anders (nog geen kandidaat gevonden ) dan zoekt OpenWave naar een geldige kaart in tbcontacadressen met respectievelijk dvsofinummer = betrokkeneIdentificatie inpBsn (indien gevuld) of naar dvnpnanp = betrokkeneIdentificatie anpIdentificatie (indien gevuld).
Anders (en nog niet gevonden dus) dan zoekt OpenWave naar een geldige kaart in tbcontacadressen met dvemail = contactpersoonRol emailadres (indien gevuld) EN dvachternaam = betrokkeneIdentificatie geslachtsnaam (indien gevuld).
Voor deze zoekopdrachten geldt dat als er meerdere kandidaten zijn dan dan de eerste de beste de gevonden kaart is.
Indien GEEN contactadreskaart is gevonden dan wordt een nieuwe contactadreskaart aangemaakt met de voorhanden gegevens.
OpenWave maakt nu een kaart aan in tbomgvergcontactennn bij de zaak met een verwijzing naar de dnkey van de (gevonden of aangemaakte) contactadreskaart en de rol. Voor de combinatie wordt ook een UUID-code uitgetrokken en bij deze regel in de kolom tbomgvergcontactennn.dvzgwuuid geplaatst.
Responsebericht
Indien de rol niet kon worden aangemaakt wordt een responsecode anders dan 200/201 geretourneerd met in de body de oorzaak van het falen.
Indien de rol succesvol is aangemaakt wordt onder de responsecode 201 het oorspronkelijke bericht geretourneerd aangevuld met de verplichte items, waarbij
- in het item uuid de code wordt geretourneerd die opgeslagen is in de nieuwe rol (= combinatie zaak, roltype en contactadres) (tbomgvercontactennn.dvzgwuuid).
Voorbeeld response body
{
"roltoelichting": "Belanghebbende",
"roltype": "MilieuKlachten",
"statussen": [],
"betrokkeneIdentificatie": {
"voornamen": "",
"geslachtsaanduiding": "m",
"anpIdentificatie": "",
"voorletters": "M.H.",
"geslachtsnaam": "Smulders",
"inpBsn": "",
"inpA_nummer": "",
"voorvoegselGeslachtsnaam": "",
"geboortedatum": "",
"verblijfsadres": {
"aoaIdentificatie": "1234567890",
"inpLocatiebeschrijving": "",
"gorOpenbareRuimteNaam": "Bakkerstraat",
"wplWoonplaatsNaam": "Assendelft",
"aoaHuisnummertoevoeging": "",
"aoaHuisletter": "s",
"aoaHuisnummer": "13",
"aoaPostcode": "1074XK"
}
},
"zaak": "https://acc.rommeldam.open-wave.nl/api/openzaak/zaken/api/v1/zaken/fda36d38dd99476eb5b49d88f1495f76",
"betrokkeneType": "natuurlijk_persoon",
"contactpersoonRol": {
"functie": "",
"telefoonnummer": "",
"naam": "Smulders, Harry",
"emailadres": "smulders@rem.nl"
},
"registratiedatum": "2024-08-12T12:37:50",
"uuid": "cac10cf1d4704af8b6212200098e7841",
"omschrijvingGeneriek": "initiator",
"url": "https://acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/rollen/cac10cf1d4704af8b6212200098e7841"
}