[VRAAG] Wat is de CMIS-mapping van resources in de Documenten API

joeribekker commented 9 months ago

Op dit moment zetten wij (Open Zaak) resources om in meta-data in CMIS, indien je koppelt met een DMS (via CMIS dus).

Er is, net als bij ZDS 1.x, een "zaakfolder", met daarin het fysieke document, aangevuld met meta data zoals dat is meegegeven via de Documenten API. Voor andere resources in de Documenten API (Verzending, Gebruiksrechten, ObjectInformatieObject) maken we enkel een meta data bestand aan, die deze resource-attributen als CMIS-properties bevat.

Er is echter geen goed gedefinieerde mapping is van de Documenten API naar CMIS-properties, waardoor andere leveranciers dit anders kunnen oplossen, wat onwenselijk is.

Ook blijkt het best wel lastig te zijn om allerlei meta data bestanden te maken voor resources maar we zien geen andere manier omdat we beperkt zijn in wat we allemaal in een CMIS-property kunnen stoppen (geen array's dien dan ook nog doorzoekbaar zijn bijvoorbeeld).

Wellicht is het goed om eens te kijken om de mapping te beproeven, op te schrijven en mee te standaardiseren.

robklomp commented 9 months ago

Ik heb dit met Joeri doorgesproken omdat wij ons FileNet DMS willen aansluiten op Open Zaak of een andere Documenten API. Maar de Documenten API dreigt aan zijn complexiteit ten onder te gaan, wat natuurlijk niet de bedoeling kan zijn.

De essentie van een DMS is opslag van documenten met content en metadata plus een of meer (evt. gelaagde) folders met metadata waaraan deze gekoppeld zijn. Documenten en folders kunnen op ID, metadata of relatie met folders opgezocht worden. Het ligt voor de hand om een bestaand DMS achter de API aan te sluiten, waarbij CMIS koppeling een logische keuze is omdat vrijwel alle DMS'en dit ondersteunen. Daar spelen wel een paar issues mee, zoals de 3 mogelijke CMIS varianten (SOAP, Atompub en Browser Binding) en onvolledige implementatie bij sommige DMS'en (bv Corsa).

Ik denk dat het verstandig is om de Documenten API zo eenvoudig mogelijk te houden en zo dicht mogelijk bij de basis DMS- en CMIS-mogelijkheden. Hoe meer functionaliteit in de API hoe moeilijker de implementatie wordt, met als risico dat implementatiepartijen afhaken of onvolledige API's bouwen. Als het datamodel van documenten en folders eenvoudig gehouden wordt (zoals bij ZDS) dan hebben we de meeste kans dat verschillende partijen verschillende DMS'en kunnen voorzien van de Documenten API. Met folders als structuur en dataopslag is veel te bereiken maar er zijn grenzen. De hoeveelheid metadata elementen is overigens geen probleem, complexiteit soms wel. Bv. arrays: die zou je mogelijk kunnen implementeren met meerdere folders gerelateerd aan een document. Maar of dat in elk DMS kan weet ik niet, in FileNet in ieder geval wel.

Daarnaast bevatten DMS'en heel veel historie! We moeten daarom rekening houden met het ontstaan van nieuwe datamodellen: vroeger documenten zonder zaken, daarna het ZDS model met zaken, nu de Documenten API en in de toekomst weer iets nieuws. Ondanks dat moeten alle documenten centraal vindbaar blijven.

Lijkt me goed om eens een overleg in te schieten met een aantal mensen met kennis van hun DMS.

michielverhoef commented 9 months ago

Op zich een goed idee om de vertaling naar CMIS uit te werken. Aangezien jullie al een uitwerking hebben lijkt het me goed om daar van uit te gaan.

Enkele vragen die ik alvast heb: De meta data bestanden, gaat het om de resources verzending, objectinformatieobject nen gebruiksrechten? Worden dat dan cmis:items of cmis:objecten? Vanuit onderstaande documentatie begrijp ik dat een cmis:item geen versionering kent, wat het misschien lastig maakt om te tijdreizen.

NB. Ik ben uitgegaan van wat ik hier gelezen heb: https://subscription.packtpub.com/book/web-development/9781782163527/1/ch01lvl1sec12/an-overview-of-the-cmis-standard

EduardWitteveen commented 9 months ago

@robklomp Wij gebruiken ook cmis in combinatie met openzaak. Graag neemt de gemeente Súdwest-Fryslân hier aan deel, op basis van de vraag zal @jachov en ik aanwezig zijn

robklomp commented 9 months ago

@joeribekker kun jij de vraag van Michiel beantwoorden? Ik merk dat ik achter loop met de documenten API... En ik heb geen idee hoe dit in CMIS op alle gangbare DMS'en (!) kan werken, want ik vermoed dat daar wel een probleem zit. Vandaar mijn voorstel om het model eenvoudig te houden.

michielverhoef commented 9 months ago

Ik ga een datumprikker rondsturen. Aan iedereen die mee zou willen doen en geen uitnodiging heeft ontvangen, laat het me even weten en ik voeg je toe.

michielverhoef commented 8 months ago

Er blijkt behoefte te zijn aan duidelijkheid omtrent de status van CMIS en een mapping op de Documenten API. De bestaande mapping uit Zaak- Documentservices (ZDS) lijkt bruikbaar maar bij nadere bestudering heb ik nog een aantal vragen:

Onderstaande is op basis van de Specificatie Zaak- Documentservices 1.2 maar komt ook in eerdere versies van ZDS voor.

In ZDS is het Zaaksysteem de ingang voor het vastleggen van documenten. Het DMS wordt niet rechtstreeks benaderd.
Bij het aanmaken van een zaak CreeerZaak wordt door het zaaksysteem in het DMS een folderstructuur aangemaakt volgens de Zaken DMS Boom

In de API's voor Zaakgericht werken (ZGW) wordt de Documenten API rechtstreeks aangesproken door de consumer applicatie. In de aanroepen is geen zaakinformatie beschikbaar en het is ook mogelijk om informatieobjecten die niet zaakgericht zijn in de Documenten API op te slaan. Alleen bij het aanmaken van een ObjectInformatieObject vanuit de Zaken API is zaakinformatie bekend. Dat is dan ook alleen maar de url naar die zaak toe.

De informatie om een Zaken DMS boom aan te maken en de juiste folder te gebruiken om een enkelvoudiginformatieobject aan te maken ontbreekt in de POST EIO operatie

Dit maakt het lastig om een document gelijk al op de juiste plaats in een DMS te plaatsen. De CMIS Adapter van Open Zaak lost dit probleem op door een document eerst in een tijdelijke folder te plaatsen en het informatieobject te verplaatsen bij het toevoegen aan een zaak.

De Zaken DMS boom lijkt zo te zien geen goede structuur. Tenzij we de scope van de Documenten API drastisch aanpassen is de vraag: Hoe moet het dan wel? Om het informatieobject als gegeven direct onder de root te nemen maakt het wel een heel grote, onoverzichtelijke boel.

Maar zoals gezegd, de informatie ontbreekt voor een structuur als deze (geleend van de CMIS adapter van OpenZaak):

CMIS Root
+-- DRC (cmis:folder)
    +-- [zaaktype-folder] (drc:zaaktypefolder)
        +-- [year] (cmis:folder)
            +-- [month] (cmis:folder)
                +-- [day] (cmis:folder)
                    +-- [zaak-folder] (drc:zaakfolder)
                        +-- [filename] (drc:document)
                        +-- Related data (cmis:folder)
                            +-- [filename]-gebruiksrechten (drc:gebruiksrechten)
                            +-- [filename]-oio (drc:oio)

michielverhoef commented 8 months ago

Na er nog eens over nagedacht te hebben is de enige andere oplossing (anders dan die ik zo 1,2,3 kan bedenken een bericht waarmee zowel een nieuw EIO gemaakt kan worden als een relatie met een zaak gelegd kan worden.

Los van een dergelijk bericht maken zitten er nog wat hobbels op de weg: Op dit moment mag een ObjectInformatieObject alleen aangemaakt worden door de Zaken API of de Besluiten API. Bovendien is er (nog) geen synchonisatie van de Documenten API met De Zaken API beschreven. Maar niets wat niet opgelost kan worden.

@robklomp @EduardWitteveen

robklomp commented 8 months ago

@michielverhoef
Ik zou een paar uitgangspunten willen voorleggen voor de Documenten API.

Willen we als uitgangspunt nemen dat de Documenten API mede bedoeld is als interface voor een separaat DMS (van diverse fabricaten)? Voor ons (Gemeente Tilburg) is dat heel logisch, dus hopelijk ook voor vele andere gebruikers.
Zo ja dan moeten we in de API ook rekening houden met de algemene doelstellingen en mogelijkheden van een DMS. Primair zijn daar documenten met content en metadata en folders met metadata waar documenten aan gelinkt kunnen worden. Vaak zijn er nog andere (custom) objecten mogelijk maar dat varieert per DMS.
CMIS is heel een bruikbare interface die over het algemeen wel de mogelijkheden van het DMS ondersteunt: is dus niet meer dan een middel om het DMS te bedienen. Maar gelukkig wel een breed ondersteunde wereldstandaard.
Daarbij moeten we er rekening mee houden dat niet alle DMS'en alle interne en CMIS mogelijkheden (en 3 varianten in 2 versies) ondersteunen. Met andere woorden: als we de nieuwste en meeste fancy mogelijkheden gebruiken dan zullen sommige DMS dat niet ondersteunen. Dat beperkt enigszins wat zinvol is om in de API op te nemen.
@michielverhoef geeft terecht aan dat de Documenten API niet per se gekoppeld hoeft te zijn aan zaakgericht werken: prima, dat vergroot de bruikbaarheid.
Het DMS datamodel van ZDS 1.1 (1.2) is prima maar je moet je afvragen of je in het DMS een ander datamodel wilt gebruiken dan in de API zelf. Dat is weliswaar handig voor historie maar minder handig voor mapping naar de nieuwe API.
Zaakgegevens in het DMS zijn redundant maar zeker nuttig voor de context van documenten. Het systeem van Zaaktypefolders met daaronder Zaakfolders werkt prima. De year/month/day lagen zijn gelukkig optioneel want die verstoren het zoeken op path.

Samenvattend zou ik willen pleiten voor een Documenten API als gestandaardiseerd voorportaal voor een DMS, daarbij rekening houdend met de mogelijkheden van de in Nederland meest voorkomende DMS'en. Dat betekent:

oppassen met functionaliteit die ver van normaal DMS gebruik staat (bv. Verzending?)
niet te complex datamodel, bij voorkeur een plat model voor documenten en folders (bv Ondertekening)
1:1 mapping van API naar DMS properties
soms zijn URL's te groot voor normale string properties. Het gebruik van text/CLOB properties is niet handig omdat die meestal niet indexeerbaar zijn. Eventueel verdelen over 2 of 3 properties (bv uuid + pad1 + pad2).
1:n relaties zoals Verzending zijn lastiger te implementeren in sommige DMS'en. Hoewel CMIS 1.1 daar zeker ondersteuning voor biedt wordt niet alles door elk DMS ondersteund. Eenvoudige 1:n CSV strings zoals trefwoorden zijn wel mogelijk.
DMS'en die echt te weinig functionaliteit bieden moeten we misschien uitsluiten óf alternatief oplossen. Bv. Verzending buiten DMS opslaan (in Open Zaak of Objecten API). En misschien wel optioneel maken, want wie gaat dat ook werkelijk invullen?

Overigens is het gebruikelijk om documenten eerst op te slaan en pas later aan een zaak te koppelen. Bijvoorbeeld een document aangeboden bij een webformulier-aanvraag wordt opgeslagen voordat de zaak aangemaakt wordt. Dat is voor een DMS ook geen probleem want de relatie document-folder(s) kan altijd later gelegd worden. Zaakgegevens zullen ook aan een document gekoppeld moeten worden bij het koppelen van document aan zaak via de Zaken API. Dat was bij ZDS ook zo. Daar zullen meerdere API calls voor nodig zijn.

VNG-Realisatie / gemma-zaken

[VRAAG] Wat is de CMIS-mapping van resources in de Documenten API #2353