Creëer ZGW zaak conform OpenZaak API

ZGW Open Zaak Api functionaliteit in OpenWave

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

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

In de Authorization header van dit POST bericht moet een valide JWT-token worden meegegeven onder Bearer Token.
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/zaken/ waarop dit creerzaakbericht wordt gepost: bijvoorbeeld: /api/zgw

De volgende headers parameters zijn verplicht:

EPSG: 4326 verwijst naar Bosatlas-coördinatenstelsel.

Body

In application/json.

voorbeeld

{
  "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": [
          4.9384269,
          52.3685617 
      ],
      "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"
}

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 mits aan de nodige voorwaarden in de OpenWave implementatie is voldaan:

Er moet tenminste één valide kaart zijn in de OpenWave zaaktype tabel (tbsoortomgverg) 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) 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
Het eventueel doorgegeven registratieNummer (zie hieronder bij extra items) moet niet in de weg zitten.

UUID bij zaaktype(s)

In de zaaktypetabel 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.

Er wordt dan een nieuwe kaart gemaakt in tbomgvergunning met dnkeysoortomgverg = de dnkey van de gevonden rij uit tbsoortomgverg. De omgevingzaak krijgt de waarde van de DummyLokatiePerceelkey als dnkeyperceeladres (hier kan nog vanaf geweken worden bij de niet verplichte waarnemingslokatie-items: zie verderop bij extra items).
Er wordt een unieke UUID-code uitgetrokken voor de aangemaakte zaak en deze code komt in kolom tbomgvergunning.dvzgwuuid (zichtbaar op detailpagina van de omgevingzaak in blok keten mits de kolom is gevuld).

De verplichte items van de body (tot en met zaakgeometrie) worden als volgt ondersteund in de nieuw aangemaakte omgevingszaak:

bronorganisatie. Hier doet OpenWave niets mee
omschrijving komt in de kolom dvaanvraagnaam
toelichting in de kolom dvaanvraagoms
verantwoordelijkeOrganisatie. Hier doet OpenWave niets mee
startdatum in de kolom ddaanvraag
zaakgeometrie. Voor de lijn, punt of vlak wordt een kaart aangemaakt in tbzaakkadperc (en gekoppeld aan de net aangemaakte omgevingzaak) 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.

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

Naast de verplichte items kijkt OpenWave ook naar de volgende extra items in de body. Dit zijn items die niet in de Open Zaak API zijn beschreven. OpenWave gaat hier als volgt mee 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 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 subCategorie bestaat en is gevuld dan 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).
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 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
- indien straatnaamWaarneming bestaat en is gevuld wordt deze waarde overgenomen in tbomgvergunning.dvwaarnemingstraat (blok klacht waarnemingslokatie op het detailscherm)
- indien postcodeWaarneming bestaat en is gevuld wordt deze waarde overgenomen in tbomgvergunning.dvwaarnemingpc (blok klacht waarnemingslokatie op het detailscherm)
- indien plaatsWaarneming bestaat en is gevuld wordt deze waarde overgenomen in tbomgvergunning.dvwaarnemingplaats (blok klacht waarnemingslokatie op het detailscherm)
- 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.

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) en die door de zender gebruikt moet worden voor het aanbrengen van een rol/contactpersoon (Creëer rol en contactadres conform OpenZaak API ) bij de zaak en het koppelen van een document bij de zaak (Koppel Document aan Zaak conform OpenZaak API)
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. 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 omgevingszaak is aangemaakt.

voorbeeld response body

{
"zaakgeometrie": {
  "coordinates": [
    4.9384269,
    52.3685617
  ],
  "type": "Point"
},
"vermoedelijkeVeroorzaker": "windvlaag",
"bronorganisatie": "001509962",
"straatnaamWaarneming": "Cruquiusweg",
"tijdstipOverlast": "13:12:00",
"einddatum": null,
"betalingsindicatieWeergave": "n.v.t",
"uuid": "30cb03a43daf4698b698d7c80eb1c49e",
"verantwoordelijkeOrganisatie": "001509962",
"omschrijving": "Omgevallen lantaarnpaal",
"registratieNummer": "Paultest_001",
"hoofdCategorie": "ik zie",
"huisletterWaarneming": null,
"zaakobjecten": [],
"huisnummertoevoegingWaarneming": null,
"toelichting": "Ja, op de hoek eeghenlaan en cruquiusweg is een lantaarnplaal omgevallen",
"subCategorie": "rommel op straat",
"postcodeWaarneming": "1069AH",
"huisnummerWaarneming": "60",
"identificatie": "2024K0005",
"zaaktype": "https://acc.rommeldam.open-wave.nl/api/zgw/catalogi/api/v1/zaaktypen/365f113f-cb3c-4843-91ce-e7c9467f19c5",
"gemeenteWaarneming": "Amsterdam",
"url": "https://acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/zaken/30cb03a43daf4698b698d7c80eb1c49e",
"rollen": [],
"deelzaken": [],
"startdatum": "2024-08-01",
"datumOverlast": "2024-07-29",
"eigenschappen": [],
"plaatsWaarneming": "Amsterdam",
"zaakinformatieobjecten": [],
"status": null
}

Creëer ZGW zaak conform OpenZaak API

Authorisation Token

Headers

Body

Responsebericht

Documentatie