Vocabularies

Vocabularies allow administrators to define controlled lists of terms that users select when tagging assets. By using vocabularies instead of free-text fields, you ensure data consistency across your entire digital asset library, making search and filtering more reliable.

This feature is designed for administrators to build everything from simple flat lists (like "Colors" or "Status") to complex hierarchical taxonomies (like "Product Categories" or "Organizational Structures"). It includes built-in support for multi-language translations and automated term generation.

Page Overview

• Purpose: To centralize the management of all metadata selection lists.
• When to use it: Use this page when you need to create a new set of tags, update existing category names, or translate metadata terms for international teams.
• What you can do here:
  • Create flat or hierarchical (tree) vocabulary structures.
  • Add, edit, and reorder terms within a vocabulary.
  • Auto-translate terms into multiple languages using integrated services.
  • Protect critical vocabularies from accidental deletion.
  • Convert flat lists into hierarchical structures as your data needs grow.

Page Layout

• Top bar: Contains the page title, a description of the feature, and the Add Vocabulary button.
• Main area: Displays a searchable table of all existing vocabularies, showing their name, unique code, structure type (Flat or Hierarchical), and current translation completion status.
• Search and Filter: A dedicated card above the table allows you to filter the list by vocabulary name or code.
• Dialogs: Contextual windows for creating vocabularies, editing terms, and confirming sensitive actions like deleting protected items.

Main Features

Vocabulary Structures

• What it's for: Defines how terms are organized.
• Typical use: Choose Flat List for simple, independent values. Choose Hierarchical Tree for categories that require parent-child relationships (e.g., "Electronics" > "Computers" > "Laptops").
• Result: Determines whether you can nest terms inside one another when managing the vocabulary.

Auto-Translation

• What it's for: Automatically filling in missing translations for terms.
• Typical use: When adding a new term in your primary language, use the Auto-translate action to instantly generate labels for all other active languages in the system.
• Result: Populates the translation fields, reducing manual data entry for global teams.

Smart Delete

• What it's for: Safely removing terms that are already assigned to assets.
• Typical use: When a category is no longer needed, you can choose to replace it with a different term across all assets or simply clear the value from those assets.
• Result: Prevents broken metadata links and ensures assets remain correctly categorized after a term is removed.

Detailed Feature Documentation

Creating a Vocabulary

• Purpose: To establish a new container for metadata terms.
• Where to find it: In the top bar, click the Add Vocabulary button.
• What you'll see: A dialog appears asking for a name, code, and structure type.

How to use it:

1. Enter a Name (e.g., "Department").
2. The Code will auto-generate based on the name; you can manually edit this if a specific system ID is required.
3. Provide an optional Description to help other admins understand the vocabulary's purpose.
4. Select the Vocabulary Structure: Flat List or Hierarchical Tree.
5. Click Create Vocabulary.

Managing Terms

• Purpose: To add the actual selectable values to a vocabulary.
• Where to find it: Click the Name of any vocabulary in the main table, or select View Terms from the actions menu.
• What you'll see: A dedicated management page for that vocabulary's terms, including search, sorting, and density controls.

How to use it:

1. Click Add Term to create a top-level value.
2. In the Term Name section, enter the label in your default language.
3. If auto-translate is enabled, other language fields will populate automatically.
4. Review the Term Code (auto-generated) and click Create Term.
5. For hierarchical vocabularies, click the Plus (+) icon next to an existing term to add a "Child" term beneath it.

Sorting and Display

• Purpose: To control how terms appear to end-users in the asset metadata panel.
• Where to find it: On the Vocabulary terms page, look for the Sort by dropdown and the Settings (gear icon).
• What you'll see: Options to change the view density (Compact, Normal, Large) and the sort order.

How to use it:

1. Select Custom Order from the Sort by dropdown to enable manual reordering.
2. Click and hold the Grip icon (vertical dots) next to a term and drag it to the desired position.
3. To set the permanent default order for all users, click the Settings (gear icon) and choose between Custom Order or Name A-Z.

Complete Workflows

Workflow: Converting a Flat List to a Hierarchy

• Goal: Add nesting capabilities to a vocabulary that was originally created as a flat list.
• Prerequisites: The vocabulary must currently be a "Flat List" structure.

Steps:

1. Find the vocabulary in the main list and click its Name.
2. Click the Edit Vocabulary button in the top bar.
3. Look for the Convert to Hierarchical button in the structure section.
4. Click Convert to Hierarchical.
5. Confirm the action in the warning dialog (Note: This cannot be undone).

• Expected result: The vocabulary structure changes to "Hierarchical," and you can now add child terms or nest existing terms.

Workflow: Replacing a Retired Term

• Goal: Delete a term without losing metadata on assets currently using it.
• Prerequisites: The term must be assigned to at least one asset.

Steps:

1. Open the vocabulary and find the term you wish to remove.
2. Select Delete from the term's actions menu.
3. In the Delete Term dialog, notice the warning about asset usage.
4. Select the option Replace with another term.
5. Click Choose a replacement term... and select the new term from the list.
6. Click Confirm Delete.

• Expected result: The old term is deleted, and all affected assets are automatically updated to the new term.

Who can use it

The Vocabularies page is restricted to administrators with the "Vocabularies" permission. Everyday users who can only view assets do not see this page, though the terms they produce appear throughout the metadata on assets and collections.

Limits and guardrails

• Deletion is blocked when in use: A vocabulary cannot be deleted as long as at least one metadata field still references it. Remove the references first, then retry.
• Terms with assets cannot be hard-deleted: Simple deletion of a term is refused whenever that term (or any of its descendants) is attached to one or more assets. In that case you must use the "Smart Delete" flow, which offers two safe choices — Replace with another term (which reassigns every affected asset to the replacement) or Clear from all assets (which detaches the term and leaves those assets without that tag). Both actions are applied inside a transaction so either all assets update or none do.
• Hierarchy safeguards: A term cannot be made its own parent, and the system detects and blocks any change that would create a circular chain.
• Large vocabularies are paginated: On vocabularies with more than 100 terms, the admin page loads terms in pages rather than all at once. You can request up to 200 terms per page. Tree vocabularies of that size load only the top-level branches first and fetch children on demand as you expand them.
• System rights vocabularies: Five built-in vocabularies — rights actions, territories, channels, prohibitions, and duties — power the Rights module. They remain editable, but edits to them refresh a system-wide cache automatically so that changes flow through rights evaluation.
• Flat-to-hierarchical conversion is one-way: Converting a flat list to a hierarchical tree cannot be undone. The confirmation dialog warns about this before the change.

What happens behind the scenes

• Auto-translation: When enabled, Freedam can auto-translate vocabulary terms into the workspace's other active languages. Translations for missing languages are generated automatically the first time you use the Auto-translate action, reducing manual data entry for global teams. If the translation service is unavailable or hits its quota, a clear message asks you to enter the labels manually.
• Freshness of term search: Term lookups and tree slices used by pickers elsewhere in the app are cached for up to five minutes for performance. Any edit, deletion, or reorder you make invalidates that cache immediately so users see your change on their next interaction.
• Code stability: Names and descriptions are free to change at any time, but the Code acts as the permanent identifier used by integrations. Once a code has been saved, editing the term name no longer regenerates it — you must update the code manually if you need it to change.
• Smart delete tracks asset counts: Each option in the Smart Delete dialog shows exactly how many assets are affected so you can confirm with full context. The resulting notification reports how many assets were updated and whether the term was replaced or cleared.

Tips and Best Practices

• Unique Codes: While names can be translated, Codes should remain constant. Use simple, hyphenated strings (e.g., marketing-assets) for codes to ensure compatibility with API integrations.
• Protection: Use the Protect option in the actions menu for vocabularies that are critical to system workflows. This adds an extra confirmation step before any edits or deletions can occur.
• Density Settings: If you have a vocabulary with hundreds of terms, use the Compact density setting to see more data on the screen at once.
• Auto-Generation: When creating many terms, check the Create another term after this one box in the term dialog to keep the window open for rapid entry.

Troubleshooting

Issue: Cannot delete a vocabulary

• Symptoms: The delete option is blocked or requires extra confirmation.
• Cause: The vocabulary is marked as "Protected" to prevent accidental data loss.
• Fix:
  1. Select Unprotect from the actions menu first.
  2. Proceed with the Delete action.
• Prevention: Only unprotect vocabularies that you are certain are no longer in use by any metadata definitions.

Issue: Term code is not updating

• Symptoms: Changing the Term Name does not change the Code.
• Cause: Once a code is manually edited or saved, the auto-generation link is broken to prevent accidental URL or API breaks.
• Fix: Manually type the new code into the Term Code field in the Edit Term dialog.

Issue: Translation service failed

• Symptoms: An error message appears saying "Translation service is currently unavailable."
• Cause: The system cannot reach the external translation provider (e.g., DeepL) or the API limit has been reached.
• Fix:
  1. Enter translations manually in the provided language fields.
  2. Contact your system administrator to check the API configuration in the global settings.