Setting up the auto-suggestion feature for adding tags in Enterprise 9
Info: This feature requires Enterprise Server version 9.1 or higher.
IMPORTANT: The legacy Open Calais will be discontinued on 31 August 2015 and is to be replaced by a new and improved Thomson Reuters Open Calais. This new version is not fully backward compatible with the legacy Open Calais and will require a few manual changes, a new API key and the OpenCalais plug-in of Enterprise Server 9.4.5 or higher. For information about upgrading from the legacy Open Calais to the new Thomson Reuters Open Calais, visit the Upgrade page on opencalais.com.
In the auto-suggestion feature, the content of a Publish Form field is sent to an external Suggestion Provider which scans the content and provides tags based on the content that is found. These tags are then returned to Content Station where the user can decide whether or not to include them in the article.
Note: The auto-suggestion feature is available when publishing content to a Web site that is based on Drupal 7 or Drupal 8.
Enterprise is shipped with the functionality of Suggestion Provider OpenCalais (made available through a Server plug-in) but you can also make use of other providers such as Zemanta. A Suggestion Provider is linked in Enterprise on Publication Channel level. It is possible to configure multiple providers in Enterprise, but only one provider can be used per Publication Channel.
Auto-suggested tags are treated by subject, referred to by OpenCalais as 'entities'.
Example: Entities can be countries, cities, people, movies, companies, and so on.
Adding a tag
In a Publish Form, tags need to be added in a specific field so that the publishing system (such as Drupal) knows that this data should be treated as tags.
Such a field is linked to a specific entity meaning that for that field tags of only that entity are suggested. The purpose of the field therefore is to only enter tags that are related to that entity (although a user is free to manually enter custom tags).
As a result, a Publish Form will therefore typically need multiple fields for adding keywords, each linked to its own entity and each one used for entering tags about a specific subject.
Example: A field that is linked to the entity "Cities" will only have city names suggested as tags.
Figure: A Publish Form showing multiple fields for adding keywords. Here, the Country field is linked to the Country entity; therefore, only country names are suggested. The Continent field is linked to the Continent entity and therefore only continents are suggested.
Tags are added to a field by clicking a suggested tag or by entering a tag manually.
How auto-completed tags are displayed
The functionality of displaying suggested tags is provided by a Drupal field of a special type named 'Autocomplete term widget (tagging)'. Such a field needs to be linked to an OpenCalais entity to make sure that only tags for that entity appear for that field. This is done by creating a Drupal vocabulary— one for each entity — and linking a vocabulary to the field.
Configuration steps to perform
Note: The following steps describe how to set up Enterprise for use with OpenCalais. In case another provider needs to be used, make it available by creating a custom Enterprise Server plug-in. Once this is done, follow step 4. Adding OpenCalais to the Publication Channel in Enterprise Server.
Steps in Enterprise Server:
Steps in Drupal:
Step in Enterprise Server:
Step 1. In Enterprise Server, access the Server Plug-in Maintenance page.
Click Server Plug-ins in the Maintenance menu or on the Home page.
All the newly available plug-ins that are found in the plug-ins folders are registered in the database. Similarly, any plug-ins that are no longer available are unregistered.
Note: In case many plug-ins need to be initialized, the process of opening the page can take a few moments. When the page is loaded, all registered plug-ins are displayed. Each plug-in indicates whether or not it needs to be installed and activated automatically.
Step 2. Locate the plug-in named OpenCalais Suggestion Provider.
This plug-in is deactivated by default as indicated by the red icon in front of the name.
OpenCalais Suggestion Provider
Step 3. Activate the plug-in by clicking its icon.
The icon should change to green:
OpenCalais Suggestion Provider
Step 1. In Enterprise Server, access the OpenCalais Maintenance page.
Step 1a. In Enterprise Server, click Integrations in the Maintenance menu or on the Home page. A page with all integrated services appears.
Step 1b. Click OpenCalais. The OpenCalais Maintenance page appears.
Step 2. Enter the API key as provided by OpenCalais.
Note: To obtain a key, visit www.opencalais.com. On the page that appears, click Request API Key in the top right corner and follow the steps on screen.
Step 3. Click Save.
Step 1. In Enterprise Server, access the Health Check page.
Step 1a. In Enterprise Server, click Advanced in the Maintenance menu or on the Home page. A page with all advanced Maintenance features appears.
Step 1b. Click Health Check. The Health Check page appears.
Step 2. At the bottom of the page, click Clear All.
Step 3. Only select the OpenCalais test.
Step 4. Click Test.
The test is executed and the result is displayed next to the test. It should display “OK”.
Note: If the test fails, an error is displayed together with instructions for solving it. Follow the instructions and then run the test once more.
Step 1. In Enterprise Server, access the Maintenance page for the Publication Channel that is used for publishing the content to the Web.
Step 1a. In Enterprise Server, click Brands in the Maintenance menu or on the Home page. A page with all Brands appears.
Step 1b. Click the Brand, followed by the Publication Channel.
Step 2. From the Suggestion Provider list, choose the OpenCalais Suggestion Provider.
Figure: The Suggestion Provider list on the Publication Channel Maintenance page.
Step 3. Click Update.
Step 1. In Drupal, add a vocabulary to the taxonomy by navigating to Structure > Taxonomy > Add vocabulary.
Step 2. For each vocabulary, enter a name and one of the following WoodWing Enterprise Suggestion Entities:
Note: For a detailed explanation of each Suggestion Entity listed below, see http://www.opencalais.com/documentation/calais-web-service-api/api-metadata/entity-index-and-definitions.
Example: When the SportsEvent Suggestion Entity is used and the scanned text contains the phrase "Tour de France", the tag "Tour de France" is extracted and used as a suggestion.
Step 3. Click Save.
Step 1. In Drupal, navigate to Structure > Content Types.
Step 2. Add a new field to a content type and use the following settings:
- Field type: Term reference
- Widget: Autocomplete term widget (tagging)
Step 3. Click Save.
The Field Settings appear.
Step 4. Scroll down to the Field Settings section and set the following settings:
- Define the maximum number of values that should be displayed.
Note: This is normally set to 'Unlimited'.
- From the Vocabulary list, choose the vocabulary that corresponds to the field type.
Example: If the field is to be used for entering keywords related to movies, choose a vocabulary that contains movie names.
Step 5. Click Save field settings.
Step 4. Import the content type in Enterprise Server:
Caution: When importing content types, any Publish Form templates that are already in the database are updated. This means that the content of existing Publish Form templates is replaced (but this can be beneficial when Publish Forms need to be updated).
Step 4a. In Enterprise Server, access the Drupal 7 Maintenance page.
- In Enterprise Server, click Integrations in the Maintenance menu or on the Home page. A page with all integrated services appears.
- Click Drupal 7. The "Import Content Types from Drupal 7" Maintenance page appears
Step 4b. Click Import to import the content types.
Note: Any errors that may occur during the import are displayed on the page.
Testing the setup
Suggestion Providers use complex (and clever) algorithms for analyzing text and subsequently providing suggested tags. The results can therefore be difficult to predict sometimes, so when possible it is advisable to compare the raw output from the Suggestion Provider with the tags displayed in Content Station.
It is also advisable to check if all selected tags in Content Station actually end up in the published article on Drupal.
Step 1. In Content Station, set up a Publish Form for publishing to Drupal and use a representative article from your production workflow for the text.
During this process, tags suggested by OpenCalais should automatically appear.
Step 2. Copy the text used in the Publish Form, paste it the online OpenCalais viewer on viewer.opencalais.com and have it analyzed.
Step 3. Compare the results with the automatically added tags in the Publish Form. If any differences exist, check your Drupal setup.
Step 4. Add some tags to the fields in the Publish Form by adding them manually or by selecting one or more suggested tags.
Step 5. Publish the article to Drupal.
Step 6. In the published article, check if all tags are present. If any differences exist, check your Drupal setup.
Troubleshooting: Why do fewer tags appear in the published article than have been added to a field in the Publish Form?
Example: 3 tags have been added to a field but only 1 is published.
This can occur when the 'Number of values' option for the Term Reference field in the Drupal content type is incorrectly set. (See Structure > Content types > Manage fields > Edit > scroll down to Social Field Settings.)