close

Filter

loading table of contents...

Headless Server Developer Manual / Version 2406.0

Table Of Contents

4.14 Taxonomies

Overview

In the Headless Server, taxonomies can be retrieved via id or path, see Section “Retrieve a taxonomy”. How to retrieve content items 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 localized 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 content item by id.

{
  content {
    taxonomy(id: "coremedia:///cap/content/1234") {
      id
      name
      value
    }
  }
}
  
Retrieve a localized taxonomy by id (and locale)

This GraphQL query is a simple example for fetching a localized CMTaxonomy document by id and locale. If the locale parameter is null or skipped completely, the target locale will be determined by the TaxonomyLocalizationStrategy that is passed to the TaxonomyAdapter.

{
  content {
    localizedTaxonomy(id: "coremedia:///cap/content/1234", locale: "en-US") {
      id
      value
    }
  }
}
  

To fetch a list of the supported locales, the query supportedTaxonomyLocales can be executed:

{
  content {
    supportedTaxonomyLocales
  }
}
  

The result contains the list translations which describes the target locales and the defaultLocale, that describes the locale of the value field of every taxonomy.

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 content item by a single segment path:

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

This GraphQL query is an example for fetching a CMTaxonomy content item 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. Also, localized path segments are not supported. Every segment must match the actual value field of a node.

Retrieve content tagged with a taxonomy

Content items can be tagged with subject and/or location taxonomies. For faster lookup, the tags are stored for each content item in the Solr index of the CAE. To retrieve a content item 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 content item 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.