Headless Server Developer Manual / Version 2304
Table Of ContentsOverview
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. thevalue
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
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 } } } }