CMIS

TypeDMS DistributionFree

The CMIS Plugin lets CMDBuild use an external Document Management System that speaks the CMIS (Content Management Interoperability Services) protocol, such as Alfresco, to store card attachments.

Once the plugin is enabled, every attachment uploaded from the CMDBuild UI, the REST web services, workflows or incoming emails is stored in the CMIS repository. CMDBuild keeps only the reference to the document.

The plugin supports:

• Uploading, downloading, updating and deleting attachments
• Document versioning (major and minor versions) and version history
• Document metadata: author, description and category
• Document preview, using the thumbnails generated by the repository
• Full-text search on attachments (advanced search)

Prerequisites

• CMDBuild core version 4.0.0 or later
• A CMIS repository reachable from the CMDBuild server through the AtomPub binding
• A repository user with read and write permissions on the root folder used by CMDBuild

Service configuration

The following settings are needed on the CMIS repository side.

Endpoint

The plugin connects to the AtomPub endpoint of the repository using HTTP Basic authentication. For Alfresco the endpoint is usually:

http://<alfresco-host>:<port>/alfresco/api/-default-/public/cmis/versions/1.1/atom

Root folder

CMDBuild stores all its documents under a single root folder (by default /User Homes/cmdbuild). If the root folder or any subfolder does not exist, the plugin creates it the first time a document is uploaded. The configured user must therefore be allowed to create folders and documents under that path.

Metadata model

Document metadata is stored using CMIS 1.1 secondary types (Alfresco aspects). When a document is created, the plugin applies these aspects:

Aspect	Property	CMDBuild field	Notes
P:cm:author	cm:author	Author	Standard Alfresco aspect
P:cm:titled	cm:description	Description	Standard Alfresco aspect
P:cmdbuild:classifiable	cmdbuild:classification	Category	Custom aspect, must be deployed first

The cmdbuild:classifiable aspect is not part of the standard Alfresco model. A custom content model that defines the cmdbuild namespace, the cmdbuild:classifiable aspect and its cmdbuild:classification text property must be deployed on the repository. If the aspect is missing, document creation fails.

If the repository supports only CMIS 1.0, secondary types are not available: documents are stored without author, description and category, and a warning is written to the CMDBuild log.

Thumbnails and full-text search

• Document preview uses the cmis:thumbnail renditions generated by the repository. If the repository generates no thumbnails, no preview is shown.
• Advanced search uses CMIS full-text queries (CONTAINS), so full-text indexing must be active on the repository (for Alfresco, Search Services / Solr).

Configuration

Plugin configuration

Enabling the DMS

To use CMIS as the attachment storage, set the following CMDBuild core settings (Administration module → System config → DMS):

Config	Value	Description
org.cmdbuild.dms.enabled	true	Enables the DMS module
org.cmdbuild.dms.service.type	cmis	Selects the CMIS plugin as the DMS provider
org.cmdbuild.dms.advanced.search	true / false	Enables full-text search on attachments (default true)
org.cmdbuild.dms.category	lookup type name	Lookup used for attachment categories (default AlfrescoCategory)

Connection parameters

The connection to the repository is set in the plugin configuration (plugin cmis, namespace dms.service.cmis):

Config	Default	Description
dms.service.cmis.url *	http://localhost:10080/alfresco/api/-default-/public/cmis/versions/1.1/atom	AtomPub endpoint of the CMIS repository
dms.service.cmis.user *	admin	Username used to connect to the repository
dms.service.cmis.password *		Password used to connect to the repository
dms.service.cmis.path	/User Homes/cmdbuild	Root folder where CMDBuild stores its documents
dms.service.cmis.read.timeout	30000	Read timeout of requests to the repository, in milliseconds

* required. The default values are for a local test installation only and must be changed in production.

The connection timeout is fixed at 10 seconds and cannot be configured.

The status of the connection is shown in the system services list as DMS_ CMIS client.

Additional Notes

Repository folder structure

Documents are organized in folders that follow the class hierarchy of the card they belong to:

<root path>/<superclass>/.../<class>/Id<card id>/<file name>

The base Class superclass is not included in the path. For example, an attachment manual.pdf of card 12345 of class Notebook, which inherits from Computer, is stored as:

/User Homes/cmdbuild/Computer/Notebook/Id12345/manual.pdf

Full-text searches look only in the folder of the card or, when no card is given, in the folder of the class and all its subfolders.

Notes and Limitations

• Single repository: the plugin always uses the first repository exposed by the endpoint. Selecting a repository by ID is not supported.
• Binding and authentication: only the AtomPub binding with HTTP Basic authentication is supported.
• Path tied to class names: folder names come from the class names. If a class is renamed or the class hierarchy changes, the documents already stored in the old folders are no longer found by CMDBuild unless they are moved in the repository.
• MIME type: the MIME type is detected from the file content (Apache Tika), not from the file extension.
• Versioning: when the content of an attachment is updated, the plugin performs a check-out / check-in on the repository, creating a new major or minor version. If only the metadata changes, the properties are updated without creating a new version. The version history is available only if the repository document type is versionable.
• Deletion: deleting an attachment from CMDBuild removes the document with all its versions from the repository. Empty card folders are not removed.
• Search terms: the search text is passed as-is to the CMIS CONTAINS clause. Search terms with single quotes (') can make the query fail.
• Connection cache: the repository connection is cached. After changing the connection parameters, restart the DMS service (or CMDBuild) so the new values are used.

Deployment Notes

• The plugin requires CMDBuild core 4.0.0 or later.
• The Apache Chemistry OpenCMIS client library (version 1.1.0) is bundled inside the plugin jar, so no additional libraries need to be installed on the server.
• Upgrading from versions where CMIS was part of the core: the connection parameters were previously read from the core settings org.cmdbuild.dms.service.cmis.*. The plugin reads them only from its own plugin configuration (dms.service.cmis.*), so check that URL, credentials, path and timeout are set in the plugin configuration after the upgrade. The folder structure is unchanged, so documents that already exist stay available.