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

  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
    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 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 useLanguage that is set at the connector-level is not the preferred behavior for Content Manager, insert a useLanguage property within the sitesCm section and set it to the value you want to use in Content Manager.

    PublicationLanguage is the default for a Content Manager environment and overrides the default setting for the connector overall, which is UserLanguage.

    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 useLanguage property and set it to userLanguage. This property must be userLanguage for each Content Delivery environment (either because that is the default value of useLanguage at the connector level or because you explicitly set it in each Content Delivery environment section) 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:

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