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 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

  1. Upload the Taxonomy Connector's ZIP package to the Add-ons Service.
  2. 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.
    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).
    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.

    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.
  3. Upload the connector's JSON configuration file to the Add-ons Service.
  4. 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.