Creëer zaakobject conform OpenZaak API [Documentatie]

Deze pagina is alleen-lezen. Je kan de broncode bekijken maar niet veranderen. Neem contact op met de beheerder als je denkt dat dit niet klopt.
===== Creëer zaakobject conform OpenZaak API =====
{{tag>oldstable:applicatiebeheer:functionaliteiten:zgw}}

Op het endpoint //base-url//<nowiki>/api/zgw/zaken/api/v1/zaakobjecten/</nowiki> kan een POST worden geplaatst waarmee OpenWave een zaakobject van objectType //adres// of //medewerker// kan toevoegen aan een bestaande zaak.

Indien //adres// dan wordt op grond van deze adresgegevens sowieso een kaart aangemaakt (of bijgewerkt) in tbzaakkadperc die de eigenschap hoofdprojectlocatie krijgt. Daarnaast wordt getracht de zaak op grond van deze adresinformatie te (her)koppelen aan een kaart van tbperceeladressen (de OpenWave locatie-tabel).\\

Indien //medewerker// dan wordt op grond van deze medewerkergegevens een medewerker gezocht in de tabel tbmedewerkers. Indien gevonden dan wordt deze medewerker opgenomen als actieve behandelaar in de tabel tbinbehandelingbij.

De //base_url// is de implementatie van OpenWave waar tegenaan gepraat moet worden, bijvoorbeeld: //<nowiki>https://acc.rommeldam.open-wave.nl</nowiki>//.

Gebaseerd op versie Open Zaak API 1.2

<adm warning 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 [[oldstable: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.
Zie voorbeeld bij [[oldstable:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeer_zgw_zaak]].

Voor het verkrijgen van een token (met beperkte geldigheidsduur!) zie:  [[oldstable: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/zaakobjecten/ /// waarop dit creeer zaakobjectbericht wordt gepost: bijvoorbeeld: ///api/zgw//
</adm>

===== Headers =====

De enige verplichte header variabele is: Content-Type met als waarde //application/json//

===== Body voor doorgeven ADRES=====

<adm example Voorbeeld objecttype adres>
<code json>
  {
   "zaak": "https://acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/zaken/dc594a1a-61ac-49d2-88cd-535029033fe3",
    "objectType": "adres",
    "objectIdentificatie": {
        "identificatie": "0106010000000006",
        "wplWoonplaatsNaam": "Rommeldam",
        "gorOpenbareRuimteNaam": "Wasstraat",
        "huisnummer": 14,
        "huisletter": null,
        "huisnummertoevoeging": null,
        "postcode": null
    }
  }
</code>
</adm>


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 projectlocatie (of het wijzigen van een projectlocatie) in tbzaakkadperc en tot het herkoppelen van de zaak aan een kaart in tbperceeladressen. Dit alles bij een een omgevingzaak of APV/Overige zaak die eerder is aangemaakt en voorzien is van een gevulde kolom dvzgwuuid. 

Die bestaande zaak is reeds gekoppeld aan een perceeladres bij het verwerken van een creeerzaakbericht. Dit zal altijd een dummylokatie zijn (onbekend adres) omdat het creerzaak-bericht geen locatie informatie bevat. Een uitzondering is wanneer waarnemingsgegevens zijn opgenomen als extra items in dat creeerzaakbericht, deze worden dus niet ondersteund door de Open Zaak API, maar OpenWave verwerkt deze optionele gegevens in de klachtenkolommen van een omgevingzaak EN tracht tevens de zaak aan een bestaand valide adres in tbperceeladressen te koppelen.

Indien er geometrie is opgegeven in het creeerzaakbericht dan heeft OpenWave al een een projectlocatiekaart aangemaakt in tbzaakkadperc en deze kaart voorzien van de eigenschap hoofdprojectlocatie. Is dat het geval dan wordt deze projectlocatiekaart met dit creeerzaakobject-bericht bijgewerkt. Anders wordt dus een nieuwe kaart aangemaakt bij de zaak in tbzaakkadperc.

Dit alles, mits aan de nodige voorwaarden in de OpenWave implementatie is voldaan: 
  * 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 (indien de zaak een omngevingzaak is), en anders - dus als de zaak een APV/Overige zaak is - het functionele recht tbovrechten.dlbovvins. 
  * 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**// OF er moet een unieke kaart zijn in tbovvergunningen waarvoor geldt dat tbovvergunningen.dvzgwuuid gelijk is aan deze waarde.

==== Projectlocatie ====
Op grond van de zaak-identifier wordt de zaak opgezocht in tbomgvergunning.dvzgwuuid dan wel tbovvergunningen.dvzgwuuid. Bij de gevonden zaak wordt gekeken of er een kaart is in de tabel tbzaakkadperc (de projectlocaties)  met eigenschap dlhoofdprojectlocatie = 'T'. Zo ja, dan wordt deze kaart bijgewerkt met de objectIdentificatie gegevens uit het bericht. Zo nee dan wordt met deze gegevens een nieuwe kaart aangemaakt met dlhoofdprojectlocatie = 'T'.
Indien het item identificatie uit zestien cijfers bestaat, waarbij posities 5 + 6 samen één van de volgende combinaties vormt: 01, 02, 03, 10, 20 of 30, dan beschouwt OpenWave de identificatie als een BAG-identificatie en wordt de kolom tbzaakkadperc.dvbagid daarmee gevuld.
De kolom tbzaakkadperc.dvzgwuuid wordt overschreven met een op dat moment uitgetrokken unieke UUID-code.

==== Perceeladressen ====

Indien het item identificatie uit zestien cijfers bestaat, waarbij posities 5 + 6 samen één van de volgende combinaties vormt: 01, 02, 03, 10, 20 of 30, dan beschouwt OpenWave de identificatie als een BAG-identificatie en wordt daarmee in tbperceeladressen getracht een unieke kaart te vinden (dus op verblijfsobject, pandidentificatie of nummeraanduiding). Niet gevonden of identificatie voldoet niet aan deze specificaties dan wordt getracht een unieke kaart te vinden in tbperceeladressen op grond van de adresgegevens.

Indien niet gevonden, dan wordt dnkeyperceeladressen niet gewijzigd bij de omgeving- dan wel APV/Overige zaak.
Indien wel een unieke perceeladreslokatie is gevonden (op grond van identificatie dan wel adres), dan wordt de dnkeyperceeladressen bij de zaak gewijzigd met deze gevonden dnkey-waarde.

===== Responsebericht adres ====

Indien het adres niet kon worden aangemaakt of gekoppeld wordt een responsecode anders dan 200/201 geretourneerd met in de body de oorzaak van het falen.
Indien het adres wel succesvol is aangemaakt of gekoppeld 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 bij het zaakobject (tbzaakkadperc.dvzgwuuid) 

<adm example Voorbeeld response body adres>
<code json>
   {
   "url": "https://acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/zaakobjecten/095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
   "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
   "zaak": "https://acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/zaken/dc594a1a-61ac-49d2-88cd-535029033fe3",
    "objectType": "adres",
    "objectIdentificatie": {
        "identificatie": "0106010000000006",
        "wplWoonplaatsNaam": "Rommeldam",
        "gorOpenbareRuimteNaam": "Wasstraat",
        "huisnummer": 14,
        "huisletter": null,
        "huisnummertoevoeging": null,
        "postcode": null
    }
  }
</code>
</adm>

===== Body voor doorgeven MEDEWERKER=====

<adm example voorbeeld objecttype medewerker>
<code json>
{
    "zaak": "acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/zaken/fb03f6c9678349688c726179fffc1efc",
    "objectType": "medewerker",
    "objectIdentificatie": {
        "identificatie": "pdeboer@rem.nl",
        "achternaam": "Boer",
        "voorletters": "P.A.",
        "voorvoegselAchternaam": "de"
    }
}
</code>
</adm>

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.

Openwave zal op grond van het item //identificatie// van het medewerkersbericht de medewerker opzoeken in de tabel tbmedewerkers. Indien gevonden dan wordt deze medewerker opgenomen als actieve behandelaar in de tabel tbinbehandelingbij bij de betreffende zaak.\\ 
Als dit medewerker-zaakobject bericht meerdere malen wordt verstuurd, wordt alleen een nieuwe tbinbehandelingbij-kaart aangemaakt indien de actieve behandelaar een andere is dan wordt doorgegeven.
Die betreffende zaak wordt opgezocht op grond van de uuid-code aan het eind van het item zaak (in bovenstaand voorbeeld: //fb03f6c9678349688c726179fffc1efc//) in tbomgvergunning.dvzgwuuid danwel tbovvergunning.dvzgwuuid.Op welke kolom van de tbmedewerkers de //identificatie// wordt gezocht is afhankelijk van een instelling.

Indien  de kolom //Tekst// van //sectie ZGW en Item: BehandelaarIdentificatieKolom// is:
  * //dvmwexterncode//  dan wordt gezocht op de kolom dvwexterncode (van de niet vervallen kaarten) 
  * //dvloginnnaam//  dan wordt gezocht op de kolom dvloginnaam (van de niet vervallen kaarten) 
  * //dvcode//  dan wordt gezocht op de kolom dvcode (van de niet vervallen kaarten) 
  * //dvemail//  dan wordt gezocht op de kolom dvemail (van de niet vervallen kaarten) 
Indien  de instelling ontbreekt dan wordt gezocht op dvemail

Dit alles, mits aan de nodige voorwaarden in de OpenWave implementatie is voldaan: 
  * 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 (indien de zaak een omngevingzaak is), en anders - dus als de zaak een APV/Overige zaak is - het functionele recht tbovrechten.dlbovvins. 
  * 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**// OF er moet een unieke kaart zijn in tbovvergunningen waarvoor geldt dat tbovvergunningen.dvzgwuuid gelijk is aan deze waarde.

===== Responsebericht medewerker=====

Indien de inbehandelingbij kaart niet kon worden aangemaakt wordt een responsecode anders dan 200/201 geretourneerd met in de body de oorzaak van het falen.
Indien de rij in tbinbehandelingbij wel 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 bij de combinatie zaak/behandelaar (tbinbehandelingbij.dvzgwuuid) 

<adm example Voorbeeld response body medewerker>
<code json>
   {
   "url": "https://acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/zaakobjecten/095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
   "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
   "zaak": "https://acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/zaken/dc594a1a-61ac-49d2-88cd-535029033fe3",
    "zaak": "acc.rommeldam.open-wave.nl/api/zgw/zaken/api/v1/zaken/fb03f6c9678349688c726179fffc1efc",
    "objectType": "medewerker",
    "objectIdentificatie": {
        "identificatie": "pdeboer@rem.nl",
        "achternaam": "Boer",
        "voorletters": "P.A.",
        "voorvoegselAchternaam": "de"
        }
  }
</code>
</adm>