Advertising sustains the DA. Ads are hidden for members. Join today

On this page

PoolParty Taxonomy Manager for Drupal

Last updated on
7 September 2018

Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites

This is the documentation for the "PoolParty Taxonomy Manager" module.

Table of contents:

---------------------------------------------------------------------------------------

Documentation for Server Administrators

This area offers documentation for the common tasks of a server administrator using the PoolParty Taxonomy Manager module.

Installation of the Module

Server Requirements

You have to install and enable the following components:

Install and enable these first.
Afterwards install the most recent release of the "PoolParty Taxonomy Manager" module (see https://drupal.org/documentation/install/modules-themes/modules-7 for further information).

---------------------------------------------------------------------------------------

Documentation for Content Management System Administrators

This area provides documentation for the common tasks of a content manager using the PoolParty Taxonomy Manager module.

Creating a PoolParty Taxonomy Manager Configuration

To access the module configuration in the administration menu, click "Configuration" --> "Semantic Drupal" --> "PoolParty Taxonomy Manager".

The next page shows a list of all already created PoolParty Taxonomy Manager configurations with the possibility to edit or delete any of the existing configurations.
To add a new configuration click "Add a PoolParty Taxonomy Manager configuration" at the top.
Then complete the following two-step creation process:

Part 1: The Server Configuration Settings

Every PoolParty Taxonomy Manager configuration is connected to a single project on one PoolParty server.

To fill the list of projects with the ones ready for use, follow these steps:

  1. Select a name for the configuration. 
  2. Fill in all fields describing how to connect to the PoolParty server. 
  3. Select whether every taxonomy should be directly connected to a PoolParty project or to a concept scheme in an existing PoolParty project. In case you decide for "PoolParty project" you can skip the following step and directly click on the "Save and edit details" button now.
  4. If you selected "Concept Scheme" in the previous step, you have to select the PoolParty project containing the concept schemes now. To do so click on "Load projects". The list of projects below should now be filled and ready for you to select the project to use.
    Select the project and click "Save and edit details" to move to Part 2 of the creation of the new PoolParty Taxonomy Manager configuration.

Troubleshooting in case the project list stays empty:

  • Check if the API Server can be reached:
    • Click "Health Check".
  • If the connection can be established but the list of projects is still empty:
    • Make sure that the given user has the rights to view your preferred project in the PoolParty configuration.

Part 2: The Configuration Detail Settings

Your configuration has already been saved with default values for a variety of configuration options, which can be altered now.
To go back to Part 1 of the configuration click "Change the connected PoolParty server or project".

Note: Changing the server or project once content has already been tagged with this PoolParty Taxonomy Manager configuration is not advised and should only be done with great caution.

In the next step you can export taxonomies from Drupal to the PoolParty server or import a thesaurus from the PoolParty server to Drupal.

On the configuration page you can see up to two tables, one for potential synchronization candidates and one for already synchronized Drupal taxonomies (the second table will only appear after at least on Drupal taxonomy was synchronized before). Both of the tables share the same first three columns:

  • The first column shows all the existing Drupal taxonomies that can be exported to the PoolParty server.
  • The second column shows the operations for exporting, importing and updating taxonomies.
  • Depending on the selected taxonomy root level in the connection configuration the third column shows either the PoolParty projects on the PoolParty server or the concept schemes, which are stored in the connected PoolParty project.

The table of already synchronized Drupal taxonomies has two more columns:

  • Information about the last synchronization of the taxonomy containing start- and end-time of the synchronization process and the user starting the operation.
  • One column that states if the Drupal taxonomy needs to be synchronized. This is the case if inside the connected area of PoolParty a label was changed, one of the existing concepts was deleted or a new concept was added.

Configuration form

Export Drupal Taxonomy to PoolParty Server

To export an existing Drupal taxonomy, follow these steps:

  1. Open or create a new configuration page.
  2. Search in the interconnection table for the desired taxonomy in the left column.
  3. Click the "Export to PoolParty" link in the corresponding row.

This forwards you to the batch settings form:

Export batch settings form

The following options are available:

  • Title of the new concept scheme / project: The name of the new concept scheme or project, in which the terms will be inserted as concepts
  • Map the Drupal languages with the PoolParty project languages: Here you can map the languages between Drupal and the PoolParty project languages.
    All non-mapped languages will not be transferred.
  • Taxonomy terms per request: This options controls the number of taxonomy terms, that are processed during one HTTP request. (Allowed value range: 1 - 100). The higher this number, the less HTTP requests have to be sent to the server until the batch finished exporting all your terms. This results in a shorter duration of the export process.
    Setting these numbers too high can result in a timeout, which will break the whole export process.

Start the batch job by clicking "Export taxonomy" in this form.
Note: Do not close your browser as long as the progress bar has not reached 100% to signify the successfully finished process.
You will be informed about the result of the export process as soon as it has been finished.

Before the batch process is started, the selected taxonomy will be verified and adapted:

  • The translation mode of the taxonomy will be changed to "Translate", if it is not already set, if these conditions are fulfilled:
    • If the sub-module "Taxonomy Translation" from the "Internationalization" module is enabled and
    • you mapped more than one language.

In a final step the connection between the taxonomy and the PoolParty project will be saved.

Import Thesaurus from PoolParty Server to Drupal

To import a thesaurus from the PoolParty server, follow these steps:

  1. Open or create a new configuration page.
  2. Search in the interconnection table for the desired concept scheme / project in the right column.
  3. Then click on the "Import into Drupal" link in the corresponding row. 

This will forward you to the batch settings form, where the following options are available:

  • Name of the new taxonomy: The name of the new taxonomy, in which the concepts will be inserted as terms
  • Map the Drupal languages with the PoolParty project languages: Here you can map the languages between Drupal and the PoolParty project languages.
    All non-mapped languages will not be transferred.
  • Preserve old concepts: If the concepts get imported into an existing taxonomy, taxonomy terms which can't be matched by URI or label normally get deleted. By checking "Preserve old concepts" instead of deleting them they get moved under a special concept named "Freeterms" without a URI.
  • Select the properties that will be saved in addition to the taxonomy terms: Here you can select additional properties fetched from PoolParty and saved to the taxonomy terms resembling concepts in case you want to make use of them. Available properties are:
    • Alternative labels: An alternative lexical label for a resource.
    • Hidden labels: A lexical label for a resource that should be hidden when generating visual displays of the resource, but should still be accessible to free text search operations.
    • Scope notes: A note that helps to clarify the meaning and/or the use of a concept.
    • Related concepts: Concepts with an associative semantic relationship to the concept.
    • Exact matches: skos:exactMatch is used to link two concepts, indicating a high degree of confidence that the concepts can be used interchangeably across a wide range of information retrieval applications.
  • PoolParty concepts per request: This options controls the number of concepts, that are processed during one HTTP request. (Allowed value range: 1 - 100). The higher this number, the less HTTP requests have to be sent to the server until the batch finished exporting all your concepts. This results in a shorter duration of the export process.
    Setting these numbers too high can result in a timeout, which will break the whole export process.

Start the batch job by clicking "Import taxonomy" in this form.
Note: Do not close your browser as long as the progress bar has not reached 100% to signify the successfully finished process.
You will be informed about the result of the import process as soon as it has been finished.

Before the batch process starts, a new taxonomy will be created.
The translation mode of the taxonomy will be set to "Translate", if these conditions are fulfilled:

  • The sub-module "Taxonomy Translation" from the "Internationalization" module is enabled and
  • you mapped more than one language.

Otherwise the translation for this taxonomy is disabled. In a final step the connection between the taxonomy and the PoolParty project will be saved.

Update/Sync Taxonomy from PoolParty Server

To update/sync an existing Drupal taxonomy, follow these steps:

  1. Open a configuration page.
  2. Search in the interconnection table for the desired taxonomy in the left column.
  3. Click on the "Sync from PoolParty" link in the corresponding row.

This forwards you to the batch settings form:

  • Map the Drupal languages with the PoolParty project languages: Here you can map the languages between Drupal and the PoolParty project languages. All non-mapped languages will not be updated.
  • Select the properties that will be saved in addition to the taxonomy terms: Here you can select additional properties fetched from PoolParty and saved to the taxonomy terms resembling concepts in case you want to make use of them. Available properties are:
    • Alternative labels: An alternative lexical label for a resource.
    • Hidden labels: A lexical label for a resource that should be hidden when generating visual displays of the resource, but should still be accessible to free text search operations.
    • Scope notes: A note that helps to clarify the meaning and/or the use of a concept.
    • Related concepts: Concepts with an associative semantic relationship to the concept.
    • Exact matches: skos:exactMatch is used to link two concepts, indicating a high degree of confidence that the concepts can be used interchangeably across a wide range of information retrieval applications.
  • PoolParty concepts per request: This options controls the number of concepts, that are processed during one HTTP request. (Allowed value range: 1 - 100). The higher this number, the less HTTP requests have to be sent to the server until the batch finished exporting all your concepts. This results in a shorter duration of the export process.
    Setting these numbers too high can result in a timeout, which will break the whole export process.

Start the batch job by clicking "Synchronize taxonomy" in this form.
Note: Do not close your browser as long as the progress bar has not reached 100% to signify the successfully finished process.
You will be informed about the result of the update process as soon as it is finished.

Before the batch process starts, the selected taxonomy will be verified and adapted:

The taxonomy's translation mode will be changed to "Translate", if it is not already set, if these conditions are fulfilled:

  • The sub-module "Taxonomy Translation" from the "Internationalization" module is enabled
  • You mapped more than one language.

The batch process itself will pass 4 steps:

  • Updating existing terms: Only changed concepts on the PoolParty server side are updated.
  • Creating new terms: New concepts on the PoolParty server side are added to the Drupal taxonomy.
  • Deleting terms: All deleted concepts on the PoolParty server site are deleted from the Drupal taxonomy also.
  • Adapting tree structure: All changes to the tree structure of the vocabulary are also applied to the Drupal taxonomy.

Make an existing PowerTagging taxonomy a synchronized taxonomy

When using the PowerTagging module to tag content with the concepts of a PoolParty project, the Drupal taxonomy used by the PowerTagging configuration is connected to a PoolParty project but only contains the minimum information required by the PowerTagging module. For example it doesn't use any hierarchy at all. To make such a Drupal taxonomy a completely synchronized taxonomy in terms of the PoolParty Taxonomy Manager an additional operation "make complete taxonomy" is available for applicable taxonomies in the table of potential interconnections between the Drupal taxonomies and PoolParty projects.

The "make complete taxonomy" operation internally works a little bit different than the normal "Sync from PoolParty" operation, but configuration-wise it looks almost the same. For more information on the configuration have a look at section Update/Sync Taxonomy from PoolParty Server above.

Disconnect from PoolParty Project

To disconnect an existing Drupal taxonomy from a PoolParty project, follow these steps:

  1. Search for the desired taxonomy in the left column.
  2. Click the "Disconnect from PoolParty" link in the corresponding row.

This forwards you to the confirmation form.
Note: The selected taxonomy has to have to be either imported or exported in advance.

To delete the connection between the taxonomy and the PoolParty project, click "Disconnect taxonomy" in the confirmation form.
The taxonomy itself will be retained in both the Drupal system and the PoolParty system.

Suggest free-terms as new PoolParty concepts

If module PowerTagging is used for content tagging and the extraction of free-terms or manual tagging is enabled, there will be taxonomy terms in the  Drupal taxonomy, which are not available in the PoolParty thesaurus. In case you would like to improve your PoolParty thesaurus over time, it might be helpful to suggest the most frequently used custom tags as new PoolParty concepts. Suggested concepts can then be approved or denied inside PoolParty.

The suggestion of new PoolParty concepts can be done in the "Suggest Concepts" area, available at "Configuration" -> "Semantic Drupal" -> "PoolParty Taxonomy Manager" -> "Suggest Concepts". For every PowerTagging configuration there will be an entry in the list containing following information:

  • Basic information about the PoolParty configuration used
  • The fields this PowerTagging configuration is being used for
  • Number of free-terms: The number of tags, which are not available in PoolParty as concepts and have not yet been suggested as new concepts
  • Number of pending suggestions: The number of tags, which are not available in PoolParty as concepts yet but have already been suggested as new concepts -> If a concept suggestion gets denied, it will become a normal free-term again.

If there are any free-terms available, which have not yet been suggested as concepts, the "Suggest Concepts" operation is available for that PowerTagging configuration at the right side of the table, leading to a searchable and filterable list of free-terms. By selecting one or more tags in the list and clicking the "Suggest"-button below the table the batch job of the concept suggestion will be started. Suggested free-terms, which are currently pending in the PoolParty concept creation lifecycle, will be displayed in a separate list below the tag selection list.

Help improve this page

Page status: No known problems

You can: