===========================
Documenten API CMIS adapter
===========================
:Version: 1.9.0
:Source: https://github.com/open-zaak/cmis-adapter
:Keywords: CMIS, Documenten API, VNG, Common Ground
:PythonVersion: 3.7
|build-status| |coverage| |linting| |black| |python-versions| |django-versions| |pypi-version|
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.
.. _`Open Zaak`: https://github.com/open-zaak/open-zaak/
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`: https://docs.oasis-open.org/cmis/CMIS/v1.0/cmis-spec-v1.0.html
.. _`CMIS 1.1`: https://docs.oasis-open.org/cmis/CMIS/v1.1/CMIS-v1.1.html
+----------------------+-----------+-----------+
| | 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)
.. _`Corsa platform`: https://www.bctsoftware.com/corsa/
.. _`BCT`: https://www.bctsoftware.com/
.. _`Contezza`: https://contezza.nl/
.. _`Alfresco CE 6.1.2-ga`: https://hub.docker.com/layers/alfresco/alfresco-content-repository-community/6.1.2-ga/images/sha256-6edaf25aded1b16991f06be7754a7030c9d67429353e39ce1da3fd307a5f2e6f?context=explore
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.7 or above
* setuptools 30.3.0 or above
* Django 3.2 or newer
Install
-------
1. Install the library in your Django project:
.. code-block:: bash
$ pip install drc-cmis
2. Add to ``INSTALLED_APPS`` in your Django ``settings.py``:
.. code-block:: python
INSTALLED_APPS = [
...
"drc_cmis",
...
]
3. Create a mapping file to match Documenten API attributes to custom
properties in your DMS model. See `Mapping configuration`_.
4. In your ``settings.py``, add these settings to enable it:
.. code-block:: python
# 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
5. 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:
.. code-block:: json
{
"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).
.. code-block:: xml
<?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.
.. _`cmis_mapper.json`: https://github.com/open-zaak/cmis-adapter/blob/master/test_app/cmis_mapper.json
.. _`alfreso-zsdms-model.xml`: https://github.com/open-zaak/cmis-adapter/blob/master/alfresco/extension/alfreso-zsdms-model.xml
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`` |
+-------------------------+---------------------------------+
The mapping between API-attributes and CMIS properties can be found in the `cmis_mapper.json`_.
**Gebruiksrechten**
Usage rights. These rights don't need to be enforced by the DMS but are stored
for use outside the DMS.
+-------------------------+---------------------------------+
| Documenten API resource | ``Gebruiksrechten`` |
+-------------------------+---------------------------------+
| CMIS objecttype \* | ``drc:gebruiksrechten`` |
+-------------------------+---------------------------------+
| CMIS basetype | ``cmis:document`` |
+-------------------------+---------------------------------+
| CMIS-mapper object | ``GEBRUIKSRECHTEN_MAP`` |
+-------------------------+---------------------------------+
The mapping between API-attributes and CMIS properties can be found in the `cmis_mapper.json`_.
**ObjectInformatieObject**
Relation between a document and another object, like a Zaak, Besluit or
something else.
+-------------------------+---------------------------------+
| Documenten API resource | ``ObjectInformatieObject`` |
+-------------------------+---------------------------------+
| CMIS objecttype \* | ``drc:oio`` |
+-------------------------+---------------------------------+
| CMIS basetype | ``cmis:document`` |
+-------------------------+---------------------------------+
| CMIS-mapper object | ``OBJECTINFORMATIEOBJECT_MAP`` |
+-------------------------+---------------------------------+
The mapping between API-attributes and CMIS properties can be found in the `cmis_mapper.json`_.
**Zaaktype folder**
Contains all Zaken from this Zaaktype and has itself some meta data about the
Zaaktype. API-attributes are from the `Catalogi API`_ ``Zaaktype``-resource.
.. _`Catalogi API`: https://vng-realisatie.github.io/gemma-zaken/standaard/catalogi/index
+-------------------------+---------------------------------+
| Catalogi API resource | ``Zaaktype`` |
+-------------------------+---------------------------------+
| CMIS objecttype \* | ``drc:zaaktypefolder`` |
+-------------------------+---------------------------------+
| CMIS basetype | ``cmis:folder`` |
+-------------------------+---------------------------------+
| CMIS-mapper object | ``ZAAKTYPE_MAP`` |
+-------------------------+---------------------------------+
The mapping between API-attributes and CMIS properties can be found in the `cmis_mapper.json`_.
**Zaak folder**
Contains all Zaak-related documents and has itself some meta data about the
Zaak. API-attributes are from the `Zaken API`_ ``Zaak``-resource.
.. _`Zaken API`: https://vng-realisatie.github.io/gemma-zaken/standaard/zaken/index
+-------------------------+---------------------------------+
| Zaken API resource | ``Zaak`` |
+-------------------------+---------------------------------+
| CMIS objecttype \* | ``drc:zaakfolder`` |
+-------------------------+---------------------------------+
| CMIS basetype | ``cmis:folder`` |
+-------------------------+---------------------------------+
| CMIS-mapper object | ``ZAAK_MAP`` |
+-------------------------+---------------------------------+
The mapping between API-attributes and CMIS properties can be found in the `cmis_mapper.json`_.
\* CMIS objecttype: ``cmis:objectTypeId``
DMS Content model configuration
-------------------------------
The CMIS mapper configuration must match the content model in the DMS. Each
property, like ``drc:document__titel`` in the example above, must be defined
in the content model.
The example shown in ``/alfresco/extension/alfreso-zsdms-model.xml``
indicates 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 structure
--------------------
Open Zaak uses a folder structure in the DMS similar to the
`Zaak- en Documentservices 1.2`_. However, due to way the Documenten API works
there are differences.
.. _`Zaak- en Documentservices 1.2`: https://www.gemmaonline.nl/index.php/Zaak-_en_Documentservices
**Creating a document**
When a document is created via the Documenten API, the document is placed in a
temporary folder. By default this is:
.. code-block::
CMIS Root
+-- DRC (cmis:folder)
+-- [year] (cmis:folder)
+-- [month] (cmis:folder)
+-- [day] (cmis:folder)
+-- [filename] (drc:document)
For example:
.. code-block::
CMIS Root > DRC > 2020 > 12 > 31 > document.txt
If nothing else happens, this document will remain here.
**Creating gebruiksrechten**
A document can have Gebruiksrechten. These are stored as a separate document
(``gebruiksrechten``) in a folder called ``Related data``. This folder is
always in the same folder as the document itself and is of type ``cmis:folder``.
The Gebruiksrechten will always be moved or copied along with the document.
For example:
.. code-block::
CMIS Root > DRC > 2020 > 12 > 31 > document.txt
CMIS Root > DRC > 2020 > 12 > 31 > Related data > document.txt-gebruiksrechten
**Relating a document to a Zaak**
Relating a document to a Zaak (by creating an ``ObjectInformatieObject``
instance in the Documenten API) will cause the document and its Gebruiksrechten
if it exists, to be **moved** or **copied** to the zaak folder.
.. code-block::
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 is **moved** when the document was **not related** to a Zaak before
(and thus it was in the temporary folder). The document is **copied** to the
new zaak folder when the document was **already related** to 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
the ``Related data`` folder.
For example:
.. code-block::
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-oio
**Relating a document to a Besluit**
When a document is related to a Besluit, there's a few different scenario's:
1. The Besluit is **related** to a Zaak and...
1. The document is **not related** to a Zaak (and thus the document is in
the temporary folder): The document is **moved** to the Zaak folder of
the Zaak that is related to the Besluit.
2. The document is **already related** to a Zaak: The document is **copied**
to the new Zaak folder.
2. The Besluit is **not related** to a Zaak and...
1. The document is **not related** to a Zaak: The document **stays** in its
temporary folder.
2. The document is **related** to a Zaak: The document is **copied** to the
temporary folder.
In all cases, the relation of a document to a Besluit is stored as a separate
document (``oio``) in the ``Related data`` folder, relative to wherever the new
document is stored.
**Relating a document to another object**
When 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 Object**
When 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:
1. 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.
2. If the document IS a copy, then it should be deleted. Related gebruiksrechten should also be deleted.
DMS folder structure overview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You 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 path**
Storage location for documents related to a Zaak.
Default: ``/DRC/{{ zaaktype }}/{{ year }}/{{ month }}/{{ day }}/{{ zaak }}/``
.. code-block::
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 path**
Storage location for documents not (yet) related to a Zaak.
Default: ``/DRC/{{ year }}/{{ month }}/{{ day }}/``
.. code-block::
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 DMSs
=================================
**SQL queries support**
The SQL queries that are not supported in Alfresco can be found `here`_. 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:
* ``IN`` queries
* ``IN_FOLDER('<folder objectId>')``
* ``OR`` queries
.. _`here`: https://docs.alfresco.com/insight-engine/latest/using/sql/#unsupported-sql-commands
References
==========
* `Issues <https://github.com/open-zaak/open-zaak/issues>`_
* `Code <https://github.com/open-zaak/cmis-adapter>`_
License
=======
Copyright © Dimpact 2019 - 2020
Licensed under the EUPL_
.. _EUPL: LICENCE.md
.. _`Maykin Media B.V.`: https://www.maykinmedia.nl
.. _`Alfresco`: https://www.alfresco.com/ecm-software/alfresco-community-editions
.. |build-status| image:: https://github.com/open-zaak/cmis-adapter/workflows/Run%20CI/badge.svg
:target: https://github.com/open-zaak/cmis-adapter/actions?query=workflow%3A%22Run+CI%22
:alt: Run CI
.. |linting| image:: https://github.com/open-zaak/cmis-adapter/workflows/Code%20quality%20checks/badge.svg
:target: https://github.com/open-zaak/cmis-adapter/actions?query=workflow%3A%22Code+quality+checks%22
:alt: Code linting
.. |coverage| image:: https://codecov.io/gh/open-zaak/cmis-adapter/branch/master/graph/badge.svg
:target: https://codecov.io/gh/open-zaak/cmis-adapter
:alt: Coverage status
.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
.. |python-versions| image:: https://img.shields.io/pypi/pyversions/drc-cmis.svg
.. |django-versions| image:: https://img.shields.io/pypi/djversions/drc-cmis.svg
.. |pypi-version| image:: https://img.shields.io/pypi/v/drc-cmis.svg
:target: https://pypi.org/project/drc-cmis/
.. _Documenten API: https://vng-realisatie.github.io/gemma-zaken/standaard/documenten/index
Raw data
{
"_id": null,
"home_page": "https://github.com/open-zaak/cmis-adapter",
"name": "drc-cmis",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "CMIS, Documenten API, VNG, Common Ground",
"author": "Maykin Media, Joeri Bekker, Jorik Kraaikamp, Sergei Maertens, Silvia Amabilino",
"author_email": "support@maykinmedia.nl",
"download_url": "https://files.pythonhosted.org/packages/07/95/0ac2e1dacabb49fa0b4b88e081c97d11a44363e7c856e60b058e24fe51c9/drc-cmis-1.9.0.tar.gz",
"platform": null,
"description": "===========================\nDocumenten API CMIS adapter\n===========================\n\n:Version: 1.9.0\n:Source: https://github.com/open-zaak/cmis-adapter\n:Keywords: CMIS, Documenten API, VNG, Common Ground\n:PythonVersion: 3.7\n\n|build-status| |coverage| |linting| |black| |python-versions| |django-versions| |pypi-version|\n\nA CMIS backend-connector for the `Documenten API`_.\n\nDeveloped by `Maykin Media B.V.`_ commissioned by the municipality of Utrecht\nwith support of the municipality of S\u00fadwest-Frysl\u00e2n and the Open Zaak project\nteam.\n\n\nIntroduction\n============\n\nThe Documenten API CMIS adapter allows Django implementations of the Documenten\nAPI to easily connect to a CMIS-compatible Document Management System (DMS).\nMost notably it's used by `Open Zaak`_ to use a DMS as backend for the\nDocumenten API rather then using its own backend.\n\n.. _`Open Zaak`: https://github.com/open-zaak/open-zaak/\n\nFeatures\n--------\n\nBoth `CMIS 1.0`_ and `CMIS 1.1`_ are supported but not for all bindings. Below\nis a list of supported bindings for each CMIS version.\n\n.. _`CMIS 1.0`: https://docs.oasis-open.org/cmis/CMIS/v1.0/cmis-spec-v1.0.html\n.. _`CMIS 1.1`: https://docs.oasis-open.org/cmis/CMIS/v1.1/CMIS-v1.1.html\n\n+----------------------+-----------+-----------+\n| | CMIS 1.0 | CMIS 1.1 |\n+======================+===========+===========+\n| Web Services binding | Supported | Untested |\n+----------------------+-----------+-----------+\n| AtomPub binding | Untested | Untested |\n+----------------------+-----------+-----------+\n| Browser binding | N/A | Supported |\n+----------------------+-----------+-----------+\n\nFor the supported bindings, the following features are implemented:\n\n* Retrieve from and store documents in a CMIS-compatible DMS.\n* Supports reading and writing of documents.\n* Supports checking out/in of documents.\n* Supports custom data-model for storing additional meta data.\n\nTested against:\n\n* `Corsa platform`_ using CMIS 1.0 Web Services binding (Thanks to `BCT`_)\n* `Alfresco`_ Enterprise 5.2.3 using CMIS 1.1 Browser binding (Thanks to\n `Contezza`_)\n* `Alfresco CE 6.1.2-ga`_ (Used for CI)\n\n.. _`Corsa platform`: https://www.bctsoftware.com/corsa/\n.. _`BCT`: https://www.bctsoftware.com/\n.. _`Contezza`: https://contezza.nl/\n.. _`Alfresco CE 6.1.2-ga`: https://hub.docker.com/layers/alfresco/alfresco-content-repository-community/6.1.2-ga/images/sha256-6edaf25aded1b16991f06be7754a7030c9d67429353e39ce1da3fd307a5f2e6f?context=explore\n\n\nInstallation\n============\n\n**NOTE: If you are using Open Zaak 1.3.1 or above, the CMIS-adapter is already\nincluded and does not require separate installation.**\n\nRequirements\n------------\n\n* Python 3.7 or above\n* setuptools 30.3.0 or above\n* Django 3.2 or newer\n\nInstall\n-------\n\n1. Install the library in your Django project:\n\n.. code-block:: bash\n\n $ pip install drc-cmis\n\n2. Add to ``INSTALLED_APPS`` in your Django ``settings.py``:\n\n.. code-block:: python\n\n INSTALLED_APPS = [\n ...\n \"drc_cmis\",\n ...\n ]\n\n3. Create a mapping file to match Documenten API attributes to custom\n properties in your DMS model. See `Mapping configuration`_.\n\n4. In your ``settings.py``, add these settings to enable it:\n\n.. code-block:: python\n\n # Enables the CMIS-backend and the Django admin interface for configuring\n # the DMS settings.\n CMIS_ENABLED = True\n\n # Absolute path to the mapping of Documenten API attributes to (custom)\n # properties in your DMS content model.\n CMIS_MAPPER_FILE = /path/to/cmis_mapper.json\n\n5. Login to the Django admin as superuser and configure the CMIS backend.\n\nMapping configuration\n=====================\n\nThere are 2 important concepts:\n\n* Content model - The DMS configuration to store (custom) properties on folders\n and documents. These properties are called CMIS properties.\n* CMIS-mapper - a JSON-file containing the translation from Documenten API\n attributes to CMIS properties.\n\nMapping the Documenten API attributes to (custom) CMIS properties in the DMS\ncontent model should be done with great care. When the DMS stores these\nproperties, the Documenten API relies on their existance to create proper responses.\n\nBelow is a snippet of the CMIS-mapper:\n\n.. code-block:: json\n\n {\n \"DOCUMENT_MAP\": {\n \"titel\": \"drc:document__titel\"\n }\n }\n\nThe ``DOCUMENT_MAP`` describes the mapping for the\n``EnkelvoudigInformatieObject`` resource in the Documenten API. In this\nsnippet, only the ``EnkelvoudigInformatieObject.titel`` attribute is mapped to\na custom CMIS property called ``drc:document_titel``.\n\nCommunication between the Documenten API using the CMIS-adapter, is done via\nCMIS. Therefore, when creating a document via the Documenten API, the\nattributes are translated to CMIS properties as shown below (note that this is\na stripped down request example).\n\n.. code-block:: xml\n\n <?xml version=\"1.0\"?>\n <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/\">\n <soapenv:Header />\n <soapenv:Body>\n <msg:createDocument>\n <msg:repositoryId>d6a10501-ef36-41e1-9aae-547154f57838</msg:repositoryId>\n <msg:properties>\n <core:propertyString propertyDefinitionId=\"drc:document__titel\">\n <core:value>example.txt</core:value>\n </msg:properties>\n <msg:folderId>workspace://SpacesStore/7c6c7c86-fd63-4eec-bcf8-ffb59f6f6b90</msg:folderId>\n </msg:createDocument>\n </soapenv:Body>\n </soapenv:Envelope>\n\nAn example of the mapping configuration, with all possible Documenten API\nresources and attributes is shown in ``test_app/cmis_mapper.json``\n(`cmis_mapper.json`_). The related DMS content model, that has the definitions\nfor all these CMIS properties, for `Alfresco`_ (an open source DMS) is in\n``/alfresco/extension/alfreso-zsdms-model.xml`` (`alfreso-zsdms-model.xml`_).\nBoth the mapping and the model should be aligned.\n\n.. _`cmis_mapper.json`: https://github.com/open-zaak/cmis-adapter/blob/master/test_app/cmis_mapper.json\n.. _`alfreso-zsdms-model.xml`: https://github.com/open-zaak/cmis-adapter/blob/master/alfresco/extension/alfreso-zsdms-model.xml\n\nMappings\n--------\n\nThe content model and the CMIS-mapper configurations need to be aligned. For\neach object, the API resource, the CMIS objecttype, CMIS basetype and the\n(configuratble) CMIS-mapper object is described.\n\n**Document**\n\nThe document itself, its content and meta data.\n\n+-------------------------+---------------------------------+\n| Documenten API resource | ``EnkelvoudigInformatieObject`` |\n+-------------------------+---------------------------------+\n| CMIS objecttype \\* | ``drc:document`` |\n+-------------------------+---------------------------------+\n| CMIS basetype | ``cmis:document`` |\n+-------------------------+---------------------------------+\n| CMIS-mapper object | ``DOCUMENT_MAP`` |\n+-------------------------+---------------------------------+\n\nThe mapping between API-attributes and CMIS properties can be found in the `cmis_mapper.json`_.\n\n**Gebruiksrechten**\n\nUsage rights. These rights don't need to be enforced by the DMS but are stored\nfor use outside the DMS.\n\n+-------------------------+---------------------------------+\n| Documenten API resource | ``Gebruiksrechten`` |\n+-------------------------+---------------------------------+\n| CMIS objecttype \\* | ``drc:gebruiksrechten`` |\n+-------------------------+---------------------------------+\n| CMIS basetype | ``cmis:document`` |\n+-------------------------+---------------------------------+\n| CMIS-mapper object | ``GEBRUIKSRECHTEN_MAP`` |\n+-------------------------+---------------------------------+\n\nThe mapping between API-attributes and CMIS properties can be found in the `cmis_mapper.json`_.\n\n**ObjectInformatieObject**\n\nRelation between a document and another object, like a Zaak, Besluit or\nsomething else.\n\n+-------------------------+---------------------------------+\n| Documenten API resource | ``ObjectInformatieObject`` |\n+-------------------------+---------------------------------+\n| CMIS objecttype \\* | ``drc:oio`` |\n+-------------------------+---------------------------------+\n| CMIS basetype | ``cmis:document`` |\n+-------------------------+---------------------------------+\n| CMIS-mapper object | ``OBJECTINFORMATIEOBJECT_MAP`` |\n+-------------------------+---------------------------------+\n\nThe mapping between API-attributes and CMIS properties can be found in the `cmis_mapper.json`_.\n\n**Zaaktype folder**\n\nContains all Zaken from this Zaaktype and has itself some meta data about the\nZaaktype. API-attributes are from the `Catalogi API`_ ``Zaaktype``-resource.\n\n.. _`Catalogi API`: https://vng-realisatie.github.io/gemma-zaken/standaard/catalogi/index\n\n+-------------------------+---------------------------------+\n| Catalogi API resource | ``Zaaktype`` |\n+-------------------------+---------------------------------+\n| CMIS objecttype \\* | ``drc:zaaktypefolder`` |\n+-------------------------+---------------------------------+\n| CMIS basetype | ``cmis:folder`` |\n+-------------------------+---------------------------------+\n| CMIS-mapper object | ``ZAAKTYPE_MAP`` |\n+-------------------------+---------------------------------+\n\nThe mapping between API-attributes and CMIS properties can be found in the `cmis_mapper.json`_.\n\n**Zaak folder**\n\nContains all Zaak-related documents and has itself some meta data about the\nZaak. API-attributes are from the `Zaken API`_ ``Zaak``-resource.\n\n.. _`Zaken API`: https://vng-realisatie.github.io/gemma-zaken/standaard/zaken/index\n\n+-------------------------+---------------------------------+\n| Zaken API resource | ``Zaak`` |\n+-------------------------+---------------------------------+\n| CMIS objecttype \\* | ``drc:zaakfolder`` |\n+-------------------------+---------------------------------+\n| CMIS basetype | ``cmis:folder`` |\n+-------------------------+---------------------------------+\n| CMIS-mapper object | ``ZAAK_MAP`` |\n+-------------------------+---------------------------------+\n\nThe mapping between API-attributes and CMIS properties can be found in the `cmis_mapper.json`_.\n\n\\* CMIS objecttype: ``cmis:objectTypeId``\n\nDMS Content model configuration\n-------------------------------\n\nThe CMIS mapper configuration must match the content model in the DMS. Each\nproperty, like ``drc:document__titel`` in the example above, must be defined\nin the content model.\n\nThe example shown in ``/alfresco/extension/alfreso-zsdms-model.xml``\nindicates all attributes, types and whether the property is indexed (queryable)\nor not. If these attributes are incorrectly configured, the Documenten API\nmight not work correctly.\n\nDMS folder structure\n--------------------\n\nOpen Zaak uses a folder structure in the DMS similar to the\n`Zaak- en Documentservices 1.2`_. However, due to way the Documenten API works\nthere are differences.\n\n.. _`Zaak- en Documentservices 1.2`: https://www.gemmaonline.nl/index.php/Zaak-_en_Documentservices\n\n**Creating a document**\n\nWhen a document is created via the Documenten API, the document is placed in a\ntemporary folder. By default this is:\n\n.. code-block::\n\n CMIS Root\n +-- DRC (cmis:folder)\n +-- [year] (cmis:folder)\n +-- [month] (cmis:folder)\n +-- [day] (cmis:folder)\n +-- [filename] (drc:document)\n\nFor example:\n\n.. code-block::\n\n CMIS Root > DRC > 2020 > 12 > 31 > document.txt\n\nIf nothing else happens, this document will remain here.\n\n**Creating gebruiksrechten**\n\nA document can have Gebruiksrechten. These are stored as a separate document\n(``gebruiksrechten``) in a folder called ``Related data``. This folder is\nalways in the same folder as the document itself and is of type ``cmis:folder``.\n\nThe Gebruiksrechten will always be moved or copied along with the document.\n\nFor example:\n\n.. code-block::\n\n CMIS Root > DRC > 2020 > 12 > 31 > document.txt\n CMIS Root > DRC > 2020 > 12 > 31 > Related data > document.txt-gebruiksrechten\n\n**Relating a document to a Zaak**\n\nRelating a document to a Zaak (by creating an ``ObjectInformatieObject``\ninstance in the Documenten API) will cause the document and its Gebruiksrechten\nif it exists, to be **moved** or **copied** to the zaak folder.\n\n.. code-block::\n\n CMIS Root\n +-- DRC (cmis:folder)\n +-- [zaaktype-folder] (drc:zaaktypefolder)\n +-- [year] (cmis:folder)\n +-- [month] (cmis:folder)\n +-- [day] (cmis:folder)\n +-- [zaak-folder] (drc:zaakfolder)\n +-- [filename] (drc:document)\n +-- Related data (cmis:folder)\n +-- [filename]-gebruiksrechten (drc:gebruiksrechten)\n +-- [filename]-oio (drc:oio)\n\nA document is **moved** when the document was **not related** to a Zaak before\n(and thus it was in the temporary folder). The document is **copied** to the\nnew zaak folder when the document was **already related** to a Zaak.\n\nThe relation of a document to a Zaak is implicitly described by its path. In\naddition however, this relation is stored as a separate document (``oio``) in\nthe ``Related data`` folder.\n\nFor example:\n\n.. code-block::\n\n CMIS Root > DRC > Melding Openbare Ruimte > 2020 > 12 > 31 > ZAAK-0000001 > document.txt\n CMIS Root > DRC > Melding Openbare Ruimte > 2020 > 12 > 31 > ZAAK-0000001 > Related data > document.txt-gebruiksrechten\n CMIS Root > DRC > Melding Openbare Ruimte > 2020 > 12 > 31 > ZAAK-0000001 > Related data > document.txt-oio\n\n**Relating a document to a Besluit**\n\nWhen a document is related to a Besluit, there's a few different scenario's:\n\n1. The Besluit is **related** to a Zaak and...\n\n 1. The document is **not related** to a Zaak (and thus the document is in\n the temporary folder): The document is **moved** to the Zaak folder of\n the Zaak that is related to the Besluit.\n 2. The document is **already related** to a Zaak: The document is **copied**\n to the new Zaak folder.\n\n2. The Besluit is **not related** to a Zaak and...\n\n 1. The document is **not related** to a Zaak: The document **stays** in its\n temporary folder.\n 2. The document is **related** to a Zaak: The document is **copied** to the\n temporary folder.\n\nIn all cases, the relation of a document to a Besluit is stored as a separate\ndocument (``oio``) in the ``Related data`` folder, relative to wherever the new\ndocument is stored.\n\n**Relating a document to another object**\n\nWhen a document is related to any other object, the document is not moved or\ncopied and stays in its temporary folder.\n\n**Deleting a Zaak Informatie Object**\n\nWhen a document is related to a zaak, it is located in the zaak folder and has an OIO in the 'Related Data'\nfolder. If the ZIO relating the zaak and the document is deleted, the OIO is deleted, and the document\nshould not remain in the zaak folder. This is done as follows:\n\n1. If the document is NOT a copy (i.e. it's the original document), it should be moved to the default folder.\n If there are related gebruiksrechten, then they should also be moved.\n2. If the document IS a copy, then it should be deleted. Related gebruiksrechten should also be deleted.\n\n\nDMS folder structure overview\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nYou can configure the folders used by the CMIS adapter via the admin interface.\nSome folders are templated (indicated with ``{{ }}``) which means their value\ndepends on the current date or the related Zaak.\n\nA complete overview of all default folders and documents are shown below:\n\n**Zaak folder path**\n\nStorage location for documents related to a Zaak.\n\nDefault: ``/DRC/{{ zaaktype }}/{{ year }}/{{ month }}/{{ day }}/{{ zaak }}/``\n\n.. code-block::\n\n CMIS Root\n +-- DRC (cmis:folder)\n +-- [zaaktype-folder] (drc:zaaktypefolder)\n +-- [year] (cmis:folder)\n +-- [month] (cmis:folder)\n +-- [day] (cmis:folder)\n +-- [zaak-folder] (drc:zaakfolder)\n +-- [filename] (drc:document)\n +-- Related data (cmis:folder)\n +-- [filename]-gebruiksrechten (drc:gebruiksrechten)\n +-- [filename]-oio (drc:oio)\n\nYou can for example change this to: ``/DRC/{{ zaaktype }}/{{ zaak }}/`` to\nremove the year/month/day folder structure entirely.\n\n**Other folder path**\n\nStorage location for documents not (yet) related to a Zaak.\n\nDefault: ``/DRC/{{ year }}/{{ month }}/{{ day }}/``\n\n.. code-block::\n\n CMIS Root\n +-- DRC (cmis:folder)\n +-- [year] (cmis:folder)\n +-- [month] (cmis:folder)\n +-- [day] (cmis:folder)\n +-- [filename] (drc:document)\n +-- Related data (cmis:folder)\n +-- [filename]-gebruiksrechten (drc:gebruiksrechten)\n +-- [filename]-oio (drc:oio)\n\nNotes on differences between DMSs\n=================================\n\n**SQL queries support**\n\nThe SQL queries that are not supported in Alfresco can be found `here`_. In addition, queries such as:\n``SELECT * FROM drc:document WHERE cmis:parentId = '<folder.objectId>'`` don't seem to work.\n\nThe SQL queries that seem not to be supported in Corsa are:\n\n* ``IN`` queries\n* ``IN_FOLDER('<folder objectId>')``\n* ``OR`` queries\n\n.. _`here`: https://docs.alfresco.com/insight-engine/latest/using/sql/#unsupported-sql-commands\n\nReferences\n==========\n\n* `Issues <https://github.com/open-zaak/open-zaak/issues>`_\n* `Code <https://github.com/open-zaak/cmis-adapter>`_\n\n\nLicense\n=======\n\nCopyright \u00a9 Dimpact 2019 - 2020\n\nLicensed under the EUPL_\n\n.. _EUPL: LICENCE.md\n\n.. _`Maykin Media B.V.`: https://www.maykinmedia.nl\n\n.. _`Alfresco`: https://www.alfresco.com/ecm-software/alfresco-community-editions\n\n.. |build-status| image:: https://github.com/open-zaak/cmis-adapter/workflows/Run%20CI/badge.svg\n :target: https://github.com/open-zaak/cmis-adapter/actions?query=workflow%3A%22Run+CI%22\n :alt: Run CI\n\n.. |linting| image:: https://github.com/open-zaak/cmis-adapter/workflows/Code%20quality%20checks/badge.svg\n :target: https://github.com/open-zaak/cmis-adapter/actions?query=workflow%3A%22Code+quality+checks%22\n :alt: Code linting\n\n.. |coverage| image:: https://codecov.io/gh/open-zaak/cmis-adapter/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/open-zaak/cmis-adapter\n :alt: Coverage status\n\n.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n\n.. |python-versions| image:: https://img.shields.io/pypi/pyversions/drc-cmis.svg\n\n.. |django-versions| image:: https://img.shields.io/pypi/djversions/drc-cmis.svg\n\n.. |pypi-version| image:: https://img.shields.io/pypi/v/drc-cmis.svg\n :target: https://pypi.org/project/drc-cmis/\n\n.. _Documenten API: https://vng-realisatie.github.io/gemma-zaken/standaard/documenten/index\n",
"bugtrack_url": null,
"license": "EUPL-1.2",
"summary": "An adapter to manage Documenten API resources in a CMIS backend.",
"version": "1.9.0",
"project_urls": {
"Homepage": "https://github.com/open-zaak/cmis-adapter"
},
"split_keywords": [
"cmis",
" documenten api",
" vng",
" common ground"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "12684af37a2c8758b9c4dec10d6390d3a8199421ec7fb3fd4ced2efb24ac2ac6",
"md5": "5b5f023380eb6fc6dba7ded6ffff64ed",
"sha256": "64809e89eb0988ffbe27b139f0ab876186909c4656a7cba2f6e2b1badce85ea6"
},
"downloads": -1,
"filename": "drc_cmis-1.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b5f023380eb6fc6dba7ded6ffff64ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 99618,
"upload_time": "2024-04-12T15:46:26",
"upload_time_iso_8601": "2024-04-12T15:46:26.574857Z",
"url": "https://files.pythonhosted.org/packages/12/68/4af37a2c8758b9c4dec10d6390d3a8199421ec7fb3fd4ced2efb24ac2ac6/drc_cmis-1.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "07950ac2e1dacabb49fa0b4b88e081c97d11a44363e7c856e60b058e24fe51c9",
"md5": "5390bd66afbf5fd6c0f0e7f38d528cdf",
"sha256": "d51a264a61d8b8a99f5e1f7683aa2bc7465cece17accfe6ad64b66d7d0359948"
},
"downloads": -1,
"filename": "drc-cmis-1.9.0.tar.gz",
"has_sig": false,
"md5_digest": "5390bd66afbf5fd6c0f0e7f38d528cdf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 102537,
"upload_time": "2024-04-12T15:46:29",
"upload_time_iso_8601": "2024-04-12T15:46:29.602119Z",
"url": "https://files.pythonhosted.org/packages/07/95/0ac2e1dacabb49fa0b4b88e081c97d11a44363e7c856e60b058e24fe51c9/drc-cmis-1.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 15:46:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "open-zaak",
"github_project": "cmis-adapter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "drc-cmis"
}
JSON
