Probleem:
De vrije berichten van het koppelvlak Zaak- en Documentservices (o.a. genereerZaakIdentificatie_Di02, etc.) zijn gedefinieerd als een berichtcatalogus van StUF-ZKN 3.10 in de folder ‘zs-dms’. Dit houdt in dat deze berichten dezelfde namespace hebben als het sectormodel StUF-ZKN 3.10, te weten 'http://www.egem.nl/StUF/sector/zkn/0310'. Dit leidt tot problemen omdat je geen nieuwe versie kunt uitbrengen van deze berichtcatalogus. Immers de enige manier om oude en nieuwe berichten van elkaar te onderscheiden is via de namespace-uri. Nu is de enige optie om met het hele sectormodel over te gaan op een nieuwe versie. Dat laatste is niet realistisch omdat koppelvlakken c.q. berichtcatalogi doorgaans een veel hogere release frequentie hebben dan het sectormodel waarop ze gebaseerd zijn.
Oplossing:
Eerste stap: Definieer de toplevel berichtelementen van de berichtcatalogus in een eigen namespace ZD: ’http://www.kinggemeenten.nl/StUF/koppelvlak/ZaakEnDocumentServices/0110’.
Voorbeeld:
<ZD:updateZaakdocument_Di02 xmlns="http://www.egem.nl/StUF/sector/zkn/0310" xmlns:StUF="http://www.egem.nl/StUF/StUF0301" xmlns:ZKN="http://www.egem.nl/StUF/sector/zkn/0310" xmlns:ZD="http://www.kinggemeenten.nl/StUF/koppelvlak/ZaakEnDocumentServices/0110" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.egem.nl/StUF/sector/zkn/0310 zkn0310_msg_zs-dms.xsd">
<ZKN:stuurgegevens>
<StUF:berichtcode>Di02</StUF:berichtcode>
<StUF:functie>updateZaakdocument</StUF:functie>
</ZKN:stuurgegevens>
<ZKN:parameters>
<ZKN:checkedOutId>123456</ZKN:checkedOutId>
</ZKN:parameters>
<ZKN:edcLk02 StUF:entiteittype="EDC" StUF:functie="update">
…
</ZKN:edcLk02>
</ZD:updateZaakdocument_Di02>
Een nieuwe versie van dit bericht kan eenvoudig worden aangemaakt door de namespace-uri op te hogen naar bijv.
“http://www.kinggemeenten.nl/StUF/koppelvlak/ZaakEnDocumentServices/0120”.
Tweede stap: Verwijder de ‘zs-dms’ berichtcatalogus uit het sectormodel StUF-ZKN en maak deze onderdeel van het koppelvlak Zaak- en Documentservices. De berichten zijn nog steeds gebaseerd op StUF-ZKN maar zijn er geen onderdeel meer van. Het is nu een berichtcatalogus van het koppelvlak.
De hierboven beschreven oplossing is een RFC op StUF-ZKN 3.10 en kan gerealiseerd worden in StUF-ZKN 3.20. In mijn ogen is dit absoluut weer een stap voorwaarts, omdat je nette scherpe koppelvlakken met eigen versies kunt definiëren.
Dit RFC is opgevoerd in de onderhoudsverzoeken als RFC0382.
De lijst met onderhoudsverzoeken vind je op:
gemmaonline.nl/index.php/StUF-Expertgroep#Documenten
Namens Roel de Bruin:
Goed punt en op zich een prima voorstel om dit zo op te lossen. Maar als we deze wijziging pas doorvoeren in StUF-ZKN 0320 dan is de vraag hoe we hier in Zaak- en Documentservices versie 1.2 mee om moeten gaan. Die is immers gepland voordat StUF-ZKN 0320 beschikbaar komt.
Is het wellicht een optie dit voorstel nu al toe te passen voor Zaak- en Documentservices versie 1.2? Dat is immers een nieuwe versie en geen patch. Dus die hoeft niet backwards compatible te zijn.
Goed idee om niet te wachten tot een nieuwe versie van StUF-ZKN en dit voorstel meteen toe te passen op Zaak- en Documentservices versie 1.2.
Zojuist het voorstel ook op het Zaak- en Documentservices forum ingeschoten!
Tijdens de StUF Expertgroep van 18 maart 2015 is het voorstel door de StUF Expertgroep goedgekeurd. In de eerstvolgende versie van StUF-ZKN kan deze berichtencatalogus dus uit het sectormodel worden verwijderd en worden opgenomen in de naar de nieuwe versie van StUF-ZKN verwijzende koppelvlak.
Tevens is tijdens deze StUF Expertgroep het volgende besluit genomen:
In de best practices moet worden opgenomen dat schema’s van berichtencatalogi behorende bij een koppelvlak in een eigen namespace moeten worden geplaatst. Tevens dienen ze in een folder bij de rest van het materiaal van een koppelvlak te worden geplaatst. Tenslotte dient er ook een uri strategie in de best practices te worden opgenomen.
Op basis hiervan is het onderhoudsverzoek ONV0386 opgevoerd.
De lijst met onderhoudsverzoeken vind je op:
gemmaonline.nl/index.php/StUF-Expertgroep#Documenten
Bij het uitwerken van deze scheiding voor het nieuwe koppelvlak Regie- en Zaakservices kwamen wat vragen boven waar ik nog niet uit ben hoe dit op te lossen in de koppelvlakken waar deze RFC over gaat. Laat ik als voorbeeld de Zaak- en Documentservices (ZS-DMS) nemen, welke momenteel nog in de namespace van StUF ZKN zit.
Om het koppelvlak in een eigen namespace te plaatsen zie ik het volgende:
Of zie ik dit verkeerd? Wat is dan het verschil tussen voor een koppelvlak specifieke gegevens en StUF ZKN?
Michiel,
Naar mijn mening moeten alle simpleTypes en complexTypes die nodig zijn voor het koppelvlak in de namespace van het koppelvlak geplaatst worden.
Je plaatst ze alleen in de namespace van StUF-ZKN als ze ook voor andere koppelvlakken van belang zijn.
In dat geval zouden ze trouwens ook aan een van de schema's van StUF-ZKN toegevoegd moeten worden.
Bovenstaande is besproken in de StUF expert groep van 15 april 2015.
Uitkomst was dat hoewel het in de toekomst de bedoeling is ook koppelvlak-specifieke complexTypes en simpleTypes in de daarbij behorende namespaces te plaatsen worden in deze RFC alleen de rootelementen van de berichten in een aparte namespace komen.
M.b.t. ONV0386 heb ik een voorstel tot wijziging van de best practices bijgevoegd.
Bijlage
Tijdens de StUF Expertgroep van 16-9-2015 is de in deze discussie voorgestelde oplossing goedgekeurd behoudens enkele correcties.
Een uri-strategie is echter nog niet opgenomen.
Het onderhoudsverzoek is omgezet naar erratum ERR0386.
In de discussie 'Naamgevingsconventie XML-schema's niet scherp genoeg' is een nieuwe verbeterde versie van de best-practices gepubliceerd met daarin ook enkele correctie n.a.v. ERR0386. Met name in hoofdstuk 4 is de door Henri Korver tijdens de StUF Expertgroep van 16 september 2015 geopperde zin toegevoegd en daarnaast is paragraaf 5.3 m.b.t. de uri-strategie toegevoegd.
Tijdens de StUF Expertgroep van 21-10-2015 zijn we helaas niet aan de behandeling van het bovenstaande voorstel toegekomen. Er is daarom toen afgesproken dat de aanwezige leden eventuele bezwaren binnen 2 weken na de betreffende bijeenkomst kenbaar zouden maken. Aangezien geen bezwaren zijn geplaatst is het voorstel aangenomen en het zal dan ook meegenomen worden in pre-patch 23.
Tijdens de StUf Expertgroep van 18 november 2015 is besloten de voorgestelde oplossing niet op te nemen in patch 23. Dat wat nu in de best practices staat beschreven voldoet namelijk niet helemaal voor StUF-WOZ. Er zal een aangepast voorstel worden gemaakt.
In de discussie 'Naamgevingsconventie XML-schema's niet scherp genoeg' is een nieuwe verbeterde versie van de best-practices gepubliceerd. Het is de bedoeling deze mee te nemen in patch 24.
Tijdens de StUF Expertgroep van 16 maart 2016 is het voorstel goedgekeurd. Dit voorstel gaat mee in patch 24.