Tagging

Introduction

MatchPoint Tagging adds a powerful taxonomy feature to SharePoint. It provides a set of tools to administrate the metadata and to apply the metadata to SharePoint content. This results in better search, refinement and aggregation capabilities on the content of your SharePoint environment.

MatchPoint tags can be applied to following kinds of content and content-containers:

• Site collections and webs
• Document libraries and lists
• Folders and document sets
• List items and documents

This is a major difference compared to SharePoint Terms, that can not be applied to containers (webs, lists and folders) and thus support no real inheritance. For a detailed comparison between tags and terms, please view our blog post.

Tags are managed in a hierarchical structure and allow the use of central settings (e.g. tag permissions, inheritance behavior) as well as localized settings (folder settings) which specify the behavior of a tag group for a specific location within SharePoint. Tags are managed within a Tagging Service Application and can be imported using MatchPoint Timer Jobs.

Before tags can be applied on SharePoint content objects, these objects have to be enabled for tagging. This is implicitly done when the user opens the "Edit Tags Form" on a web or a list. During this activation process two columns of the type TagField are added to the list.

For information on how to prepare a SharePoint environment for the use of MatchPoint tags and how to create a tagging service application, please refer to the document MatchPoint Installation Guide. If MatchPoint is used without tagging functionality, corresponding functions will not be available.

Architecture

SharePoint Features

The tagging functionality of MatchPoint is only available, if:

• The feature Colygon.MatchPoint.Tagging.Service has been activated
  • A "MatchPoint Tagging Service Application" has been created
  • Tags have been imported
• The feature Colygon.MatchPoint.Tagging.Inheritance has been activated.
• The feature Colygon.MatchPoint.Tagging.Infrastructure has been activated.

Tag Model

A tag object has different properties that are used to identify the tag:

• For users, a tag is identified by its Name. This value does not have to be unique since it is possible that the same tag name is used in different positions within the tag hierarchy.
• Within configuration files, tags are identified by the combination of a tag provider and a tag key. The provider identifies a category of tags whereas the key identifies a single tag within that category.
• On SharePoint content, tags are identified by an ID that is assigned automatically when a tag is implemented. Therefore, this value is unique per tagging service application. It is used to store tag information on SharePoint content, as part of the tag string.

Tag Structure

Tags are keywords or terms which can be applied to SharePoint content. Tags are structured hierarchically:

Tag Group
    (Parent) Tag
        Tag

The number of levels is unlimited, meaning each tag group can have several child groups, etc. However there always has to be a tag group at the root of this structure. And it is not adviced to build a structure where a tag has a child tag group.

Only tags can be applied to SharePoint content, groups can not. However in search queries all types of tags can be used to search for SharePoint content.

Beside the hierarchical relationship of the tags there is also the possibility to define relations between tags. The hierarchical structure and the relations of the tags are defined in the tag importers (TagImporterConfiguration, StaticTagImporterConfiguration).

Taggable objects

Folder Settings

MatchPoint folder settings define how a container element (SPWeb, SPList or SPFolder) behaves regarding tags. Following settings can be defined:

• whether the container inherits folder settings from the parent container.
• how a tag group 'behaves' (visibility, required, inheritance);
• whether default tags are automatically applied to new items within the container.

Following table shows, how the folder settings can be accessed in the GUI:

Tag Permissions

For all tags, permissions can be defined which determine what users can see (read) or apply (write) the tag. Within a tag importer timer job, the tag configuration element can be configured with PermissionConfiguration elements. If no permissions are specified, any user can use the tag. Please note that you can use the expression engine to determine permissions dynamically, for instance depending on properties from the tag importer data source.

Tag Relations

Within the meta data model, relations between different tags can be specified. Relations are defined within a TagImporterConfiguration. Users can apply a tag to a SharePoint item and the related tags will be applied implicitly. When searching for content, the item will be found when searching for a related tag.

Tag Synonyms

Tags can be imported with synonyms in a TagImporterConfiguration using the SynonymExpression. Synonyms are language independent

Integration in SharePoint

Tagging Service Application

The MatchPoint Tagging Service Application is a SharePoint Service Application that can be created either via a PowerShell Cmdlet or in the central administration. Please see the installation guide for more information. The "Full Text Search"-feature needs to be enabled on the SQL Server.

Tag Columns

If a SharePoint list or document library is enabled for MatchPoint tagging, two columns are created on that list and added to all content types:

• The column MP_UserTags contains all tags that are applied directly to an item
• The column MP_InheritedTags contains tags that are inherited from a container element above the current item or element.

Tags are persisted within those columns encoded as a tag string. This string contains the tag store ID, the tag ID of the applied tag and the tag ID's of ancestor- and related tags. Tag columns are hidden; therefore the tag string is not visible to users. Within the SharePoint GUI, tags are displayed with custom control that provides find-on-type functionality and allows browsing the tag tree.

For document libraries and lists, tags are stored on the root folder. For SharePoint sites and site collections, tags are stored within the property bag of the SPWeb object.

The functionality for viewing/editing tags on the SharePoint content and for managing the folder settings integrates directly into the SharePoint UI (e.g. Edit-, New-, and Display form).

Managed Properties

The tag columns MP_UserTags and MP_InheritedTags are crawled by the SharePoint Search Service Application which allows index-based searches for tags. By default MatchPoint creates the managed property:

• MATCHPOINTTAGS

This managed property contains the tag strings of both user- and inherited tags. Refer to the content enrichment section for further configuration options.

Content Enrichment to allow Full Text Search and to improve native refinement

MatchPoint provides a mechanism to enhance SharePoint Search's support of MatchPoint Tags. This is done using a Search Content Enrichment Web Service, utilized by SharePoint during the crawl process. The Web Services allows splitting the MatchPointTags managed property to a multi value managed property MatchPointTagRefiners. Furthermore, Tag names can optionally be resolved and stored in the index to allow full text search queries against tags.

Splitting the tag string might be necessary to get correct native refiners for MatchPoint Tags, i.e. to allow SharePoint to count single tag occurrences instead of occurrences of entire tag strings.

Resolving tag names is optional. This can be configured in the Web Service's web.config file. For more information on how to use this feature, please refer to the Installation Guide.

Import and Manage Tags using MatchPoint Timer Jobs

Following timer job configurations related to the tagging functionality are available within MatchPoint.

• Static Tag Importer: imports a static structure of tags, specified within the configuration file.
• TagImporter: imports a structure of tags from a data source.
• TagInheritanceJobDefinition: updates child element tags of tagged containers (webs, folders)
• TagSynchronizer: updates the tag information on SharePoint content if tags are changed.
• TagCleanUp: removes deleted (deprecated) tags from the tagging service application.

For both the StaticTagImporter and the TagImporter, tags can be imported for multiple languages by using a TagNames configuration element. For more information on multi-language installations with MatchPoint, please refer to the Localization chapter.

Static Tag Import

The StaticTagImporterConfiguration is the most basic configuration for a tag importer timer job. It defines a fixed structure of tags that is imported without referencing an external system.

Within such a configuration file, any number of ImportProviderConfiguration elements can be defined. Such an element specifies a category of tags which are identified by an ID. Every tag that is imported needs to be configured with a tag provider.

A StaticTagConfiguration element represents a single instance of a tag. It itself can contain other StaticTagConfiguration elements (child tags).

Tag Importer

A tag importer timer job will import tags or tag relations from an external system. A configuration file can contain two kinds of elements:

• The TagImportProviderConfiguration element contains configurations for tag imports.
• The RelationImportProviderConfiguration element contains configurations for relation imports.

Each of these elements specifies a provider for the tags/relations that are imported. A tag provider is used to identify the data source.

Tag Inheritance

The Tag Inheritance feature provides automatic metadata tagging on SharePoint content. Tags that are applied on a SharePoint container element, such as a web, a list or a folder, are automatically applied on their descendant elements. This feature allows a fast and consistent classification of related content and makes it easy to find it. Changes and modifications on the inherited tags are also automatically updated on the descendant elements.

The inheritance of tags is triggered when tags are applied on the content objects. During this process a work item for a SharePoint timer job is scheduled, which ensures the inheritance of the tags. The SharePoint timer job is installed on the web application where the "MatchPoint Tag Inheritance" feature has been activated.

On lists and folders that contain less than 20 child elements, tags are inherited immediately without using the tag inheritance timer job.

The feature needs to be activated on web application scope level and has to be activated at least on one web application in order to make the Tag Inheritance feature working.

Tag Synchronizer

The TagSynchronizer timer job is used to update the tag string of SP elements. This is necessary if the tag model changes in a way that requires an update of tagged content:

• If tag relations that are written to the tag string have changed.
• If a tag changes its position within the hierarchy of the metadata model.

If the tag string is not updated, a search will return wrong (or missing) results. It is therefore recommended to configure and run a TagSynchronizer timer job if such changes might occur within the metadata model.

Tag Clean Up Job

As the metadata model changes over time, it is possible that tags are deleted. This could happen for instance if an external system (i.e. a database) no longer contains one specific dataset which was imported as a tag.

Since it is possible that there is still SharePoint content that is tagged with such a deleted tag, tags are not "deleted" from the database, instead they are only marked as deleted (deprecated). This means that users can still see the tag when searching for items or viewing the properties of a SharePoint object, but they cannot apply the tag anymore.

If a deleted tag has been removed from all content, the "deleted" tag can be safely removed from the tag database. This is done by the TagCleanUp timer job: The timer job executes a search for all content tagged with a "deleted" tag and removes this tag from the database if no results are returned.

Using Tags

Tags are applicable on several types of SharePoint content like Webs, Lists, Folders and List Items via the "Edit Properties Forms" or in the "Settings" pages of a web or list. Another way to apply tags on SharePoint content is the usage of the TagChoiceField in combination with the Form Web Part and the corresponding Data Adapter. Tags on MatchPoint Workspaces are applied with the help of the TagChoiceField in the Workspace Editor Web Part or with the Image Tag Web Part. In the Data Grid Web Part tags of the aggregated data are rendered by the TagColumn. The rendering of the tags of the aggregated data in the Composite Web Part can be accomplished with the usage of the methods of the ITagResultRecord interface and the TagExtensions class in the expressions of the appropriate Transformer.

It is possible to apply tags to multiple items at once. This can be done either directly within the SharePoint list / document library or within a MatchPoint Data Grid Web Part. MatchPoint will determine what tags are already applied to the selected content, including tags that are only applied to some of the selected items ("applied on some").

The applied tags are visible in the "Display Properties Forms" of the corresponding SharePoint content. In views of SharePoint lists the tags are displayed by the TagField or the TagGroupField, which displays only the tags of a configured tag group.

Filtering with Tags

In order to query content with tags use a Data Provider with a TagCondition in a Data Grid Web Part, a Composite Web Part or a Chart Web Part.

The results of a query are refinable by tags with the TagRefinementColumn in the Refinement Web Part or filterable with the TagColumn in the Data Grid Web Part.

The Search Definition Web Part provides a configurable TagSearchFilter, which allows building search definitions with tags.

When using the Form Web Part as search definition input form, tag conditions are defined with the TagChoiceField.

When searching with tags the hierarchical structure of tags and the relations between tags are taken into account in the conditions of a search query:

• Hierarchy: When a search query with a tag condition is executed, all content is found that has the tag itself or any descendant of that tag applied.
• Relation: If a relation exists between two tags, tag A (Source Tag) and tag B (Target Tag), and query with a tag condition on tag A is executed, all content is found that has tag A or tag B applied.

GUI Elements

Tag Group Fields

To display tags within a tagging-enabled document library or list, tag group fields can be used. A tag group field can be added to a list like any other SharePoint field column:

• Access the "Document Library Settings" page or the "List Settings" page.
• Within the "Columns" section, select "Create Column".
• Select the column type "MatchPoint Tag Group Field"
• Within the "Tag Group" section, select a root tag.

Tag Icons

Just as for SharePoint managed properties, icon mappings can be defined for all MatchPoint tags. For general information on icon mappings, please refer to Chapter 2, section "MatchPoint Configuration File". The following example shows how the XML for creating icon mappings for the "Organization" tag group and (recursively) for all child tags:

<Mapping Pattern="Organization" FileName="TagIcons/org.png" />
<Mapping Pattern="Organization/**" FileName="TagIcons/org.png" />

Favorite Tag Sets

Favorite tag sets can be used to quickly apply a collection of tags to a SharePoint item. They can be accessed directly within the "Edit Properties" form of the list item.

Favorite tag sets can also be centrally managed by selecting the Manage Favorite Tag Sets link on the Instance Administration site. They are stored within a hidden SharePoint list "FavoriteTagSet" on the Instance Administration site.

The Public property is only available for users that are allowed to publish favorite tag sets. These users can be specified within the MatchPoint configuration file.

The Scope parameter specifies a location within the SharePoint environment for which this favorite tag set should be available. Administrators can directly edit the scope whereas normal users have to select either "current container" or "global" for the scope.

Tags in expressions and configuration files

Both tags and folder settings can be accessed using the MatchPoint expression engine.

The Tag class represents the instance of a single tag and allows direct access to its attributes, i.e. the Name attribute returns the tag's name or the ProviderId attribute returns the tag's provider ID. Tag objects (or a collection thereof) will be returned by a number of methods both from the MatchPoint API and expression variables.

Within various configuration files, TagConfiguration elements can be used to specify one or more tags.

Another class that can be used to represent a tag is SimpleTag. This type only contains information that can be accessed directly from the tag string of a SharePoint object, without having to access the tagging service application. Likewise, a SimpleTagConfiguration class represents a simple tag within a configuration file.

The FolderSettings class represents the configured folder settings for a SharePoint container element.

The following extension methods are available for accessing tag-related functionality on SharePoint objects:

• TagExtensions
• SPListItemExtensions
• SPFolderExtensions
• SPWebExtensions
• SPListExtensions
• SPListItemVersionExtensions

PowerShell CmdLets

• Install-MPTaggingServiceInstance
• New-MPTaggingServiceApplication
• Ping-MPTaggingService
• Set-MPTagInheritanceJobSchedule
• Set-MPTagStoreId
• Uninstall-MPTaggingServiceInstance

Limitations

There are some limitations with terms:

• they cannot be edited in a SharePoint list's datasheet view
• they are not resolved when sent in auto-generated mails from SharePoint

See Also

• MatchPoint Tags vs. SharePoint Terms
• Edit Tags of a SharePoint Item using PowerShell