Step 2: Setting up the Taxonomy Connector
Connecting to a taxonomy in Taxonomy Space requires editing the Taxonomy Connector's JSON configuration file. These settings define your connection of Tridion Sites with a specific instance PoolParty Semantic Suite, which is available to you through Taxonomy Space.
Before you begin
Before beginning the connector setup process, be sure you have the following:
- A Taxonomy Space user account with the
ApiUserrole. - Access to the Taxonomy Connector Add-on package. It should be included with your installation media provided by RWS Customer Support.
- The NET Core Runtime version 6 installed on the host machine of the Content Deployer and on all Content Manager server machines where the connector will be used. Download the .NET Runtime for either Windows or Linux from the following location: https://dotnet.microsoft.com/download/dotnet-core/6.0
- For Content Delivery capabilities, a Content Deployer extension for the Tridion Integration Framework, called "Taxonomy Add-on" (
udp-deployer-taxonomy-extension), which has been added to the Content Deployer.
Procedure
- Upload the Taxonomy Connector's ZIP package to the Add-ons Service.
- Create a JSON configuration that includes appropriate settings for this connector and your environment. In particular, be sure of the following:
- Connector-level, project-wide configuration
-
The
configurationsection includes the following required details from the Taxonomy Space project overall:baseUrl-
The base URL to the Taxonomy Space instance that you received from RWS, which refers to your specific instance of the PoolParty Semantic Suite. Example:
https://rws.poolparty.biz/ projectId-
The identifier of a project in Taxonomy Space, such as
1E26021B-1C2E-0001-A0C3-17E0FDDD13B6 -
Note: The
projectIdcan also go in thenamespacesection that defines the related Category. When placed in anamespace, be sure to put this element inside its ownconfigurationsubsection). See also the related topic with example configurations. conceptSchemeUri- The URI of a concept scheme within the Taxonomy Space project, such as this sample scheme from PoolParty Semantic Suite: http://e-learning.poolparty.biz/cocktails/8d052dfc-44bf-4985-8ce3-4564570a161b
-
The specified concept scheme serves as the root for the full concept structure that will be available in Tridion Sites. In Content Manager, it maps to an external Category in the Taxonomies node (as defined in the
namespacessection. -
Note: The
conceptSchemeUrican also go in thenamespacesection that defines the related Category. In fact, if you are configuring the connector for multiple concept schemes, you must put eachconceptSchemeUriin the relatednamespacesection. When placed in anamespace, be sure to put this element inside its ownconfigurationsubsection). See also the related topic with example configurations. -
Important: Once this configuration is in use within a production environment, we strongly recommend that you do not change the concept scheme. Doing so can result in various undesirable side effects, such as broken keyword links.
useUserLanguage-
The language in which the connector should load concepts from a Taxonomy Space project.
The following values are possible:
UserLanguage— The connector will load concepts in the user's preferred language, as set for each user in the individual Content Manager user interfaces.PublicationLanguage— The connector will load concepts in the Publication's language, as set in the Publication's language settings (Properties > General > Language/Region). If no language is selected in the Publication, the language falls back to Taxonomy Space project's default language.PoolPartyProjectDefault— The connector will load concepts in the Taxonomy Space project's default language.
- Remember that this connector-level setting can be overridden by defining the Content Manager environment and Content Delivery environment(s).
- Namespace-level, taxonomy-specific configuration
-
The
namespacessection defines one or more taxonomies in Taxonomy Space and instructs Tridion Sites how to interpret the external content from Taxonomy Space. - You must define at least one namespace for the connector. Each namespace is associated with a single taxonomy, or concept scheme in Taxonomy Space, and becomes an external Category under the Taxonomies node in the Content Manager user interfaces.
- Each taxonomy namespace requires the following properties:
-
displayName- Identifies the taxonomy in the configuration file. We recommend that you set this to the same name you gave the stub Category in Content Manager. Unlike when used with multimedia connectors, this setting has no impact on the Content Manager user interface.
stubCategories- The Item URIs of one or more stub Categories where Content Manager will show the taxonomy's hierarchy of concepts.
- The stub Category is also used for internal representations of the external entities; however, these are not be visible to users. The security settings configured for the stub Categories will control user access to the concepts in the external taxonomy (within the related mount point/namespace).
-
Important: Although the
stubCategoriesproperty accepts an array of values, you should only configure one Category within a single namespace and Blueprint. If you are using the same connector configuration to support multiple BluePrints, then you can define multiple URIs in this property, one for each Category in the separate Blueprints. useFeature-
Identifies which ECL feature this connector uses. In this case, it is always set to "
Taxonomy" to indicate the connection to an external taxonomy.
- Content Manager configuration
-
The
sitesCmsection is present to enable the taxonomy in Content Manager. -
If the value for
useLanguagethat is set at the connector-level is not the preferred behavior for Content Manager, insert auseLanguageproperty within thesitesCmsection and set it to the value you want to use in Content Manager.PublicationLanguageis the default for a Content Manager environment and overrides the default setting for the connector overall, which isUserLanguage.Important: When theuseLanguageproperty for Content Manager is set to eitheruserLanguageorpublicationLanguage, you need to ensure that all concepts are translated into all the languages that you expect your Content Manager end users to use. If a concept is not translated into a user's language, Taxonomy Space will not return it to Tridion Sites, and therefore, it will not be shown in any lists in the Content Manager user interface. - Content Delivery configuration
-
There is a section for each Content Delivery environment that you want to be indexed and connected to Taxonomy Space.
- Be sure the property name is set to the environment's actual name (the sample configuration contains two sections called
stagingandlive). - If needed, include the
useLanguageproperty and set it touserLanguage. This property must beuserLanguagefor each Content Delivery environment (either because that is the default value ofuseLanguageat the connector level or because you explicitly set it in each Content Delivery environment section) in order for indexing to work.
- Be sure the property name is set to the environment's actual name (the sample configuration contains two sections called
Note: For details on additional, optional properties and an example configuration file, refer to the related reference topics. - Upload the connector's JSON configuration file to the Add-ons Service.
- Return to the Content Manager user interface (Content Manager Explorer or Experience Space) and select the Refresh option (or F5).
Taxonomy Space concepts from each configured concept scheme should now appear under the appropriate External Category.
The following screen capture illustrates a publication with a new External Category for an example taxonomy:
- If you are working in a Tridion Sites Cloud setup, then after using the connector in the development environment and deciding that is suits your needs, you can request that it be added to your production environment. Contact RWS Customer Support and ask them to deploy this connector in the environment. If you have a custom configuration file that you want to use, you can provide it to the Support team.
Results
After the Taxonomy Connector setup is complete. If you plan to use the Smart Tagging feature, proceed to the next step to configure your Schemas for that feature.
- Taxonomy Space to Tridion Sites mapping
The configuration file for the Taxonomy Connector includes how concept schemes from Taxonomy Space map to external taxonomies in Tridion Sites using the stub Categories that you create in Content Manager. - Example Taxonomy Connector configurations
The examples provided illustrate some different configurations of the Taxonomy Connector. - Additional Taxonomy Connector configuration properties
The configuration section of the Taxonomy Connector's JSON configuration file includes a number of optional and advanced settings, as supported by the Tridion Integration Framework .