Package: drc-cmis
Version:1.8.0Source:https://github.com/open-zaak/cmis-adapterKeywords:CMIS, Documenten API, VNG, Common GroundPythonVersion:3.7A CMIS backend-connector for theDocumenten API.Developed byMaykin Media B.V.commissioned by the municipality of Utrecht
with support of the municipality of Súdwest-Fryslân and the Open Zaak project
team.IntroductionThe Documenten API CMIS adapter allows Django implementations of the Documenten
API to easily connect to a CMIS-compatible Document Management System (DMS).
Most notably it’s used byOpen Zaakto use a DMS as backend for the
Documenten API rather then using its own backend.FeaturesBothCMIS 1.0andCMIS 1.1are supported but not for all bindings. Below
is a list of supported bindings for each CMIS version.CMIS 1.0CMIS 1.1Web Services bindingSupportedUntestedAtomPub bindingUntestedUntestedBrowser bindingN/ASupportedFor the supported bindings, the following features are implemented:Retrieve from and store documents in a CMIS-compatible DMS.Supports reading and writing of documents.Supports checking out/in of documents.Supports custom data-model for storing additional meta data.Tested against:Corsa platformusing CMIS 1.0 Web Services binding (Thanks toBCT)AlfrescoEnterprise 5.2.3 using CMIS 1.1 Browser binding (Thanks toContezza)Alfresco CE 6.1.2-ga(Used for CI)InstallationNOTE: If you are using Open Zaak 1.3.1 or above, the CMIS-adapter is already
included and does not require separate installation.RequirementsPython 3.7 or abovesetuptools 30.3.0 or aboveDjango 3.2 or newerInstallInstall the library in your Django project:$pipinstalldrc-cmisAdd toINSTALLED_APPSin your Djangosettings.py:INSTALLED_APPS=[..."drc_cmis",...]Create a mapping file to match Documenten API attributes to custom
properties in your DMS model. SeeMapping configuration.In yoursettings.py, add these settings to enable it:# Enables the CMIS-backend and the Django admin interface for configuring# the DMS settings.CMIS_ENABLED=True# Absolute path to the mapping of Documenten API attributes to (custom)# properties in your DMS content model.CMIS_MAPPER_FILE=/path/to/cmis_mapper.jsonLogin to the Django admin as superuser and configure the CMIS backend.Mapping configurationThere are 2 important concepts:Content model - The DMS configuration to store (custom) properties on folders
and documents. These properties are called CMIS properties.CMIS-mapper - a JSON-file containing the translation from Documenten API
attributes to CMIS properties.Mapping the Documenten API attributes to (custom) CMIS properties in the DMS
content model should be done with great care. When the DMS stores these
properties, the Documenten API relies on their existance to create proper responses.Below is a snippet of the CMIS-mapper:{"DOCUMENT_MAP":{"titel":"drc:document__titel"}}TheDOCUMENT_MAPdescribes the mapping for theEnkelvoudigInformatieObjectresource in the Documenten API. In this
snippet, only theEnkelvoudigInformatieObject.titelattribute is mapped to
a custom CMIS property calleddrc:document_titel.Communication between the Documenten API using the CMIS-adapter, is done via
CMIS. Therefore, when creating a document via the Documenten API, the
attributes are translated to CMIS properties as shown below (note that this is
a stripped down request example).<?xml version="1.0"?><soapenv:Envelopexmlmsg:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlmsg:msg="http://docs.oasis-open.org/ns/cmis/messaging/200908/"xmlmsg:core="http://docs.oasis-open.org/ns/cmis/core/200908/"><soapenv:Header/><soapenv:Body><msg:createDocument><msg:repositoryId>d6a10501-ef36-41e1-9aae-547154f57838</msg:repositoryId><msg:properties><core:propertyStringpropertyDefinitionId="drc:document__titel"><core:value>example.txt</core:value></msg:properties><msg:folderId>workspace://SpacesStore/7c6c7c86-fd63-4eec-bcf8-ffb59f6f6b90</msg:folderId></msg:createDocument></soapenv:Body></soapenv:Envelope>An example of the mapping configuration, with all possible Documenten API
resources and attributes is shown intest_app/cmis_mapper.json(cmis_mapper.json). The related DMS content model, that has the definitions
for all these CMIS properties, forAlfresco(an open source DMS) is in/alfresco/extension/alfreso-zsdms-model.xml(alfreso-zsdms-model.xml).
Both the mapping and the model should be aligned.MappingsThe content model and the CMIS-mapper configurations need to be aligned. For
each object, the API resource, the CMIS objecttype, CMIS basetype and the
(configuratble) CMIS-mapper object is described.DocumentThe document itself, its content and meta data.Documenten API resourceEnkelvoudigInformatieObjectCMIS objecttype *drc:documentCMIS basetypecmis:documentCMIS-mapper objectDOCUMENT_MAPThe mapping between API-attributes and CMIS properties can be found in thecmis_mapper.json.GebruiksrechtenUsage rights. These rights don’t need to be enforced by the DMS but are stored
for use outside the DMS.Documenten API resourceGebruiksrechtenCMIS objecttype *drc:gebruiksrechtenCMIS basetypecmis:documentCMIS-mapper objectGEBRUIKSRECHTEN_MAPThe mapping between API-attributes and CMIS properties can be found in thecmis_mapper.json.ObjectInformatieObjectRelation between a document and another object, like a Zaak, Besluit or
something else.Documenten API resourceObjectInformatieObjectCMIS objecttype *drc:oioCMIS basetypecmis:documentCMIS-mapper objectOBJECTINFORMATIEOBJECT_MAPThe mapping between API-attributes and CMIS properties can be found in thecmis_mapper.json.Zaaktype folderContains all Zaken from this Zaaktype and has itself some meta data about the
Zaaktype. API-attributes are from theCatalogi APIZaaktype-resource.Catalogi API resourceZaaktypeCMIS objecttype *drc:zaaktypefolderCMIS basetypecmis:folderCMIS-mapper objectZAAKTYPE_MAPThe mapping between API-attributes and CMIS properties can be found in thecmis_mapper.json.Zaak folderContains all Zaak-related documents and has itself some meta data about the
Zaak. API-attributes are from theZaken APIZaak-resource.Zaken API resourceZaakCMIS objecttype *drc:zaakfolderCMIS basetypecmis:folderCMIS-mapper objectZAAK_MAPThe mapping between API-attributes and CMIS properties can be found in thecmis_mapper.json.* CMIS objecttype:cmis:objectTypeIdDMS Content model configurationThe CMIS mapper configuration must match the content model in the DMS. Each
property, likedrc:document__titelin the example above, must be defined
in the content model.The example shown in/alfresco/extension/alfreso-zsdms-model.xmlindicates all attributes, types and whether the property is indexed (queryable)
or not. If these attributes are incorrectly configured, the Documenten API
might not work correctly.DMS folder structureOpen Zaak uses a folder structure in the DMS similar to theZaak- en Documentservices 1.2. However, due to way the Documenten API works
there are differences.Creating a documentWhen a document is created via the Documenten API, the document is placed in a
temporary folder. By default this is:CMIS Root
+-- DRC (cmis:folder)
    +-- [year] (cmis:folder)
        +-- [month] (cmis:folder)
            +-- [day] (cmis:folder)
                +-- [filename] (drc:document)For example:CMIS Root > DRC > 2020 > 12 > 31 > document.txtIf nothing else happens, this document will remain here.Creating gebruiksrechtenA document can have Gebruiksrechten. These are stored as a separate document
(gebruiksrechten) in a folder calledRelated data. This folder is
always in the same folder as the document itself and is of typecmis:folder.The Gebruiksrechten will always be moved or copied along with the document.For example:CMIS Root > DRC > 2020 > 12 > 31 > document.txt
CMIS Root > DRC > 2020 > 12 > 31 > Related data > document.txt-gebruiksrechtenRelating a document to a ZaakRelating a document to a Zaak (by creating anObjectInformatieObjectinstance in the Documenten API) will cause the document and its Gebruiksrechten
if it exists, to bemovedorcopiedto the zaak folder.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)A document ismovedwhen the document wasnot relatedto a Zaak before
(and thus it was in the temporary folder). The document iscopiedto the
new zaak folder when the document wasalready relatedto a Zaak.The relation of a document to a Zaak is implicitly described by its path. In
addition however, this relation is stored as a separate document (oio) in
theRelated datafolder.For example:CMIS Root > DRC > Melding Openbare Ruimte > 2020 > 12 > 31 > ZAAK-0000001 > document.txt
CMIS Root > DRC > Melding Openbare Ruimte > 2020 > 12 > 31 > ZAAK-0000001 > Related data > document.txt-gebruiksrechten
CMIS Root > DRC > Melding Openbare Ruimte > 2020 > 12 > 31 > ZAAK-0000001 > Related data > document.txt-oioRelating a document to a BesluitWhen a document is related to a Besluit, there’s a few different scenario’s:The Besluit isrelatedto a Zaak and…The document isnot relatedto a Zaak (and thus the document is in
the temporary folder): The document ismovedto the Zaak folder of
the Zaak that is related to the Besluit.The document isalready relatedto a Zaak: The document iscopiedto the new Zaak folder.The Besluit isnot relatedto a Zaak and…The document isnot relatedto a Zaak: The documentstaysin its
temporary folder.The document isrelatedto a Zaak: The document iscopiedto the
temporary folder.In all cases, the relation of a document to a Besluit is stored as a separate
document (oio) in theRelated datafolder, relative to wherever the new
document is stored.Relating a document to another objectWhen a document is related to any other object, the document is not moved or
copied and stays in its temporary folder.Deleting a Zaak Informatie ObjectWhen a document is related to a zaak, it is located in the zaak folder and has an OIO in the ‘Related Data’
folder. If the ZIO relating the zaak and the document is deleted, the OIO is deleted, and the document
should not remain in the zaak folder. This is done as follows:If the document is NOT a copy (i.e. it’s the original document), it should be moved to the default folder.
If there are related gebruiksrechten, then they should also be moved.If the document IS a copy, then it should be deleted. Related gebruiksrechten should also be deleted.DMS folder structure overviewYou can configure the folders used by the CMIS adapter via the admin interface.
Some folders are templated (indicated with{{ }}) which means their value
depends on the current date or the related Zaak.A complete overview of all default folders and documents are shown below:Zaak folder pathStorage location for documents related to a Zaak.Default:/DRC/{{zaaktype}}/{{year}}/{{month}}/{{day}}/{{zaak }}/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)You can for example change this to:/DRC/{{zaaktype}}/{{zaak }}/to
remove the year/month/day folder structure entirely.Other folder pathStorage location for documents not (yet) related to a Zaak.Default:/DRC/{{year}}/{{month}}/{{day }}/CMIS Root
+-- DRC (cmis:folder)
    +-- [year] (cmis:folder)
        +-- [month] (cmis:folder)
            +-- [day] (cmis:folder)
                +-- [filename] (drc:document)
                +-- Related data (cmis:folder)
                    +-- [filename]-gebruiksrechten (drc:gebruiksrechten)
                    +-- [filename]-oio (drc:oio)Notes on differences between DMSsSQL queries supportThe SQL queries that are not supported in Alfresco can be foundhere. In addition, queries such as:SELECT * FROM drc:document WHERE cmis:parentId = '<folder.objectId>'don’t seem to work.The SQL queries that seem not to be supported in Corsa are:INqueriesIN_FOLDER('<folderobjectId>')ORqueriesReferencesIssuesCodeLicenseCopyright © Dimpact 2019 - 2020Licensed under theEUPL