Nuxeo Server

Tagging

Updated: October 13, 2017 Page Information Edit on GitHub

The tags are either categorizing the content of the document (labels like "document management", "ECM", "complex Web application", etc., can be thought as tags for Nuxeo), or they reflect the user feeling ("great", "user friendly", "versatile", etc.).

The tag service uses two important concepts: a tag object, and a tagging action. Both are represented as Nuxeo documents.

A tag holds a label that does not contain any space ("documentmanagement", "webapplication", etc.). A tagging action is a link between a given document and a tag, and belongs to a given user.

Functional Overview

Unlike subjects in the metadata of the document, you don't have to choose tags in a closed list. You are free to apply the tags that describe the document best. However, tags are proposed as you type them, to enable you to use the same tags as the other users and have a consistent tagging of documents. You can add as many tags on documents as you want.

You can then use the tag cloud to find all documents that have the same tags.

Documents can be tagged in workspaces and in sections. When a document is published, the tags applied in the workspaces are published with the document. Users can add a tag on a document as soon as they can access the document, i.e. as soon as they have reading permissions.

To tag a document, go on the Summary tab of the document and click on and type the label you want to add. Click on the suggested label to add an existing tag or on the tag in green to create and add a new one. The tag is immediately added on the document and available in the tag cloud.

To remove a tag from a document, you need to be the user who added the tag on the document or have at least Edit permission on the document. Click on the icon . The tag is immediately removed.

Tags, Versions and Publication

When you save a document as a new version, the tags that user have put on the document are saved with the version. This means that the archived versions of a document and the document in its current version can have different tags. If you restore a previous version of the document, tags are restored with it and replace the tags from the replaced version.

When you publish a document, the tags are copied from the work document to the published document. You can then remove useless tags from either version of the document (work version or published version) without affecting the other one. In case of republication of the document, the tags from the last and previous version are merged so you don't loose any previous or preparatory categorization.

Tag Service Architecture

The following document types are defined by the tag service.

A Tag is a document type representing the tag itself (but not its association to specific documents). It contains the usual dublincore schema, and in addition has a specific tag schema containing a tag:label string field.

A Tagging is a relation type representing the action of tagging a given document with a tag. (A relation type is a document type extending the default Relation document type; it works like a normal document type except that it's not found by NXQL queries on Document). The important fields of a Tagging document are relation:source which is the document id, relation:target which is the tag id, and dc:creator which is the user doing the tagging action.

Both Tag and Tagging documents managed by the tag service are unfiled, which means that they don't have a parent folder. They are therefore not visible in the normal tree of documents; only queries can find them. In addition they don't have any ACLs set on them, which means that only a superuser (and the tag service internal code) can access them.

Tag Service Features

The tag service is accessed through the TagService interface.

The tag service allows you to:

  • Tag and untag a document
  • Get all the tags for a document
  • Get all the documents for a tag
  • Get the tag cloud for a set of documents
  • Get suggested tags for a given tag prefix

Tags, Versions and Proxies

The tags are duplicated:

  • From the live document when creating a version
  • From a version when creating a proxy

When restoring a version, the tags on the live document are also restored from the ones on the version.

Tags can be added and removed independently on live documents, versions and proxies: a tag added on a live document won't be added on all its versions, but only on the versions that will be created after. The same behavior is applied for proxies.

The logic for the above is in the TaggedVersionListener listener.

Disabling Tags on Versions and Proxies

To disable the duplication of tags on versions and proxies, the TaggedVersionListener may be disabled with the following contribution:

<require>org.nuxeo.ecm.platform.tag.service.listener</require>
<extension target="org.nuxeo.ecm.core.event.EventServiceComponent" point="listener">
  <listener name="taggedVersionListener" enabled="false" />
</extension>

Related pages in current documentation
Related pages in other documentation
5 days ago manonlumeau NXDOC-1346-FT review screenshot
a year ago Solen Guitter 18
a year ago Manon Lumeau 17
a year ago Manon Lumeau 16 | javadoc links updated
2 years ago Florent Guillaume 15 | details
2 years ago Solen Guitter 14 | Remove tag weight, as all tags have the same size now
2 years ago Solen Guitter 13 | Update related pages
2 years ago Florent Guillaume 12
2 years ago Florent Guillaume 11
2 years ago Florent Guillaume 10
2 years ago Florent Guillaume 9
2 years ago Manon Lumeau 7
2 years ago Manon Lumeau 8
4 years ago Solen Guitter 6 | Typos, added TOC and related topics
4 years ago Thomas Roger 5
4 years ago Solen Guitter 4
7 years ago Solen Guitter 2
7 years ago Solen Guitter 3 | Migrated to Confluence 4.0
7 years ago Florent Guillaume 1
History: Created by Florent Guillaume