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
ApiUser role.
- 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 3.1 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 Core Runtime for either Windows or Linux from the following location: https://dotnet.microsoft.com/download/dotnet-core/3.1
- 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
configuration section 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
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
namespaces section.
-
Note: The conceptSchemeUri can also go in the namespace section that defines the related Category. In fact, if you are configuring the connector for multiple concept schemes, you must put each conceptSchemeUri in the related namespace section. When placed in a namespace, be sure to put this element inside its own configuration subsection). For an example, refer to the related topic.
-
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
- A Boolean value (true/false) that indicates whether concepts should be presented in the user's language (value
true) or should instead always use the default language (false).
-
Remember that this connector-level setting can be overridden by defining same property in the Content Manager environment and Content Delivery environment(s).
-
Namespace-level, taxonomy-specific configuration
-
The
namespaces section 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 stubCategories property 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
sitesCm section is present to enable the taxonomy in Content Manager.
If the value for useUserLanguage that is set at the connector-level is not the preferred behavior for Content Manager, insert a useUserLanguage property within the sitesCm section and set it to the value you want to use in Content Manager.
Important: Whether you override this setting or not, if the effective value of this property is true for Content Manager, be sure 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
staging and live).
- If needed, include the
useUserLanguage property and set it to true. This property must be true for each Content Delivery environment either because that is the default value of useUserLanguage at the connector level, or because you explicitly set it in each Content Delivery environment section. Content Delivery environments require that the property is set to true in order for indexing to work.
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:
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.