Semantic Connector

Last updated on
5 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 "Semantic Connector"-module.

The Semantic Connector module is the central module that is needed to add external semantic services (PoolParty servers, GraphSearch instances, SPARQL endpoints) to your Drupal integration. The Semantic Connector is where you would configure your connection to a PoolParty server and through its API it allows interconnections between other PoolParty Drupal modules.

Table of contents:

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

Documentation for Server Administrators

This area offers documentation for the common tasks of a server administrator managing the Semantic Connector module.

Installation of the Module

Server Requirements

  • Make sure cURL is installed on your server.
    The Semantic Connector module uses cURL HTTP requests to communicate with its supported APIs (except SPARQL).
  • If you want to work with SPARQL-endpoints, the EasyRDF-library needs to be installed:
    • Install PHP 5.3 or newer
    • Download the EasyRDF library (http://www.easyrdf.org/downloads) and
    • add EasyRdf.php and all the other files and folders to "sites/all/libraries/easyrdf".

For further information on how to install Drupal modules, see https://drupal.org/documentation/install/modules-themes/modules-7.

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

Documentation for Content Managers

This area offers documentation for the common tasks of a content manager using the Semantic Connector module.

Working with Connections

Semantic Connector offers an overview over all the created connections to semantic services.

Access it at "admin/config/semantic-drupal/semantic-connector" (Configuration -> Semantic Drupal -> Semantic Connector), as shown below:

Semantic Connector Overview

For every connection to a PoolParty server following information is displayed in the overview:

  • A link to the PoolParty server instance
  • The installed PoolParty version (if a newer version, which brings additional features into the set of Semantic Drupal modules, is available, a notice will appear above the PoolParty connection)
  • Information about the PoolParty license (for authorized users; PoolParty 6.0+ required)
  • A list of projects available on the PoolParty server and their usages in Drupal modules

A set of modules using the Semantic Connector are already integrated into this list of connections. Thus you get an overview over all the connection-usages of the whole website.
The currently integrated modules are:

Adding / editing Connections
Most of the modules using the Semantic Connector have a built-in way to automatically create all the Semantic Connector connections they work with.

In case connection details have changed (e.g. the URL to the server or maybe
only its port), they can be altered directly in the Semantic Connector:

  • Click the "Edit" button next to the connection you want to alter and
  • change the appropriate data in the upcoming form.

You can also add a connection to a PoolParty server or SPARQL endpoint manually.

  • Use the action buttons on top of the overview page
    • "Add a PoolParty Server connection" and
    • "Add a SPARQL endpoint connection" and
  • save the upcoming form after filling in the server details.

Refreshing Server Details
Some details of PoolParty servers have to be stored inside Drupal for performance reasons, for instance the PoolParty- and GraphSearch-versions and a list of created projects in PoolParty.

Occasionally significant changes in PoolParty can occur, like creation / deletion of projects, refreshing the extraction model for a project for the first time or PoolParty updates.
In such cases it can become necessary to fetch this information again and update the connections accordingly:
Click on "Refresh server details" beneath the title of the respective PoolParty server.

Global Settings

As soon as more than one Drupal module using the Semantic Connector is installed, you can configure the way these modules interconnect.
Access their settings at "admin/config/semantic-drupal/semantic-connector/config" (Configuration -> Semantic Drupal -> Semantic Connector -> Configuration).

Version Checking
By default the Semantic Connector checks if the installed PoolParty and GraphSearch version (if available) behind a Semantic Connector connection are up to date.
It adds notices in multiple areas of the Drupal backend in case the Semantic Connector Drupal module provides additional functionality that is not yet supported by your PoolParty/GraphSearch version.
You are not forced to update the service immediately, the message is displayed simply for your information.
To disable it, open the "Notifications" tab and uncheck the "Service version checking" check box.

Global notifications
By enabling global notifications multiple checks regarding connected PoolParty services can be performed automatically. Selected Drupal users will then be informed in case any action has to be performed inside Drupal after a relevant change of a PoolParty taxonomy. These notifications are currently only provided as warning messages, which appear on every page for the selected user roles.
The interval of the checks can be set to "daily", "every 7 days" or "every 30 days". In case you want the notifications to additionally be sent to you by mail you can add a comma separated list of mail addresses here. Once a check detects a required action, the notification will appear constantly until the the specific action was performed. In case a notification is outdated but still gets displayed you can click the "Refresh the notifications" link to update all of the notifications. Here is an example of what such a global notification would look like:

Semantic Connector Notification

Global notifications can inform users about following required actions:

  • PoolParty licenses expiration: If a PoolParty license is about to expire in the next 14 days or is already expired this notification gets triggered. Please contact a PoolParty consultant in case you receive this notification by mistake or need more information on how to extend your license. With the expiration of the license all of PoolParty's APIs get inaccessible, which prevents the Semantic Connector module from working. 
  • Required extraction model updates (provided by the PowerTagging module): Whenever one of your connected PoolParty projects has a change, the "refresh it now" notification is displayed. This action will trigger the PoolParty "refresh extraction model" operation through the PoolParty API. By refreshing the extraction model the latest state of the PoolParty thesaurus will be using for extracting concepts during the Tagging process.
    Remark: You need to have refreshed the extraction model at least once on the PoolParty side in order for this to work.
  • Required retagging of content (provided by the PowerTagging module): Whenever one of your connected PoolParty projects had a change in its tree structure or new concepts were added, the "retag content" notification is displayed.
    Warning: the "retag content" action should be used with caution. If you have manually curated PowerTagging tags inside your content, these will be overwritten by a retagging of content! (manually curated tags will be lost)
  • Required taxonomy synchronizations (provided by the PoolParty Taxonomy Manager module): Whenever after synchronizing a PoolParty taxonomy with a Drupal taxonomy a concept has one of its labels changed or gets deleted inside PoolParty, the "sync now" notification is displayed. This action will update the Drupal taxonomy with the newest state of the connected PoolParty thesaurus.

Module interconnection / Term Click Destinations
Every time a PoolParty concept is displayed it is themed via the Semantic Connector.
You can choose between the following display options:

  • Plain text or
  • themed as link or
  • a dropdown menu of links
    to any of the areas of the website giving details about this specific concept.

This includes the following possibilities:

  • GraphSearch Page: A list of items fetched from GraphSearch with the concept already pre-selected
  • Smart Glossary Detail Page: The Smart Glossary detail page of the concept
  • Taxonomy Term Detail Page: The built-in Drupal detail page of the taxonomy term of the concept

For each of these possibilities you can choose wether to show it in the list of link destinations or not and select a default text for the link.
Additional configuration of these term destinations can be done inside the affected modules (e.g. for "Smart Glossary Detail Page" inside the related Smart Glossary configuration).

Overriding Connections

In some cases it might be useful to override connection details, e.g. when having two environments (development and productive), which work with different PoolParty servers / SPARQL endpoints. Without overriding the connections on filebasis they would have to be changed manually every time the DEV database gets updated with the latest productive state.
Overriding connections can be done in Drupal's "settings.php" file, which can be found on the server at "sites/default/settings.php" in most cases. At the end of the file add the "semantic_connector_override_connections"-key to the $conf array, followed by a key containing the ID of the connection you want to override (you can find this ID by looking at the URL in the browser when editing the Semantic Connector connection in the admin backend), followed by an array containing the properties to want to alter. This would look like the following code snippet:

$conf['semantic_connector_override_connections'][{ID of the SemanticConnector connection you want to override}] = array(
  'url' => '{DEV Poolparty server URL}',
  'username' => '{DEV Poolparty server username}',
  'password' => '{DEV Poolparty server password}',
  'title' => '{Title for the DEV PoolParty server connection}',
  'graphsearch_path' => '{DEV GraphSearch path}',
);

You don't have to provide all the properties, only the ones you would like to override the values for: The properties you can alter are:

  • "url": The URL of the connection
  • "username": The username that gets used when authenticating to the connection
  • "password": The password that gets used when authenticating to the connection
  • "title": The title that is displayed in the admin backend
  • "graphsearch_path": The Path to the GraphSearch instance. Normally the path is "GraphSearch" but there might be a case where this path has to be customized.

Help improve this page

Page status: No known problems

You can: