close

Filter

loading table of contents...

Headless Server Developer Manual / Version 2110

Table Of Contents

4.13 Taxonomies

Overview

In the Headless Server, taxonomies can be retrieved via id or path, see Section “Retrieve a taxonomy”. How to retrieve documents tagged with specific taxonomies is described in Section “Retrieve content tagged with a taxonomy”.

Retrieve a taxonomy

Taxonomies are handled with the bean taxonomyAdapter defined in CaasConfig.java. The following functionality is supported:

  • Retrieve a taxonomy by id
  • Retrieve a taxonomy by path segments
Retrieve a taxonomy by id

This GraphQL query is a simple example for fetching a CMTaxonomy document by id.

{
  content {
    taxonomy(id: "coremedia:///cap/content/1234") {
      id
      name
      value
    }
  }
}
  
Retrieve a taxonomy by path segments

To retrieve a taxonomy via path segments, these parameters can be provided:

  • pathSegments: A String containing only the taxonomy value, or all path segments up to the root, separated by '/'. The path segment lookup is performed via linked parents, i.e. the value of the linked parent up to the root.
  • type: CMTaxonomy for Subject Taxonomies (default), CMLocTaxonomy for LocationTaxonomies. Will be matched exactly.
  • siteId: The siteId of the site to look up taxonomies. If empty, taxonomies will be looked up globally.

This GraphQL query is a simple example for fetching a CMLocTaxonomy document by a single segment path:

{
  content {
    taxonomyByPath(pathSegments: "Tokyo") {
      id
      name
      value
    }
  }
}
  

This GraphQL query is an example for fetching a CMTaxonomy document by the complete segment path up to the root:

{
  content {
    taxonomyByPath(pathSegments: "Asia/Japan/Tokyo") {
      id
      name
      value
    }
  }
}
  
Global and site specific taxonomies

If a siteId is provided, taxonomies are retrieved for the corresponding site, else globally.

  • Global Taxonomies are retrieved from:

    global configuration path + "/Taxonomies", e.g. "/Settings/Taxonomies".

  • Site specific Taxonomies are retrieved from:

    site root folder + site specific configuration path + "/Taxonomies",

    e.g. "/Sites/Aurora Augmentation/United States/English/Options/Settings/Taxonomies".

The site specific and global configuration paths are defined via configuration properties and can be overidden:

  • content.globalConfigurationPath
  • content.siteConfigurationPath

The configuration paths are passed to the constructor of the class TaxonomyAdapterFactory.java and can also be changed explicitely in CaasConfig.java.

Note

Note

It is assumed, that taxonomy paths are unique. If multiple taxonomies are found for a path, only the first one is returned.

Retrieve content tagged with a taxonomy

Documents can be tagged with subject and/or location taxonomies. For faster lookup, the tags are stored for each document in the Solr index of the CAE. To retrieve a document tagged with a specific taxonomy, a search is executed on the CAE index. Therefore, the Headless Server search extension is required, to use this functionality.

Search query with custom filter

To search for a document that is tagged with a given taxonomy, a provided custom filter query needs to be applied. See Section 6.3, “Custom Filter Queries” for details of custom filter queries.

The custom filter queries identified by keys SUBJ_TAXONOMY_OR and LOCATION_TAXONOMY_OR provide capabilities to create a Solr query containing filter queries for given taxonomies.

The custom filter queries take either the taxonomy ids or the paths as arguments:

  • List of numeric ids, e.g. ["1234", "5678"]

  • List of content ids, e.g. ["coremedia:///cap/content/1234", "coremedia:///cap/content/5678"]

  • List of complete path segments or the taxonomy value, e.g. ["Blog/Kitchen", "Cooking"]. The lookup is performed via taxonomyAdapter.

Example query to retrieve articles that are tagged with the subject taxonomies 'Cooking' OR 'Kitchen':

{
  content {
    search(query: "*", docTypes: ["CMArticle"],
      customFilterQueries: [
        {SUBJ_TAXONOMY_OR: ["Cooking", "Kitchen"]}
      ]
    ) {
      numFound
      result {
        id
      }
    }
  }
}

To combine taxonomies via AND, multiple custom filter queries with the same key can be provided.

Example query to retrieve articles that are tagged with the subject taxonomies 'Cooking' AND 'Kitchen':

{
  content {
    search(query: "*", docTypes: ["CMArticle"],
      customFilterQueries: [
        {SUBJ_TAXONOMY_OR: ["Cooking"]},
        {SUBJ_TAXONOMY_OR: ["Kitchen"]}
      ]
    )
    {
      numFound
      result {
        id
      }
    }
  }
}
Global and site specific taxonomies

The taxonomy lookup is performed globally by default. For a site specific lookup the siteId can be given as first list item, e.g. ["siteId:corporate", "1234", "5678"]

Example query to retrieve articles that are tagged with the site specific location taxonomies 'Europe' OR 'Asia' of the site with siteId 'corporate':

{
  content {
    search(query: "*", docTypes: ["CMArticle"],
      customFilterQueries: [
        {LOC_TAXONOMY_OR: ["siteId:corporate", "Europe", "Asia"]}
      ]
    )
    {
      numFound
      result {
        id
      }
    }
  }
}

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.