Key concepts
Central entities to this are taxonomies. A taxonomy serves as a dictionary of individual tags.
Each taxonomy is represented by a system document with the node type sophora-nt:enhancedTag The External ID of this document is the primary way to reference the taxonomy. A system might have any number of taxonomies, though a few are usually sufficient.
A taxonomy contains individual tags. A tag is a readable string that usually contains one or few words, such as "Hamburg" or "Olympic Games 2024". A tag can also store additional metadata beyond just their readable label.
To tag a document, you must configure a multi-string property using the EnhancedTag-Input field. This will make the property a tag-property within the document's node type. Documents can feature multiple tag-properties that reference different taxonomies.
An example scenario
Imagine a Sophora installation with node types for stories, images, videos and audios. You run a website "MyBrand" and also export all your audio to a podcasting system ("Hear Me") and videos to a video platform ("Watch Me").
Because external platforms often have unique tagging restrictions, you create three distinct taxonomies: Web-Tags, Hear-Me-Tags, and Watch-Me-Tags.
You might then configure a tag-property for all your node types referencing the Web-Tags taxonomy whilst video and audio documents each have an additional tag-field corresponding to their taxonomy from the external system.
- All node types use a tag-property referencing the Web-Tags taxonomy.
- Video and audio documents include an additional tag-property for their respective platforms.
- A video about cats might be tagged "cats," "news," and "videos" for your website, while its "Watch Me" tags might be "cats," "news," and "MyBrand".
Administering Taxonomies
Prerequisite: Taxo is an editorial add-on that must be actively enabled. The following instructions apply only if the add-on is activated.
Creating and editing taxonomies
Taxonomies are system documents managed just like any other document in Sophora Web or the Sophora DeskClient. You can locate them in Sophora Web under the "Tags" menu entry, or in the DeskClient's admin view as part of the document configuration section.
Taxonomies feature two categories of properties: Technical properties, that affect other entities and non-technical properties, that are used to distinguish taxonomies from one another.
A taxonomy has two technical properties: Valid Sites and Types.
- Types: Tags can be grouped by types. The available types are controlled by the corresponding taxonomies types select values. If left empty, tags within that taxonomy cannot have types.
- Valid Sites: Used to control taxonomy visibility when multiple taxonomies share the same tag-property. See the section Associating taxonomies with tag-properties for details.
A taxonomy has three primary non-technical properties: A name, a description and a thumbnail image.
Associating taxonomies with tag-properties
Having a taxonomy does not automatically enable tagging; it must be explicitly referenced by an input field configuration:
- Choose or create a node type with a multi-string property.
- Set the input field configuration for the multi-string property to "Taxonomy" ("
com.subshell.sophora.eclipse.tags.enhancedTagsFormInputField"). - Select the desired taxonomy for this field.
Handling Multiple Taxonomies & Multi-Tenant Setups:
Note: You can select several taxonomies for a single input field. This is typically only required in multi-tenant setups where tenants share the same node type configuration but utilize different taxonomies.
- If an input field references multiple taxonomies, they must specify non-overlapping "Valid Sites".
- Because a document belongs to only one site, exactly one taxonomy will be valid per document and property.
Best Practice: For real-world scenarios, use a default property configuration or a form field group for a shared tag-field, and supply it via a mixin to all node types that need it.
Managing permissions for tags
Access to taxonomies is controlled via standard document permissions. Crucially, permissions on a taxonomy extend to its tags:
- Reading: No special permissions required.
- Creating/Editing: Restricted to users who have permission to edit the parent taxonomy.
- Deleting: Restricted to users who have permission to delete the parent taxonomy.
Lifecycle of taxonomies
Taxonomies and tags handle publication states differently.
Taxonomies:
- Unlike most system documents, taxonomies do not need to be published to be used editorially.
- To make taxonomies available on Sophora Staging Servers, they must be published.
- Published taxonomies can be set offline to remove them from Sophora Staging Servers
- A taxonomy can only be deleted if it is no longer referenced by any node type configuration.
Tags:
- Tags do not have individual publication states.
- Tags are always functionally published.
- Tags can only be accessed on staging servers if the parent taxonomy is published.
- Adding, updating or deleting tags does not affect the state of the taxonomy.
Migration-Guide for Taxo
Taxo has been available since Sophora 1.52 but underwent some restructuring starting with Sophora Server 6.5.0.
In earlier versions, tags were simple strings embedded directly within the taxonomy document. Adding a tag meant editing the entire taxonomy. These strings were also the content of a tagged document's tag-property.
Tags now are composed entities featuring a label, an ID, alternative spellings, types and individual audit information. A tagged document only contains the tag's ID, not its label. To resolve the label for a tag, a lookup in the taxonomy is required (similar to Select Values).
When upgrading to Sophora 6.5.0, an automatic migration extracts all tags from taxonomies and moves them to the new tag-store. Normally, a new tag receives a randomly generated ID. However, all migrated tags receive an ID identical to their label. This ensures that existing tagged documents do not have to be modified.
It can be challenging to simultaneously update all connected Sophora Clients to a version compatible with the new Tag-API. To mitigate this, the Sophora Server provides a compatibility mode, controlled by the taxo_legacy_mode_enabled property in the central configuration document (sophora.configuration.configuration). In Server-Version 6 the default is true.
As long the compatibility mode is enabled, new tags will have IDs equal to their label. This implies that tag labels can not be changed. Furthermore, all modifications to tag-properties of documents will be automatically added to the matching taxonomy.
The compatibility mode should be switched off, as soon as all relevant Sophora Clients are compatible with the Tag-API.
