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

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:

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.

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

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

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:

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
      }
    }
  }
}