Taxonomy Support

Taxonomy Support

Generator supports the use of taxonomies to coordinate metadata generation with organization-defined lists of values. This feature is available for two metadata fields: SKILLS and KEYWORDS. When a taxonomy is configured for these fields, Generator will align the generated metadata values with the terms defined in your taxonomy, helping to normalize metadata across your organization.

What is a Taxonomy?

A taxonomy is a structured list of terms defined at the organization level that identifies concepts in a standardized way. For metadata generation, Generator supports taxonomies for:

  • SKILLS: A structured list of capabilities or competencies the content aims to develop
  • KEYWORDS: A structured list of themes, topics, or subject areas the content covers

For clarity, SKILLS identify what the learner will be able to do after engaging with the content, and KEYWORDS describe what the content is about — its core topics, themes, and concepts.

Taxonomies help ensure consistency across your content library by aligning generated metadata with the same terminology used in your other systems.

Importing a Taxonomy

To import a taxonomy into Generator, use the POST /api/v1/jobs/taxonomy endpoint. This endpoint accepts information that describes how the application should process and interact with the taxonomy. The required properties are described below:

  • taxonomy_csv - The taxonomy file itself. Generator only accepts taxonomies in CSV format at this time.
  • taxonomy_type - The type of taxonomy being imported. Must be either SKILLS or KEYWORDS.
  • csv_col_name - The column label that specifies the term names. The names specified by this column will ultimately be the terms included in the pool of possible metadata values.
  • taxonomy_id - The identifier used to identify this specific taxonomy.
  • set_configuration - (Optional, defaults to false) When set to true, Generator will automatically configure the imported taxonomy as the active taxonomy for its type. This sets the appropriate configuration setting (GENERATION__SKILL_TAXONOMY for SKILLS or GENERATION__KEYWORD_TAXONOMY for KEYWORDS) to use the newly imported taxonomy. If set to false or omitted, you will need to manually configure the taxonomy after import (see Configuration Settings).

You can import multiple taxonomies of the same type into your Generator instance. Each taxonomy must have a unique taxonomy_id.

Configuration Settings

After importing one or more taxonomies, you must specify which taxonomy should be used when generating metadata for each supported field. You can configure this in one of two ways:

  1. Automatically during import: Set the set_configuration parameter to true when importing a taxonomy (see Importing a Taxonomy). This will automatically configure the imported taxonomy as the active one for its type.
  2. Manually after import: Set the configuration setting manually using the PUT /api/v1/config/{setting} API endpoint.

Generator provides separate configuration settings for each taxonomy type:

  • GENERATION__SKILL_TAXONOMY - Specifies which skills taxonomy should be used when generating SKILLS metadata
  • GENERATION__KEYWORD_TAXONOMY - Specifies which keywords taxonomy should be used when generating KEYWORDS metadata

Both settings should be set to the taxonomy_id of the intended taxonomy. More information about configuration settings can be found here. Using these settings, you can import multiple taxonomies into your Generator instance and swap between them as necessary.

By default, both configuration settings are empty (have a value of ""). When a configuration value is empty, the application will NOT coordinate the metadata generation with any taxonomy for that field type. Therefore, you must configure the appropriate setting (either automatically during import or manually afterward) in order to involve your taxonomy in Generator’s metadata generation process.

Taxonomy Metadata Generation

Metadata generation jobs for SKILLS and KEYWORDS can be initiated either through:

  • a content import job, or
  • a field generation job.

The metadata generation process follows one of two workflows, depending on whether a taxonomy is configured:

Generation without a Taxonomy

To generate SKILLS or KEYWORDS metadata for a course without coordination of a taxonomy:

  1. Confirm that the appropriate configuration setting (GENERATION__SKILL_TAXONOMY or GENERATION__KEYWORD_TAXONOMY) has an empty value, and then
  2. Initiate a field generation job, either through the course import process or via a field generation job. See here for more details.

Generation with a Taxonomy

To generate SKILLS or KEYWORDS metadata for a course in coordination with a taxonomy:

  1. Successfully import a taxonomy into the application using the POST /api/v1/jobs/taxonomy endpoint. You can optionally set the set_configuration parameter to true during import to automatically configure the taxonomy.
  2. If you did not use set_configuration=true during import, manually set the application’s appropriate configuration setting (GENERATION__SKILL_TAXONOMY for SKILLS or GENERATION__KEYWORD_TAXONOMY for KEYWORDS) with the taxonomy_id value of the imported taxonomy.
  3. Initiate a field generation job, either through the course import process or via a field generation job. See here for more details.

Handling No Matches

When generating metadata with a configured taxonomy, Generator might encounter situations where no terms in the taxonomy are relevant to the course content. When Generator is unable to find relevant taxonomy terms, Generator will:

  • include a warning in the warnings property of the Field Generation job for that metadata field
  • return an empty list for GET /api/v1/content/{content_id}/versions/{version}/fields/{field} for that given field. Previous values can still be returned if the include_previous_values parameter is true.