AEM Tagging Framework aem-tagging-framework

To tag content and leverage the AEM tagging infrastructure :

Tags : cq:Tag Node Type tags-cq-tag-node-type

The declaration of a tag is captured in the repository in a node of type cq:Tag.

A tag can be a simple word (e.g. fruit) or represent a hierarchical taxonomy (e.g. fruit/apple, meaning both fruits in general and the more specific apple).

Tags are identified by a unique TagID.

A tag has optional meta information such as a title, localized titles, and a description. The title should be displayed in user interfaces instead of the TagID, when present.

The tagging framework also provides the ability to restrict authors and site visitors to use only specific, predefined tags.

Tag Characteristics tag-characteristics

TagID tagid

A TagID identifies a path which resolves to a tag node in the repository.

Typically, the TagID is a shorthand starting with the namespace or it can be absolute starting from the taxonomy root node.

When content is tagged, if it does not yet exist, the cq:tags property is added to the content node and the TagID is added to the property’s string array value.

The TagID consists of a namespace followed by the local TagID. Container tags have sub-tags that represent a hierarchical order in the taxonomy. Sub-tags can be used to reference tags same as any local TagID. For example tagging content with fruit is allowed, even if it is a container tag with sub-tags, such as fruit/apple and fruit/banana.

Taxonomy Root Node taxonomy-root-node

The taxonomy root node is the base path for all tags in the repository. The taxonomy root node must not be a node of type cq:Tag.

In AEM, the base path is /content/cq:tags and the root node is of type cq:Folder.

Tag Namespace tag-namespace

Namespaces allow group things. The most typical use case is to have a namespace per site (e.g. public, internal, and portal) or per larger application (e.g. Sites, Assets, Forms) but namespaces can be used for various other needs. Namespaces are used in the user interface to only show the subset of tags (i.e. tags of a certain namespace) that is applicable to the current content.

The tag’s namespace is the first level in the taxonomy subtree, which is the node immediately below the taxonomy root node. A namespace is a node of type cq:Tag whose parent is not a cq:Tag node type.

All tags have a namespace. If no namespace is specified, the tag is assigned to the default namespace, which is TagID default (title is Standard Tags) that is /content/cq:tags/default.

Container Tags container-tags

A container tag is a node of type cq:Tag containing any number and type of child nodes, which makes it possible to enhance the tag model with custom metadata.

Furthermore, container tags (or super-tags) in a taxonomy serve as the sub-summation of all sub-tags. For example, content tagged with fruit/apple is considered to be tagged with fruit as well. This means that searching for content just tagged with fruit would also find the content tagged with fruit/apple.

Resolving TagIDs resolving-tagids

If the tag ID contains a colon :, the colon separates the namespace from the tag or sub-taxonomy, which are then separated with normal slashes /. If the tag ID does not have a colon, the default namespace is implied.

The standard and only location of tags is below /content/cq:tags.

Tag referencing non-existing paths or paths that do not point to a cq:Tag node are considered invalid and are ignored.

The following table shows some sample TagIDs, their elements, and how the TagID resolves to an absolute path in the repository.

Localization of Tag Title localization-of-tag-title

When the tag includes the optional title string (jcr:title) it is possible to localize the title for display by adding the property jcr:title.<locale>.

For more details see:

Access Control access-control

Tags exist as nodes in the repository under the taxonomy root node. Allowing or denying authors and site visitors the ability to create tags in a given namespace can be achieved by setting appropriate ACLs in the repository.

Also, denying read permissions for certain tags or namespaces will control the ability to apply tags to specific content.

A typical configuration includes:

Taggable Content : cq:Taggable Mixin taggable-content-cq-taggable-mixin

In order for application developers to attach tagging to a content type, the node’s registration (CND) must include the cq:Taggable mixin or the cq:OwnerTaggable mixin.

The cq:OwnerTaggable mixin, which inherits from cq:Taggable, is intended to indicate that the content can be classified by the owner/author. In AEM, it is only an attribute of the cq:PageContent node. The cq:OwnerTaggable mixin is not required by the tagging framework.

Node Type Notation (CND) node-type-notation-cnd

Node Type definitions exist in the repository as CND files. The CND notation is defined as part of the JCR documentation here.

The essential definitions for the Node Types included in AEM are as follows:

[cq:Tag] > mix:title, nt:base
    orderable
    - * (undefined) multiple
    - * (undefined)
    + * (nt:base) = cq:Tag version

[cq:Taggable]
    mixin
    - cq:tags (string) multiple

[cq:OwnerTaggable] > cq:Taggable
    mixin

Tagged Content: cq:tags Property tagged-content-cq-tags-property

The cq:tags property is a string array used to store one or more TagIDs when they are applied to content by authors or site visitors. The property only has meaning when added to a node which is defined with the cq:Taggable mixin.

Moving and Merging Tags moving-and-merging-tags

The following is a description of the effects in the repository when moving or merging tags using the Tagging console:

Tags Migration tags-migration

In Adobe Experience Manager 6.4 onwards, tags are stored under /content/cq:tags. However, in scenarios where Adobe Experience Manager has been upgraded from previous version the tags are still present under the old location /etc/tags. In upgraded systems tags need to be migrated to /content/cq:tags.

If Upgraded AEM Instance Supports TagManager API**

import org.apache.sling.api.resource.*
import javax.jcr.*

ResourceResolverFactory resourceResolverFactory = osgi.getService(ResourceResolverFactory.class);
ResourceResolver resolver = resourceResolverFactory.getAdministrativeResourceResolver(null);
Session session = resolver.adaptTo(Session.class);

def queryManager = session.workspace.queryManager;
def statement = "/jcr:root/content/cq:tags//element(*, cq:Tag)[jcr:contains(@cq:movedTo,\'/etc/tags\') or jcr:contains(@cq:backlinks,\'/etc/tags\')]";
def query = queryManager.createQuery(statement, "xpath");

println "query = ${query.statement}\n";

def tags = query.execute().getNodes();


tags.each { node ->
        def tagPath = node.path;
        println "tag = ${tagPath}";

        if(node.hasProperty("cq:movedTo") && node.getProperty("cq:movedTo").getValue().toString().startsWith("/etc/tags")){

                def movedTo = node.getProperty("cq:movedTo").getValue().toString();

                println "cq:movedTo = ${movedTo} \n";

                movedTo = movedTo.replace("/etc/tags","/content/cq:tags");
                node.setProperty("cq:movedTo",movedTo);
        } else if(node.hasProperty("cq:backlinks")){

               String[] backLinks = node.getProperty("cq:backlinks").getValues();
               int count = 0;

               backLinks.each { value ->
                       if(value.startsWith("/etc/tags")){
                               println "cq:backlinks = ${value}\n";
                               backLinks[count] = value.replace("/etc/tags","/content/cq:tags");
    }
                       count++;
               }

               node.setProperty("cq:backlinks",backLinks);
  }
}
session.save();

println "---------------------------------Success-------------------------------------"

The script fetches all those tags that have /etc/tags in the value of cq:movedTo/cq:backLinks property. It then iterates through the fetched result set and resolves the cq:movedTo and cq:backlinks property values to /content/cq:tags paths (in the case where /etc/tags is detected in the value).

If Upgraded AEM Instance Runs on Classic UI**

In case the upgraded AEM instances is supported by the TagManager API and runs in Classic UI: