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

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:

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.

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.

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:

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