The tag service provides the backbone of the tagging feature. Tags are keywords applied as metadata on documents reflecting (for instance) the user opinion about that document. 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.
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 org.nuxeo.ecm.platform.tag.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.
A tag cloud is a set of weighted tags, the weights being integers representing the frequency of the tag. The weights can be just a count of occurrences, or can be normalized to the 0-100 range for easier display.
Tags, Versions and Proxies
Since 5.7.3, 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.
Everything is done in the org.nuxeo.ecm.platform.tag.TaggedVersionListener listener.
Disabling Tags on Versions and Proxies
To disable the duplication of tags on versions and proxies, the org.nuxeo.ecm.platform.tag.TaggedVersionListener listener needs to 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>