Documenten API CMIS adapter

Version:	1.9.1
Source:	https://github.com/open-zaak/cmis-adapter
Keywords:	CMIS, Documenten API, VNG, Common Ground
PythonVersion:	3.10

A CMIS backend-connector for the Documenten API.

Developed by Maykin 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.

Introduction

The 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 by Open Zaak to use a DMS as backend for the Documenten API rather then using its own backend.

Features

Both CMIS 1.0 and CMIS 1.1 are supported but not for all bindings. Below is a list of supported bindings for each CMIS version.

	CMIS 1.0	CMIS 1.1
Web Services binding	Supported	Untested
AtomPub binding	Untested	Untested
Browser binding	N/A	Supported

For 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 platform using CMIS 1.0 Web Services binding (Thanks to BCT)
Alfresco Enterprise 5.2.3 using CMIS 1.1 Browser binding (Thanks to Contezza)
Alfresco CE 6.1.2-ga (Used for CI)

Installation

NOTE: If you are using Open Zaak 1.3.1 or above, the CMIS-adapter is already included and does not require separate installation.

Requirements

Python 3.10 or above
setuptools 30.3.0 or above
Django 3.2 or newer

Install

Install the library in your Django project:

$ pip install drc-cmis

Add to INSTALLED_APPS in your Django settings.py:

INSTALLED_APPS = [
    ...
    "drc_cmis",
    ...
]

Create a mapping file to match Documenten API attributes to custom properties in your DMS model. See Mapping configuration.
In your settings.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.json

Login to the Django admin as superuser and configure the CMIS backend.

Mapping configuration

There 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"
  }
}

The DOCUMENT_MAP describes the mapping for the EnkelvoudigInformatieObject resource in the Documenten API. In this snippet, only the EnkelvoudigInformatieObject.titel attribute is mapped to a custom CMIS property called drc: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:Envelope xmlmsg: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:propertyString propertyDefinitionId="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 in test_app/cmis_mapper.json (cmis_mapper.json). The related DMS content model, that has the definitions for all these CMIS properties, for Alfresco (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.

Mappings

The 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.

Document

The document itself, its content and meta data.

Documenten API resource	`EnkelvoudigInformatieObject`
CMIS objecttype *	`drc:document`
CMIS basetype	`cmis:document`
CMIS-mapper object	`DOCUMENT_MAP`