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.
The CMIS adapter converts API calls to the Documenten API in Open Zaak, to CMIS calls which are sent to the DMS to retrieve, create, update and delete documents. This way, the documents are stored in, or retrieved from, the DMS and not in or from Open Zaak.
CMIS support¶
CMIS 1.0 and CMIS 1.1 have various CMIS protocol bindings that can be used. Although according to the CMIS specification repositories must implement Web Services and AtomPub bindings, some DMS implementation only support one and/or recommend the newer Browser bindings.
CMIS 1.0 |
CMIS 1.1 |
|
---|---|---|
Web Services binding |
Supported |
Untested |
AtomPub binding |
Untested |
Untested |
Browser binding |
N/A |
Supported |
CMIS support is built in Open Zaak using the CMIS adapter library. For an up-to-date list of supported CMIS versions and libraries, please see this project’s documentation.
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¶
Create a mapping file to match Documenten API attributes to custom properties in your DMS model. The format is explained in the CMIS adapter library Mapping configuration documentation.
You can use our default CMIS mapping for inspiration or just use these as defaults.
Make sure the content model is loaded in your DMS and matches the CMIS mapping described in step 1. It’s important that all attributes are present. Some need to be indexed to allow the proper CMIS queries to be executed.
You can use our Alfresco model that matches the default mapping. The detailed explanation is described in the CMIS adapter library DMS Content model configuration documentation.
Enable the CMIS adapter. In the environment (or
.env
file), add or update the variableCMIS_ENABLED
andCMIS_MAPPER_FILE
:# Enables the CMIS-backend and the Open Zaak 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 model. CMIS_MAPPER_FILE = /path/to/cmis_mapper.json
Optional: enable URL mapping. In DMSs such as Corsa, queryable text fields can only be up to 100 characters long. However, documents in the Document API have URLs associated with it that are longer. The URL mapper feature shrinks the URLs so that they fit in queryable text fields.
In the environment (or
.env
file), add or update the variableCMIS_URL_MAPPING_ENABLED
:# Enables URL mapping in the CMIS-backend so that the URLs saved in # the DMS are shorter than 100 chars. CMIS_URL_MAPPING_ENABLED = True
You will need to restart Open Zaak for these changes to take effect.
Login to the Open Zaak admin interface (
/admin/
) as superuser.Navigate to Configuratie > CMIS configuration and fill in all relevant fields.
If the URL mapping feature was enabled (point 4. above), then the mappings between the original and short version of a URL need to be defined. In the section URL MAPPINGS, fill in the field LONG PATTERN with the original URL (in format
https://<domain>[/subpath]
) and the SHORT PATTERN with the URL with shortened domain and subpath (in formathttps://<short domain>
). The short pattern field can be at most 15 characters. The scheme (http or https) should be the same for both the long and short pattern.Warning
Once a mapping has been defined, it cannot be updated or deleted.
Save the configuration with Opslaan en opnieuw bewerken.
You will see the CMIS connection status shows OK if everything went well.
When using the CMIS-adapter, sometimes a Zaak, a Zaaktype or a Besluit need to be retrieved from the APIs. This happens for example when a Zaak folder is created, since the description of the Zaak is used as part of the folder name.
For this reason, the CMIS-adapter needs to be given access to the various APIs. These are the steps to configure it:
Go to API Autorisaties > Applicaties and click on Applicatie toevoegen.
Fill out the form:
Client ID: For example:
cmis-adapter
Secret: Some random string, for example:
Tl8@04&O4gXTtB
. You will need this later on!
Click Opslaan en opnieuw bewerken.
Click Beheer Autorisaties.
Under Component check
Zaken API
, under Selecteer scopes checkzaken.lezen
, under Voor welke typen geldt dit? checkAlle huidige en toekomsitge ZAAKTYPEN
and under Tot en met welke vertrouwelijkheidaanduiding? checkZeer geheim
.Click on Nog Autorisaties toevoegen and under Component check
Catalogi API
and under Selecteer scopes checkcatalogi.lezen
.Click on Nog Autorisaties toevoegen and check under Component
Besluiten API
, under Selecteer scopes checkbesluiten.lezen
and under Voor welke typen geldt dit? checkAlle huidige en toekomsitge BESLUITTYPEN
.Click on Nog Autorisaties toevoegen and under Component check
Documenten API
, under Selecteer scopes checkdocumenten.lezen
, under Voor welke typen geldt dit? checkAlle huidige en toekomsitge INFORMATIEOBJECTTYPEN
and under Tot en met welke vertrouwelijkheidaanduiding? checkZeer geheim
.Click on Opslaan to save.
Then, the services need to be configured. First, configure the Zaken API as follows:
Go to API Autorisaties > Services and click on Service Toevoegen.
Fill out the form:
The API type should be
ZRC (Zaken)
.The API root could be
http://example.com/zaken/api/v1/
.The client ID and the secret should be those configured in the API Autorisaties > Applicaties. Following the previous example, they would be
cmis-adapter
andTl8@04&O4gXTtB
respectively.
Click Opslaan to save.
Repeat the procedure above for the Zaaktypen API, Besluiten API and Documenten API. Make sure to use the proper Type and API root. The credentials should all be the same.
Additional notes on creating documents¶
Depending on whether the CMIS adapter is enabled, there is a difference in behaviour for creating documents with an empty identification field.
If the CMIS adapter is disabled, the procedure to automatically generate the identification is as follows:
The prefix
DOCUMENT
is combined with the year of creation of the document. For example:DOCUMENT-2020-
All existing documents are searched to find all those with an identification field that starts with the generated prefix. These would for example be
DOCUMENT-2020-0000000001
,DOCUMENT-2020-0000000002
,DOCUMENT-2020-0000000003
.The new document is given an identification field with a unique number that is different from those of all the other documents. This would for example be
DOCUMENT-2020-0000000004
.
The search done in point 2. requires an SQL LIKE clause, which is not supported by all DMSs. For this reason, if the CMIS adapter is in use, the automatically generated identification field will be equal to the document UUID.