Klantcontact bij een ZAAK aanmaken > `onderwerpobject`

sytskevanhasselt commented 2 months ago

Description

Als KCM wil ik een klantcontact aan een Zaak kunnen koppelen, zodat alle betrokkenen bij die zaak kunnen zien dat er contact is geweest en wat daar is besproken.

Estimate

3

Acceptance criteria

Na opslaan van het Klantcontact kun je in OpenKlant bij het Klantcontact zien dat er een onderweprObject aanhangt.
Je hoeft na deze story nog geen twee zaaksystemen tegelijk te supporten (dat gebeurt in #873 en #904 ), maar het moet adhv een feature switch (implementeren als environment variabele) mogelijk zijn om OK2 of esuite+adapter hierbij te gebruiken.
Na deze story kun je maar 1 zaaksysteem koppelen aan KISS: ofwel een een zaaksysteem dat met OpenKlant2 kan praten, ofwel de e-Suite.
in de documentatie staat dit duidleijk uitgelegd
In de documentatie staat hoe je de FeatureSwitch moet instellen op dit punt (dus: Klanten en klantcontacten in OK2 bij een zaak uit, OF klanten en contacten in e-Suite)

Specific details

Let op, oude code niet verwijderen: opslaan op de OK1 wijze (voor esuite+adapter moet mogelijk blijven)
Het koppelen van een contactmoment en een zaak gebeurd op twee plekken: in het zaaksysteem en in openKlant. Dat eerste blijft technisch gezien ongewijzigd, Dat tweede werkt anders in OK2. Er moet een onderwerpObject aangemaakt worden van het type Zaak. Deze wordt gekoppeld aan het Klantcontact. Dit werkt met een POST op /onderwerpobjecten, met de volgende body
```
{
"klantcontact": {
"uuid": [id van het bijbehorende contactmoment]
},
"wasKlantcontact": null [altijd null],
"onderwerpobjectidentificator": {
    "objectId": [het id van de zaak. bijcvoorbeeld: ZAAK-2024000001"],
"codeObjecttype": "ZGW-Zaak" [vaste waarde],
"codeRegister": "OpenZaak" [vaste waarde],
"codeSoortObjectId": "identificatie" [vaste waarde]
}
}
```
- Gebruik bij objectId en codeSoortObjectId gegevens die in OpenZaak gebruikt kunnne worden om een zaak op te halen. Mogelijk is dat niet identificatie maar uuid.
Voor de vaste waardes wordt wellicht tzt de referentielijsten api gebruikt. voor deze story is dat buitenscope. opmerkingen over Refentielijsten API in slack
NB: als het koppelen van meerdere zaken aan één klantcontact het werk complex maakt, dan beperken we het tot één.
achtergrond info: Zie ook het onderdeel Onderwerp van het klantcontact, in de Basisterminologie

Test plan

No response

Delivery notes

No response

swrichards commented 4 weeks ago

Bij OIP staan wij zelf op het punt om de koppeling van een Zaak binnen OK2 te implementeren. Ik besef me dat voor deze issue nog niet voorzien is in het gebruik van meerdere zaaksystemen, maar omdat dit voor ons al vroeg een uitdaging is, wilde ik alvast een alternatief voorstel doen ter overweging:

{
  "onderwerpobjectidentificator": {
    // Fully qualified URL naar de zaak, zodat we weten bij welke backend we moeten zijn
    "objectId": "https://test.openzaak.nl/zgw-apis-provider/zrc/api/v1/zaken/dbf3912b-f0f3-417c-a692-514bc7a4171d"

    //Vaste waarden voor de verwijzing
    "codeObjecttype": "zaak",
    "codeRegister": "ZRC",
    "codeSoortObjectId": "zaak-url"
  }
}

Het primaire voordeel hiervan is dat het niet ambigu is bij welke API de zaak kan worden opgevraagd, hetgeen vooral speelt bij meerdere geconfigureerde backends. Nadeel is dat je misschien zelf de UUID moet extraheren als je die nodig hebt voor een andere opties (bijv. een cache lookup).

Is dit iets wat jullie zou passen?

sytskevanhasselt commented 4 weeks ago

Ik denk het wel, we gaan het hier bespreken (@mstokericatt). Dank voor de input.

sytskevanhasselt commented 4 weeks ago

Hoi @swrichards , Wij vroegen ons af of "bij welke API de zaak kan worden opgevraagd" niet volgt uit heet CodeRegister. Maar dat zou wel betekeken dat we, waar wij nu vaste waarde ZRC zetten, we daar een code moeten gebruiken voor het speccifieke zaaksysteem: e-Suite, OpenZaak, Roxit, etc. Dat betekent dat "codeRegister" afgesproken moet worden: per zaaksysteem en per gemeente. (referentielijst?)

swrichards commented 4 weeks ago

Maar dat zou wel betekeken dat we, waar wij nu vaste waarde ZRC zetten, we daar een code moeten gebruiken voor het speccifieke zaaksysteem: e-Suite, OpenZaak, Roxit, etc. Dat betekent dat "codeRegister" afgesproken moet worden: per zaaksysteem en per gemeente.

Ik heb hier ook nog even gepolsd naar de ervaringen in andere projecten. Daar blijkt dat dat dit voorstel in principe erg aantrekkelijk is. Het oorspronkelijke voorstel (geen info over welk zaaksysteem) loopt vaak spaak op het feit dat meerdere zaaksystemen in het ecosysteem eerder regel dan uitzondering zijn (ook >1 systemen van dezelfde leverancier), maar het opnemen van een volledig gekwalificeerde URL heeft dan weer het nadeel dat URLs minder stabiel zijn dan gewenst (met name wat betreft de host: DNS wil nog wel eens veranderen) en eveneens vaak moeilijk verififieerbaar zijn zonder systeem specifieke kennis (Welke versie, welke auth mechanismen, enz.).

Daarmee is iets in de trant van jullie tegenvoorstel een goede balans. De kern daarbij is m.i. dat we ergens in het object een referentie opnemen naar het zaaksysteem, die niet de vorm aanneemt van een URL.

Ik weet niet of codeRegister hiervoor echter de beste plek is. Het is daar wel fijn om ZRC te hanteren zonder subvarianten, dan kan je daar bijvoorbeeld ook makkelijker op filteren en zoeken (het geeft namelijk ook aan dat het in principe om een spec-compliant service gaat, waar die ook draait).

Het alternatief waar elders voor gekozen is, is om de service verwijziging op te nemen in de objectId, bijvoorbeeld als een URN:

{
  "onderwerpobjectidentificator": {
    // Object ID is een URN: namespace is een betekenisvolle label voor een service bekend bij de gemeente, de ID is de zaak identificatie
    "objectId": "urn:openzaak-demodam-primair:ZAAK-2024000001"

    // Zijn constant voor dit soort referenties
    "codeObjecttype": "zaak",
    "codeRegister": "ZRC",
    "codeSoortObjectId": "urn-zaak-identificatie"
  }
}

De namespaces (hier openzaak-demodam-primair) zijn dan inderdaad per gemeente gedefinieerd, en moeten dus out-of-band opgehaald en geconfigureerd worden door clients (bijvoorbeeld via referentielijsten API). Het voordeel hiervan is dat de object ID dus stabiel kan blijven (de achterliggende URL en infrastructuur van openzaak-demodam-primair kan wijzigen, maar de namespace naam kan constant blijven). Dan liggen we minder de nadruk op algemene codes voor algemene zaaksystemen ('eSuite' in het algemeen), maar op de concrete systemen die binnen het ecosysteem van de gemeente bekend zijn. De urn structuur is in principe gedefinieerd en er zullen veelal libraries voorhanden zijn om deze te parsen.

Overigens is er binnen de URN spec ook de mogelijkheid om zogenaamde 'resolver hints' die eventueel ook gebruikt zouden kunnen worden om meer concrete resolver info mee te geven, maar dat is misschien (nog) niet wenselijk.

swrichards commented 3 weeks ago

Zoals besproken tijdens overleg van 17/9 j.l., zullen we ervoor kiezen om de vindplaats op te nemen in codeRegister en de objectId niet te mis/gebruiken om andere gegevens te encoderen dan de ID zelf. Dat krijgen we iets als:

{
  "onderwerpobjectidentificator": {
    "objectId": "ZAAK-2024000001" // of 095be615-a8ad-4c33-8e9c-c7612fbf6c9f

    "codeObjecttype": "zgw-zaak",
    "codeRegister": "openzaak",
    "codeSoortObjectId": "identificatie" // of "uuid"
  }
}

codeObjectType: het lijkt me goed om hier aan te duiden dat het een zaak uit een ZGW zaak systeem betreft. De codeRegister waarde is wellicht alleen zinvol voor partijen in het ecosysteem (die op de hoogte zijn van de infrastructuur en type zaaksystemen dat er draait), maar het lijkt me belangrijk dat codeObjecttype een waarde heeft die betekenisvol is over alle gemeenten.
codeRegister: dit veld is dus vrij 'los', het moet zinvol zijn in de context van de gemeente. Indien er bijvoorbeeld meerdere versies van een openzaak systeem draaien, kan je als mogelijke waarden hebben openzaak-v1.14.0 | openzaak-v1.13.0, of iets als eSuite-primair | openzaak-migratie bij een lopende migratie, enz.
codeSoortObjectID: voor ZGW entiteiten zou het goed zijn om hier ook echt de attribuut namen te gebruiken zoals vastgelegd in de API spec (zoals @sytskevanhasselt ook al voorstelde met identificatie, maar je zou hier eventueel ook uuid kunnen gebruiken, hoewel ik url zou afraden).

mstokericatt commented 2 weeks ago

Ik ben het helemaal eens met het laatste voorstel

Klantinteractie-Servicesysteem / KISS-frontend