The CMIS adapter¶
In a default installation of Open Zaak, any documents created through the Documenten API are stored on disk and their metadata is stored in the database. However, it is also possible to store these documents in a Document Management System (DMS) using the CMIS standard.
Instead of storing the documents, the CMIS adapter converts API calls to CMIS requests which are sent to the DMS to create, update and delete documents. This way, the documents are stored in the DMS.
Warning
The CMIS adapter is currently an experimental feature. While we have extensive unit test coverage with Alfresco, we require more “real world” testing before we can label the feature as stable.
Using the CMIS adapter¶
In order to use the CMIS adapter, the setting CMIS_ENABLED
should be set to True
.
This can be done in the .env
file.
Then, the following details need to be configured through the Admin interface of Open Zaak:
The client URL
The client username and password
The name of the main folder in the Document Management System (DMS) where documents are going to be created
These can be configured under Configuratie > CMIS configuration. An example configuration could be:
Client URL:
http://example.com:8888/alfresco/api/-default-/public/cmis/versions/1.1/browser
Client Username:
Admin
Client Password:
SomeSecretPassw0rd
Main folder name:
DRC
Note
Currently only the CMIS 1.1 browser binding is supported. The CMIS 1.0 SOAP binding is under active development and will follow in a later release.
The CMIS mapper¶
Before a CMIS request can be performed, each attribute passed via the Document API has to be mapped to a CMIS property.
The customised document model used in the DMS is defined in a XML file, where all the
properties of the document are specified. An example XML file is provided in
extension/alfresco-zsdms-model.xml
.
The mapping between the Document API attributes and the names used in the XML can be
found in config/cmis_mapper.json
.
The keys are the names of the attributes in the Document API, while the values are the names used in CMIS content model.
If a different custom document model is used, then the mapper file also needs to be
updated. The path to the new mapper file is specified via the setting
CMIS_MAPPER_FILE
, which can be specified in the .env
file.
Content model requirements¶
CMIS content models define a number of properties that are important for the correct functionining of the adapter.
Notably, the defined Object-Type must have the attribute
queryable
set toTRUE
, otherwise errors will pop up when we query for documents using CMIS queries.Additionally, a number of properties on the Document Object must be
queryable
to use them in theWHERE
clauses of the CMIS queries. In particular, this spans the following attributes:bestandsnaam
bronorganisatie
identificatie
informatieobjecttype
titel
link
versie
creatiedatum
begin_registratie
Todo
More properties are marked as ‘index’ in the shipped content model, but it’s unclear if they’re actually used at the moment.
Example CMIS request¶
The example data below shows what data is sent by Open Zaak when a CMIS request is performed to create different objects.
The objects are created with a POST
request to the url of the root folder.
The url of the root folder is obtained by appending /root/
to the client url configured in the
Admin interface of Open Zaak.
For example, if the client url has been set to
http://example.com/alfresco/api/-default-/public/cmis/versions/1.1/browser
,
then the root folder url is
http://example.com/alfresco/api/-default-/public/cmis/versions/1.1/browser/root
.
Within the root folder, all content created by Open Zaak will be in a folder whose name
is specified in the configuration (by default DRC
).
The username and passwords used are those specified in the CMIS configuration section of the Admin interface.
Document objects (EnkelvoudigInformatieObject)
The data below is an example of what is sent from Open Zaak to create a document object according to the default document model.
The first property (objectId
) is the ID of the folder that will contain the new document.
POST http://example.com/alfresco/api/-default-/public/cmis/versions/1.1/browser/root User-Agent: python-requests/2.21.0 Accept-Encoding: gzip, deflate Accept: application/json Connection: keep-alive Content-Length: 1241 Content-Type: x-www-form-urlencoded Authorization: Basic YWRtaW46YWRtaW4= objectId=02bc165a-4f55-4d65-818a-e0b9d4ace38f&cmisaction=createDocument&propertyId%5B0%5D=cmis%3Aname&propertyValue%5B0%5D=some+titel-HWVLOF&propertyId%5B1%5D=cmis%3AobjectTypeId&propertyValue%5B1%5D=D%3Adrc%3Adocument&propertyId%5B2%5D=drc%3Adocument__identificatie&propertyValue%5B2%5D=6cd3cf4a-320d-4167-a192-fb33a34184ac&propertyId%5B3%5D=drc%3Adocument__bronorganisatie&propertyValue%5B3%5D=275318941&propertyId%5B4%5D=drc%3Adocument__creatiedatum&propertyValue%5B4%5D=2018-06-27T00%3A00%3A00.000Z&propertyId%5B5%5D=drc%3Adocument__titel&propertyValue%5B5%5D=some+titel&propertyId%5B6%5D=drc%3Adocument__auteur&propertyValue%5B6%5D=some+auteur&propertyId%5B7%5D=drc%3Adocument__formaat&propertyValue%5B7%5D=some+formaat&propertyId%5B8%5D=drc%3Adocument__taal&propertyValue%5B8%5D=nld&propertyId%5B9%5D=drc%3Adocument__informatieobjecttype&propertyValue%5B9%5D=http%3A%2F%2Ftestserver%2Fcatalogi%2Fapi%2Fv1%2Finformatieobjecttypen%2F4123f2e5-8201-46a9-9030-3d629ca5baeb&propertyId%5B10%5D=drc%3Adocument__vertrouwelijkaanduiding&propertyValue%5B10%5D=openbaar&propertyId%5B11%5D=drc%3Adocument__beschrijving&propertyValue%5B11%5D=old&propertyId%5B12%5D=drc%3Adocument__begin_registratie&propertyValue%5B12%5D=2020-06-23T13%3A02%3A11.000Z
The data present in the body is also shown below in a more readable format:
{ 'objectId': '5353495a-3441-42d5-bf52-f9388dc0eef8', 'cmisaction': 'createDocument', 'propertyId[0]': 'cmis:name', 'propertyValue[0]': 'some titel-4IP28I', 'propertyId[1]': 'cmis:objectTypeId', 'propertyValue[1]': 'D:drc:document', 'propertyId[2]': 'drc:document__identificatie', 'propertyValue[2]': UUID('e6b0499e-c9ee-4473-b4fc-7f942564b2dc'), 'propertyId[3]': 'drc:document__bronorganisatie', 'propertyValue[3]': '768254103', 'propertyId[4]': 'drc:document__creatiedatum', 'propertyValue[4]': '2018-06-27T00:00:00.000Z', 'propertyId[5]': 'drc:document__titel', 'propertyValue[5]': 'some titel', 'propertyId[6]': 'drc:document__auteur', 'propertyValue[6]': 'some auteur', 'propertyId[7]': 'drc:document__formaat', 'propertyValue[7]': 'some formaat', 'propertyId[8]': 'drc:document__taal', 'propertyValue[8]': 'nld', 'propertyId[9]': 'drc:document__informatieobjecttype', 'propertyValue[9]': 'http://testserver/catalogi/api/v1/informatieobjecttypen/5b020631-8fd1-4f88-a237-b605f715e168', 'propertyId[10]': 'drc:document__vertrouwelijkaanduiding', 'propertyValue[10]': 'openbaar', 'propertyId[11]': 'drc:document__beschrijving', 'propertyValue[11]': 'old', 'propertyId[12]': 'drc:document__begin_registratie', 'propertyValue[12]': '2020-06-22T11:26:44.000Z', }
Usage rights objects (Gebruiksrechten)
The data below is an example of what is sent from Open Zaak to create a usage right object.
POST http://example.com/alfresco/api/-default-/public/cmis/versions/1.1/browser/root User-Agent: python-requests/2.21.0 Accept-Encoding: gzip, deflate Accept: application/json Connection: keep-alive Content-Length: 706 Content-Type: x-www-form-urlencoded Authorization: Basic YWRtaW46YWRtaW4= objectId=a6b372f2-c009-48ca-a4f9-52fd6ae5cba1&cmisaction=createDocument&propertyId%5B0%5D=cmis%3Aname&propertyValue%5B0%5D=4WN8N9&propertyId%5B1%5D=cmis%3AobjectTypeId&propertyValue%5B1%5D=D%3Adrc%3Agebruiksrechten&propertyId%5B2%5D=drc%3Agebruiksrechten__startdatum&propertyValue%5B2%5D=2020-06-23T13%3A01%3A49.000Z&propertyId%5B3%5D=drc%3Agebruiksrechten__omschrijving_voorwaarden&propertyValue%5B3%5D=Training+according+value+somebody+analysis.+Practice+special+organization+plant.+Media+treatment+protect+others+should+billion.&propertyId%5B4%5D=drc%3Agebruiksrechten__informatieobject&propertyValue%5B4%5D=http%3A%2F%2Ftestserver%2Fdocumenten%2Fapi%2Fv1%2Fenkelvoudiginformatieobjecten%2F9ba4ed73-7783-48ce-bcc0-393c1e5ef01e
The data passed in the body is also shown below in a more readable format:
{ 'objectId': '0e921c3e-dbbb-47e7-bb57-81b5fc268daa', 'cmisaction': 'createDocument', 'propertyId[0]': 'cmis:name', 'propertyValue[0]': 'TOX6GI', 'propertyId[1]': 'cmis:objectTypeId', 'propertyValue[1]': 'D:drc:gebruiksrechten', 'propertyId[2]': 'drc:gebruiksrechten__startdatum', 'propertyValue[2]': '2020-06-23T08:38:03.000Z', 'propertyId[3]': 'drc:gebruiksrechten__omschrijving_voorwaarden', 'propertyValue[3]': 'A sample description', 'propertyId[4]': 'drc:gebruiksrechten__informatieobject', 'propertyValue[4]': 'http://testserver/documenten/api/v1/enkelvoudiginformatieobjecten/5bd261cf-9fa0-4289-b5fc-a19f363b0f74' }