Hieronder een voorbeeld hoe OpenWave in te richten om ZGW-berichten om te kunnen zetten naar een zaak, een adres, een contact, extra eigenschappen en een geregistreerd document.

De zender die de ZGW api gebruikt om berichten naar OpenWave te versturen moet gewhitelist worden op de juiste endpoints.
Zie Endpoints whitelist.
Achter de tegel Endpoints Whitelist op het beheerportaal (onder kolom gebruikers) zal minimaal een regel met het endpoint /api/zgw gedefinieerd moeten worden.
Bij dat endpoint kunnen vervolgens één of meer IP-adressen worden genoteerd waarvandaan de zender de berichten gaat versturen.

In de medewerkerstabel moet een (robot) medewerker worden aangemaakt met:

• Loginnaam (dvloginnaam) = de uit te reiken Username aan de zender
• Client secret bij loginnaam t.b.v. accesstoken (dvclientsecret) in het blok Login = het uit te reiken Password aan de zender. Let op: De ingetoetste waarde kan door OpenWave automatisch gecrypt worden opgeslagen indien Getal1 van de instelling Sectie: Encryption en Item: Method de waarde 3 heeft. Zie 2-way encryptie van externe wachtwoorden. Aan de zender moet dus de ongecrypte versie worden uitgereikt.

Met deze twee gegevens kan de zender een token opvragen aan OpenWave die de zender met elk bericht dient mee te sturen als authenticatie.

Bij de medewerkerskaart:

• vul de organisatienaam (dvorganisatie) met een benaming voor de ontvangende instantie (bijvoorbeeld OD Rommeldam e.o.)
• vul de achternaam van de robot (dvomschrijving) met een benaming voor de zendende instantie (bijvoorbeeld milieuklachten Gelderland)
• vul de kolom 1=robot, 2=browser, 3=beide (dnmaginapp) met 1 (robot)
• Voeg de robot toe aan een rechtengroep die minimaal het insertrecht op omgevingzaken heeft (tbomgrechten.dlomgins) indien de aangebracht zaken in tbomgvergunning kunnen worden opgeslagen.
• Voeg de robot (ook) toe aan een rechtengroep die minimaal het insertrecht op APV/Overige zaken heeft (tbovrechten.dlovvins) indien de aangebracht zaken in tbovvergunningen kunnen worden opgeslagen.
• kies bij de dropdownkolom Endpoint (robotmedewerker is gedefinieerd voor binnenkomende berichten op endpoint) (dnkeyendpointlist) in het blok Login voor de whitelist met de waarde /api/zgw
• De (robot)-medewerker moet in dienst zijn (vervaldatum leeg of > vandaag)

Base-url
Vul de kolom Tekst van Sectie: Operations en Item: Servernaam_hyperlink met de base-URL van de OpenWave installatie bijvoorbeeld https://acc.rommeldam.open-wave.nl. Deze base-URL moet gecommuniceerd worden met de instantie die OpenZaak berichten gaat posten in OpenWave zodat de berichten op het juiste endpoint terechtkomen (zie: Voorbeeldberichten ZGW creëren van zaak).

Anoniem contactpersoon
Vul de kolom Getal1 van Sectie: ZGW en Item: KeyAnoniemContactAdres met een valide verwijzing naar de primary key van een contactadreskaart die gaat functioneren als anoniem contactpersoon. Dat anonieme contactadres wordt gebruikt indien het bericht dat dient om een contactpersoon toe te voegen aan een zaak niet voldoende gegevens bevat.

Onbekende lokatie
De kolom// Getal2// van de instelling Sectie: Koppeling ZAAK en Item: DummyLokatiePerceelkey moet gevuld zijn met een waarde die verwijst naar een dnkey van tbperceeladressen die gebruikt wordt om de zaak aan een locatie te koppelen bij ontbrekende lokatie-informatie. Bij het ontvangst van het eerste ZGW-creeer zaakbericht zal deze onbekende adresverwijzing worden gebruikt, omdat de lokatiegegevens normaliter pas in een vervolgbericht worden doorgegeven\.

Messagelog
Vul het aanvinkvakje van Sectie: ZGW en Item: Messagelog zodat alle binnenkomende en uitgaande berichten gelogd worden.

Eén contactadres bij een zaak
Door in Sectie: ZGW het Item: CheckEenRolContactPerZaak aan te vinken wordt geregeld dat er maar één contactpersoon via de ZGW-api kan worden doorgegeven bij een zaak.

Aavrager bij aanmaken zaak met StUf Zaak/DMS
Alleen indien sprake is van StUF Zaak/DMS-koppeling op het zaaktype dat aangesproken wordt door zender, dan moet de kolom Getal1 van Sectie: ZGW en Item: KeyVoorlopigeAanvrager gevuld worden met een valide verwijzing naar de primary key van een contactadreskaart die gaat functioneren als voorlopige initiator voor de StUF Zaak/DMS -bericht.

Hoe medewerker te traceren bij binnenkomend creeer zaakobjecttype medewerker
Wanneer de zender dit bericht stuurt moet de medewerker uit het bericht gezocht worden in tbmedewerkers om een kaart aan te maken in tbinbehandelingbij bij de zaak.
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)

In alle andere gevallen wordt gezcht op dvemail (ook wanneer deze instelling ontbreekt)

In de zaaktypetabellen tbsoortomgverg en/of tbsoortovverg (zaakbeheerportaal) moeten bij de zaaktypes waaronder met de ZGW-API zaken gecreeerd kunen worden een unieke UUID-code worden gegenereerd en geplaatst in de kolom dvzgwuuid in het blok categorie in het detailscherm van zaaktype. Indien de UUID-kolom leeg is kan met de wizard knop erachter een code worden gegenereerd. Deze code(s) kunnen vervolgens buiten OpenWave om eenmalig gecommuniceerd worden met de zender zodat deze het item zaaktype in de body van het creeer zaakbericht kan vullen.
De zender kan deze ook ophalen met een GET op het endpoint base-url/api/zgw/catalogi/api/v1/zaaktypen\.

Indien de zaak ook door OpenWave aangemaakt moet worden in het externe zaaksysteem/DMS (via de StUF-standaard) dan moeten bij deze zaaktypes de kolom Verplichte adressoort (rol) (dvadressoortverpl) gevuld worden met de codering van tbadressoort die gaat gelden als de rol initiator voor het DMS.

In de tabel tbzgwzaakobjecttypes (dochtertabel van de zaaktypes uit tbsoortomgverg en uit tbsoortovverg) moeten per zaaktype een unieke UUID-code worden gegenereerd met de eigenschap dvobjectype: adres en een met objecttype medewerker en geplaatst in de kolom tbzgwzaakobjecttypes.dvzgwuuid. Deze tabel is via het detailscherm van tbsoortomgverg en/of tbsoortovverg (zaakbeheer) te benaderen in het blok zaakobjecttypen onder aan de pagina.
Bij een insert om een zaakobjecttype toe te voegen aan een zaaktype moet de beheerder kiezen uit medewerker of adres. Meer mogelijkheden ondersteunt OpenWave niet.
Het objecttype adres wordt gebruikt om een lokatie toe te voegen aan een zaak (zowel in tbzaakkadperc met hoofdprojectlocatie = true, als herkoppelen van een zaak aan een perceelkadres).
Het objecttype medewerker wordt gebruikt om een behandelaar toe te voegen aan een zaak. Zie hierboven bij instellingen hoe
Op de detailkaart van de toegevoegde combinatie zaaktype/objecttype kan de UUID-code worden gegenereerd met de wizardknop achter het UUID-veld (indien de kolom leeg is).
Elke combinatie objecttype en zaaktype heeft dus een eigen uniek uuid
De zender kan deze opvragen op het endpoint base-url/api/zgw/catalogi/api/v1/zaakobjecttypen/

In de roltypetabel tbzgwroltypes (koppeltabel tussen de zaaktypes uit tbsoortomgverg en uit tbsoortovverg met de tabel tbadressoort) moeten bij één of meer combinaties zaaktype/adressoort een unieke UUID-code worden gegenereerd en geplaatst in de kolom tbzgwroltypes.dvzgwuuid. Deze tabel is via het detailscherm van tbsoortomgverg en/of tbsoortovverg (zaakbeheer) te benaderen in het blok roltypes onder aan de pagina. Bij een insert om een roltype toe te voegen aan een zaaktype moet de beheerder kiezen uit de niet-vervallen adressoorten waarvoor geldt dat de kolom dvvantoepop is gevuld met een W (indien aan een omgevingzaaktype wordt gekoppeld) of met een O (indien uit een APV-Overige zaaktype wordt gekoppeld).
Op de detailkaart van de toegevoegde combinatie zaaktype/adrerssoort kan de UUID-code worden gegenereerd met de wizardknop achter het UUID-veld (indien de kolom leeg is).
Elke combinatie adressoort en zaaktype heeft dus een eigen uniek uuid
Deze uuid-code(s) moeten vervolgens buiten OpenWave om eenmalig gecommuniceerd worden met de zender zodat deze het item roltype in de body van het creeer rol/contactpersoon-bericht kan vullen. Deze roltypen kunnen ook opgehaald worden door de zender op het GET endpoint base-url/api/zgw/catalogi/api/v1/roltypen.

De adressoorten/rollen die hiervboven gekoppeld zijn aan een of meer zaaktypes moeten voorzien worden van een generieke ZGW-omschrijving.
De tabel adresoort bevindt zich in het beheerportaal onder de kolom administratie.
Op het detailscherm van de bewuste adressoorten dient de kolom rol (dvomschrijving) EN de dropdownkolom Generieke omschrijving Open Zaak API (dvzgwgeneriekeoms) gevuld te zijn. Dit is noodzakelijk om een valide antwoord te genereren op het GET endpoint base-url/api/zgw/catalogi/api/v1/roltypen.

In de documenttypetabel tbdocumenttype moeten bij één of meer documenttypes die de zender mag gebruiken, een unieke UUID-code worden gegenereerd en geplaatst in de kolom dvzgwuuid. Deze tabel is benaderbaar onder de tegel documenttypen onder de kolom werkbeheer in het beheerportaal. De UUID kan met de wizardknop achter de kolom worden gegenereerd mits die kolom een lege waarde bevat. Deze code(s) moeten vervolgens buiten OpenWave om eenmalig gecommuniceerd worden met de zender. Deze kunnen ook opgehaald worden door de zender op het GET endpoint base-ur/lapi/zgw/catalogi/api/v1/informatieobjecttypen\.

In de zaakeigenschappen tbdsospecvraagid (dochtertabel tussen de zaaktypes uit tbsoortomgverg en uit tbsoortovverg die ook gebruikt wordt voor instructies op basis van een DSO STAM-bericht) kunnen bij één of meer zaaktypes een unieke UUID-code worden gegenereerd en geplaatst in de kolom tbdsospecvraagid.dvdsovraagid. Deze tabel is via het detailscherm van tbsoortomgverg en/of tbsoortovverg (zaakbeheer) te benaderen in het blok zaakeigenschappen onder aan de pagina.
Op de detailkaart van de toegevoegde zaakeigenschap kan de UUID-code worden gegenereerd met de wizardknop achter het UUID-veld dvdsovraagid (indien de kolom leeg is).
Elke combinatie eigenschap en zaaktype heeft dus een eigen uniek uuid
Daarnaast heeft elke eigenschap een formaat, een maximale lengte en een kardinaliteit.

• 0.n wil zeggen dat de waarde meerder keren of helemaal niet kan voorkomen
• 0.1 wil zeggen dat de waarde één keer of helemaal niet kan voorkomen
• 1 wil zeggen dat de waarde één keer moet voorkomen
• 1.n wil zeggen dat de waarde minimaal één keer moet voorkomen

De zender kan per zaaktype de mogelijke door te geven eigenschappen ophalen met een GET op het endpoint base-url/api/zgw/catalogi/api/v1/eigenschappen/. Met de POST op het endpoint base-url/api/zgw/zaken/api/v1/zaken/{identifier}/zaakeigenschappen kan de zender een waarde, een zaak-UUID en een eigenschap- UUID doorgeven.
In deze zaakeigenschappentabel kan gedefineerd worden hoe die waarde te verwerken bij de zaak.

Hieronder volgen een aantal voorbeelden:

select dnkey from tbproducten 
    where dnkeyproductdef = (select dnkey from tbproductdef where lower(dvproductcode) = lower(%dvdsoantwoord%)) 
    and dnkeysoortomgverg = (select dnkeysoortomgverg from tbomgvergunning where dnkey = %keypointer%)

Een gevulde keyerwjzing in Getal1 van Sectie: ZGW en Item: KeyVoorlopigeAanvrager is nodig omdat bij het creëren van een zaak in het DMS via StUF een initiator verplicht is. Die initiator zit echter niet in het Open Zaak API - creeer Zaak bericht, op grond waarvan het Stuf bericht voor het creëren van de zaak in het DMS wordt gefabriceerd: direct bij ontvangst van het ZGW-creerzaakbericht. Bij het ontbreken van deze verwijzing zal er geen zaak in het DMS worden aangemaakt en kunnen dus ook geen documenten gestald worden.

Wanneer

• nadat een ZGW-zaak is aangemaakt en deze zaak is succesvol doorgezet naar het ZAAK/DMS systeem (in dat geval wordt de kolom dvintzaakcode in de OpenWave zaak gevuld).
• EN er naderhand een ZGW-Creëer rol en contactadres binnenkomt, waarbij het roltype uuid verwijst naar de intiator-rol (die uuid wordt opgezocht in de tabel tbzgwroltypes : de mogelijke rollen per zaaktype. De adressoort van die gevonden kaart in tbzgwrollen moet verwijzen naar een kaart in tbadressoorten met dvzgwgeneriekeoms = initiator.
  dan zal OpenWave alsnog automatisch in een stuf-UpdateZaakbericht deze contactgegevens als initiator doorgegeven aan het ZAAK/DMS.

Samenvattend: Voor een goede ZAAK/DMS koppeling met betrekking tot de initiator aangeleverd via een ZGW-bericht moet het volgende ingesteld worden:

• Er moet een instelling zijn met in kolom Getal1 van Sectie: ZGW en Item: KeyVoorlopigeAanvrager een valide verwijzing naar de primary key van een contactadreskaart die gaat functioneren als voorlopige initiator voor de StUF Zaak/DMS -bericht.
• Op het detailscherm van het ZGW-zaaktype (zaakbeheerportaal: of tbsoortomgverg of tbsoortovverg) zal in het blok// Roltypes tbv ZGW-api// een rij aanwezig moeten zijn met een gevulde uuid voor het ZGW-roltype die verwijst naar een adressoort met tbadressoort.dvzgwgeneriekeoms = initiator
• Die initator-adressoort moet gelijk zijn aan het de inhoud van de kolom verplichte adressoort tbsoortomgverg.dvadressoortverpl of tbsoortovverg.dvadressoortverpl) bij het zaaktype