| Beide kanten vorige revisie Vorige revisie | |
| stable:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeer_zgw_zaak [2026/07/15 10:16] – ↷ Pagina verplaatst van stable:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeer_zgw_zaak naar dev:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeer_zgw_zaak Kars Gottschal | stable:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeer_zgw_zaak [2026/07/15 11:07] (huidige) – aangemaakt - Externe bewerking 127.0.0.1 |
|---|
| | ====== Creëer ZGW zaak conform OpenZaak API ====== |
| | |
| | {{tag>openwave:1.34:applicatiebeheer:functionaliteiten:zgw}} |
| | |
| | Op het endpoint //base-url//%%/api/zgw/zaken/api/v1/zaken/%% kan een POST worden geplaatst waarmee OpenWave een nieuwe zaak kan aanmaken. |
| | |
| | De //base_url// is de implementatie van OpenWave waar tegenaan gepraat moet worden, bijvoorbeeld: //%%https://acc.rommeldam.open-wave.nl%%//. |
| | |
| | Gebaseerd op versie Open Zaak API 1.2 |
| | |
| | <adm warning Whitelist> |
| | |
| | De zender die hier een creëer zaakbericht POST zal gewhitelist moeten worden. Dit kan in de tabellen tbendpointlist en tbipauthorisationlist onder de tegel [[stable:applicatiebeheer:probleemoplossing:portalen_en_moduleschermen:beheerportaal_nieuw:tegels_kolom_gebruikers: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. |
| | |
| | </adm> |
| | |
| | ===== Authorisation Token ===== |
| | |
| | In de Authorization header van dit POST bericht moet een valide JWT-token worden meegegeven onder Bearer Token. {{openwave:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:zgw-tokeninauthirizationheader.png?600|zgw-tokeninauthirizationheader}} Voor het verkrijgen van een token (met beperkte geldigheidsduur!) zie: [[stable:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit]].\\ |
| | |
| | De token wordt opgezocht in de tabel tbaccesstoken en het tijdstip van aanvraag wordt getoetst aan de geldigheidsduur van de gevonden rij. |
| | |
| | <adm warning (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/zaken/// waarop dit creerzaakbericht wordt gepost: bijvoorbeeld: ///api/zgw// |
| | |
| | </adm> |
| | |
| | ===== Headers ===== |
| | |
| | De volgende headers parameters zijn verplicht:\\ {{openwave:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:zgw_headervariabelen.png?600|zgw_headervariabelen}}\\ |
| | |
| | EPSG: 4326 verwijst naar een Bosatlas-coördinatenstelsel. De paren coördinaten moeten aangeleverd worden met eerst de Y en dan de X, dus eerst breedtegraad (y: latitude) en dan de lengtegraad (x: longitude), zoals in onderstaand voorbeeld. Aangezien er bij epsg 4326 ruis bestaat over deze volgorde, mogen de coordinaatparen ook aangeleverd worden met eerst de x en dan de y. In dat geval moet de instelling //Sectie: ZGW en Item: epsg4326xy// bestaan en aangevinkt zijn, want anders wordt de berekening door OpenWave naar Rijksdriehoek verkeerd uitgevoerd. |
| | |
| | ===== Body ===== |
| | |
| | In application/json. |
| | |
| | <adm example> |
| | |
| | <code json> |
| | { |
| | "bronorganisatie": "001509962", |
| | "omschrijving": "Omgevallen lantaarnpaal", |
| | "toelichting": "Ja, op de hoek eeghenlaan en cruquiusweg is een lantaarnpaal omgevallen", |
| | "zaaktype": "https://acc.rommeldam.open-wave.nl/api/zgw/catalogi/api/v1/zaaktypen/365f113f-cb3c-4843-91ce-e7c9467f19c5", |
| | "verantwoordelijkeOrganisatie": "001509962", |
| | "startdatum": "2024-07-26", |
| | "zaakgeometrie": { |
| | "coordinates": [ |
| | 52.3685617, |
| | 4.9384269 |
| | ], |
| | "type": "Point" |
| | } |
| | } |
| | </code> |
| | |
| | </adm> |
| | |
| | Zie Github: POST //Maak een ZAAK aan// op [[https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/vng-Realisatie/zaken-api/1.5.1/src/openapi.yaml#tag/zaken/operation/zaak_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 zaak in tbomgvergunning of tbovvergunningen mits aan de nodige voorwaarden in de OpenWave implementatie is voldaan: |
| | |
| | * Er moet tenminste één valide kaart zijn in de OpenWave zaaktype tabel tbsoortomgverg of tbsoortovverg 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 //**zaaktype**//. |
| | * 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) en/of tbovrechten.dlbovvins (insertrecht op de APV/Overige tabel) aangevinkt heeft staan. |
| | * Er moet een rij zijn in tbperceeladressen met dnkey = de waarde van //Getal1// van de instelling //Sectie: Koppeling ZAAK en Item: DummyLokatiePerceelkey// |
| | * Indien de instelling //Sectie: ZGW// en //Item: GeometrieVerplicht// is aangevinkt, dan moet er geometrie zijn opgenomen in het bericht, anders wordt een foutmelding gegenereerd als response. |
| | |
| | <adm warning UUID bij zaaktype(s)> |
| | |
| | In de zaaktypetabel tbsoortomgverg en/of in de tabel tbsoortomgverg moeten dus door de functioneel beheerder bij één of meer zaaktypes een unieke UUID-code worden gegenereerd (online zijn er diverse programma's die dat kunnen) en geplaatst in de kolom //dvzgwuuid//. Deze code(s) moeten vervolgens buiten OpenWave om eenmalig gecommuniceerd worden met de zender zodat deze het item zaaktype in de body kan vullen. Deze uuid-waardes kunnen ook opgehaald worden met [[stable:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:opvragenlijstmetzgwzaaktypen]] |
| | |
| | </adm> |
| | |
| | De waarde van item //zaaktype// vanaf de laatste slash wordt opgezocht in tbsoortomgverg en anders in tbsoortovverg. Er wordt dan een nieuwe kaart gemaakt in tbomgvergunning met dnkeysoortomgverg = de dnkey van de gevonden rij uit tbsoortomgverg OF een nieuwe kaart in tbovvergunningen met dvcodesoortoverg = de dvcode van de gevonden rij uit tbsoortovverg. De zaak krijgt de waarde van de //DummyLokatiePerceelkey// als dnkeyperceeladres (hier kan nog vanaf geweken worden bij de niet verplichte waarnemingslocatie-items: zie verderop bij extra items). |
| | |
| | Er wordt een unieke UUID-code uitgetrokken voor de aangemaakte zaak en deze code komt in kolom //dvzgwuuid// (zichtbaar op detailpagina van de omgeving- APV/Overige zaak in blok keten mits de kolom is gevuld). |
| | |
| | Met het creeerzaakobject-bericht kan een locatie van de zaak worden doorgegeven: zie [[stable:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeerzgwzaakobject]]. |
| | |
| | De **items van de body** (tot en met //zaakgeometrie//) worden als volgt ondersteund in de nieuw aangemaakte zaak: |
| | |
| | * **bronorganisatie**. Hier doet OpenWave niets mee |
| | * **omschrijving** komt in de kolom //tbomgvergunning.dvaanvraagnaam// dan wel //tbovvergunningenen.dvomschrijving// |
| | * **toelichting** in de kolom //tbomgvergunning.dvaanvraagoms// dan wel //tbovvergunningenen.dvinhoud// |
| | * **verantwoordelijkeOrganisatie**. Hier doet OpenWave niets mee |
| | * **startdatum** in de kolom //tbomgvergunning.ddaanvraag// dan wel //tbovvergunningenen.ddontvangsdatum// |
| | * **zaakgeometrie**. Voor de lijn, punt of vlak wordt een kaart aangemaakt in tbzaakkadperc (en gekoppeld aan de net aangemaakte omgeving, dan wel APV/Overige zaak) met dlhoofdprojectlocatie = 'T' en waarbij de coördinaten worden overgenomen en ook nog eens worden omgezet naar Rijksdriehoek (EPSG 28991). |
| | |
| | Op grond van het zaaktype en aanverwante instellingen wordt een rij aangemaakt in tbinbehandelingbij, worden zo nodig mappen aangemaakt, worden processen toegevoegd, wordt de zaak zo nodig aangebracht in het DMS conform de verwerking van een StUF-bericht of DSO-verzoek dat heeft geleid tot een nieuw zaak. |
| | |
| | <adm warning StUF Zaak/dms> |
| | |
| | Automatisch een zaak aanmaken in het externe zaak/DMS systeem via de stuf zaak/DMS koppeling kan alleen indien de initiator van de zaak bekend is. Maar deze contactpersoon wordt niet direct met het creeeer zaakbericht verstuurd. Probleem. Het creeer rol/contactpersoon bericht wordt veel later of misschien niet verstuurd. De zaak moet echter wel worden aangemaakt in het DMS om aldaar documenten te kunnen stallen. Daarom het volgende: Indien //Getal1// van de instelling //Sectie: ZGW en Item: keyvoorlopigeaanvrager// verwijst naar een valide rij in tbcontactadressen dan wordt dit contactadres gebruikt als initiator. Bij het ontbreken van deze verwijzing zal er geen zaak in het DMS worden aangemaakt en kunnen dus ook geen documenten gestald worden. Deze voorlopige aanvrager wordt alleen gebruikt om de zaak in het DMS te kunnen aanmaken. Er wordt geen kaart in OpenWave aangemaakt in tbomgvergcontactennn of tbovcontactennn. Zie ook kopje ZAAK/DMS bij [[vereiste_minimale_instellingen]] |
| | |
| | </adm> |
| | |
| | ==== Uitzondering extra waarnemings-items ==== |
| | |
| | Vanaf item //registratieNummer// kunnen er items in het creeerZaakbericht zijn opgenomen, die niet in de OpenZaakApi thuishoren, maar die OpenWave toch ondersteunt indien het zaaktype een omgevingzaaktype (tbsoortomgverg) met dvsoortproc = "K" (klacht) betreft. |
| | |
| | <adm example> |
| | |
| | <code json> |
| | { |
| | "bronorganisatie": "001509962", |
| | "omschrijving": "Omgevallen lantaarnpaal", |
| | "toelichting": "Ja, op de hoek eeghenlaan en cruquiusweg is een lantaarnpaal omgevallen", |
| | "zaaktype": "https://acc.rommeldam.open-wave.nl/api/zgw/catalogi/api/v1/zaaktypen/365f113f-cb3c-4843-91ce-e7c9467f19c5", |
| | "verantwoordelijkeOrganisatie": "001509962", |
| | "startdatum": "2024-07-26", |
| | "zaakgeometrie": { |
| | "coordinates": [ |
| | 52.3685617, |
| | 4.9384269 |
| | ], |
| | "type": "Point" |
| | }, |
| | "registratieNummer": "567890", |
| | "hoofdCategorie": "ik zie", |
| | "subCategorie": "rommel op straat", |
| | "datumOverlast": "2024-07-25", |
| | "tijdstipOverlast": "13:12:00", |
| | "vermoedelijkeVeroorzaker": "windvlaag", |
| | "straatnaamWaarneming": "Cruquiusweg", |
| | "huisnummerWaarneming": "60", |
| | "huisletterWaarneming": null, |
| | "huisnummertoevoegingWaarneming": null, |
| | "postcodeWaarneming": "1069AH", |
| | "plaatsWaarneming": "Rommeldam", |
| | "gemeenteWaarneming": "Rommeldam", |
| | "datumEindeOverlast": "2024-07-25", |
| | "tijdstipEindeOverlast": "17:34:00" |
| | } |
| | </code> |
| | |
| | </adm> |
| | |
| | OpenWave gaat met deze extra items als volt om: |
| | |
| | * Indien het item **registratieNummer** bestaat en is gevuld wordt gekeken of de instelling //Sectie: ZGW en Item: CheckOpRegistratienummer// aangevinkt is. Zo ja dan wordt dat registratieNummer opgezocht in de kolom //tbomgvergunning.dvcodeexternebron// in blok //verloop klacht// op het detailscherm van de omgevingzaak. Indien gevonden, dan concludeert OpenWave dat de zaak reeds bestaat en wordt er GEEN nieuwe zaak aangemaakt. Indien er wel een nieuwe zaak wordt aangemaakt wordt deze kolom dvcodeexternebron dus gevuld met het registratieNummer. |
| | * Indien **hoofdCategorie** bestaat en is gevuld dan wordt |
| | * Indien de kolom //Tekst// van de instelling //Sectie: ZGW en Item: mappingHoofdcat// is gevuld met //tbklachtbinkomstcat// dan wordt deze waarde opgezocht in de kolom dvomschrijving van tbklachtbinkomstcat (Zaakbeheerportaal kolom: Klachten, tegel: //Klacht Binnenkomstcategorie//). Indien NIET gevonden dan wordt een nieuwe rij aangemaakt in tbklachtbinkomstcat. De dnkey van de gevonden of nieuw aangemaakte rij wordt vervolgens overgenomen in de kolom dnkeyklachtbinkomstcat van de omgevingzaak (blok //classificatie klacht// op detailscherm). |
| | * Anders, dus de kolom //Tekst// van de instelling //Sectie: ZGW en Item: mappingHoofdcat// is NIET gevuld met //tbklachtbinkomstcat// dan wordt deze waarde opgezocht in de kolom dvvorm van tbklachtvorm (Zaakbeheerportaal kolom: Klachten, tegel: //KlachtVorm//). Indien NIET gevonden dan wordt een nieuwe rij aangemaakt in tbklachtvorm. De dnkey van de gevonden of nieuw aangemaakte rij wordt vervolgens overgenomen in de kolom dnkeyklachtvorm van de omgevingzaak (blok //classificatie klacht// op detailscherm). |
| | * Indien **subCategorie** bestaat en is gevuld dan |
| | * Indien de kolom //Tekst// van de instelling //Sectie: ZGW en Item: mappingSubcat// is gevuld met //tbklachtbinkomsttype// wordt deze waarde opgezocht in de kolom dvomschrijving van tbklachtbinkomsttype (Zaakbeheerportaal kolom: klachten, tegel: //Klacht Binnenkomsttype//). Indien NIET gevonden dan wordt een nieuwe rij aangemaakt in tbklachtbinkomsttype. De dnkey van de gevonden of nieuw aangemaakte rij wordt vervolgens overgenomen in de kolom dnkeyklachtbinkomsttype van de omgevingzaak (blok //classificatie klacht// op detailscherm). |
| | * Anders, dus de kolom //Tekst// van de instelling //Sectie: ZGW en Item: mappingSubcat// is NIET gevuld met //tbklachtbinkomsttype// dan wordt deze waarde opgezocht in de kolom dvomschrijving van tbklachtbinkomstcat (Zaakbeheerportaal kolom: Klachten, tegel: //Klacht Binnenkomstcategorie//). Indien NIET gevonden dan wordt een nieuwe rij aangemaakt in tbklachtbinkomstcat. De dnkey van de gevonden of nieuw aangemaakte rij wordt vervolgens overgenomen in de kolom dnkeyklachtbinkomstcat van de omgevingzaak (blok //classificatie klacht// op detailscherm). |
| | * Indien **datumOverlast** bestaat en is gevuld wordt deze waarde overgenomen in tbomgvergunning.ddatumbeginoverlast (blok //verloop klacht// op het detailscherm). |
| | * Indien **tijdstipOverlast** bestaat en is gevuld wordt deze waarde overgenomen in tbomgvergunning.dvtijdbeginoverlast (blok //verloop klacht// op het detailscherm). |
| | * Indien **datumEindeOverlast** bestaat en is gevuld wordt deze waarde overgenomen in tbomgvergunning.ddatumeindoverlast (blok //verloop klacht// op het detailscherm). |
| | * Indien **tijdstipEindeOverlast** bestaat en is gevuld wordt deze waarde overgenomen in tbomgvergunning.dvtijdeindoverlast (blok //verloop klacht// op het detailscherm). |
| | * Indien **vermoedelijkeVeroorzaker** bestaat en is gevuld wordt deze waarde overgenomen in tbomgvergunning.dvvermveroorznaam (blok //Klacht Vermoedelijke veroorzaker// op het detailscherm). |
| | * Voor de **lokatieitems**: straatnaamWaarneming, huisnummerWaarneming, huisletterWaarneming,huisnummertoevoegingWaarneming,postcodeWaarneming, plaatsWaarneming en gemeenteWaarneming geldt het volgende: |
| | * de combinatie gemeente, woonplaats, straat, huisnummer, huisletter en huisnummertoevoeging wordt gezocht in vwfrmlokaties. Indien uniek resultaat is gevonden, dan wordt dnkeyperceeladressen van de aangemaakte omgevingskaart overschreven met de gevonden vwfrmlokaties.dnkeypereeladressen. Hierbij wordt wat betreft de gemeentewaarneming de waarde 'Gemeente Nijmegen' geinterpreteerd als 'Nijmegen' (en zo ook voor andere gemeentes) . |
| | * tbomgvergunning.dvwaarneminglok (blok //Klacht Locatie omschrijving // op het detailscherm) wordt gevuld met een samenvoeging van de lokatiegegevens. |
| | * De aangemaakte kaart in tbzaakkadperc (op grond van de zaakgeometrie) wordt aangevuld met deze lokatiegegevens. |
| | |
| | ===== Responsebericht ===== |
| | |
| | Indien de zaak niet kon worden aangemaakt wordt een responsecode anders dan 200/201 geretourneerd met in de body de oorzaak van het falen. Indien de zaak 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 zaak (tbomgvergunning.dvzgwuuid of tbovvergunningen.dvzgwuuid) en die door de zender gebruikt moet worden voor het aanbrengen van een rol/contactpersoon ([[stable:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeer_zgw_rol]]) bij de zaak en het koppelen van een document bij de zaak ([[stable:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:koppel_zgw_documentaanzaak]]) en het toevoegen van een zaakobject bij de zaak ([[stable:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeerzgwzaakobject]]) |
| | * in het item //url// wordt een URL gegenereerd op basis van kolom //Tekst// van de instelling //Sectie: Operations en Item: servernaam_hyperlink// gevolgd door ///api/zgw/zaken/api/v1/zaken/// gevolgd door de UUID uit tbomgvergunning.dvzgwuuid of tbovvergunningen.dvzgwuuid. De waarde van //servernaam_hyperlink// in onderstaand voorbeeld is //%%https://acc.rommeldam.open-wave.nl%%//: als het goed is is dat de //base-url// van het aangesproken endpoint. |
| | * in het item //identificatie// komt de wavezaakcode te staan die bij de omgevings- of APV/Overige zaak is aangemaakt. |
| | |
| | <adm example Voorbeeld response body> |
| | |
| | <code json> |
| | { |
| | "zaakgeometrie": { |
| | "coordinates": [ |
| | 4.9384269, |
| | 52.3685617 |
| | ], |
| | "type": "Point" |
| | }, |
| | "bronorganisatie": "001509962", |
| | "betalingsindicatieWeergave": "n.v.t", |
| | "uuid": "30cb03a43daf4698b698d7c80eb1c49e", |
| | "verantwoordelijkeOrganisatie": "001509962", |
| | "omschrijving": "Omgevallen lantaarnpaal", |
| | "zaakobjecten": [], |
| | "toelichting": "Ja, op de hoek eeghenlaan en cruquiusweg is een lantaarnplaal omgevallen", |
| | "identificatie": "2024K0005", |
| | "zaaktype": "https://acc.rommeldam.open-wave.nl/api/zgw/catalogi/api/v1/zaaktypen/365f113f-cb3c-4843-91ce-e7c9467f19c5", |
| | "url": "https://acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/zaken/30cb03a43daf4698b698d7c80eb1c49e", |
| | "rollen": [], |
| | "deelzaken": [], |
| | "eigenschappen": [], |
| | "zaakinformatieobjecten": [], |
| | "status": null |
| | } |
| | </code> |
| | |
| | </adm> |
| | |
| | Indien extra items zijn meegegeven worden deze ook geretourneerd in het responsebericht. |
| | |
| |