Additional Installation Steps

Restart SharePoint TimerJob Service and IIS

MatchPoint's timer job engine uses functionality of the SharePoint TimerJob service. Therefore, after the solution files have been deployed, the service has to be restarted:

net stop sptimerv4
net start sptimerv4

This has to be repeated after a MatchPoint update was applied to the system and whenever custom solutions are deployed/upgraded that use the MatchPoint API.

Also, it is recommended to restart the IIS after solutions have been deployed or upgraded on every frontend server:

iisrest

After the MatchPoint managed properties have been created, it is required to restart the IIS.

Create a Tagging Service Application

If you plan on using the tagging functionality of MatchPoint in your SharePoint environment, you have to create a "Tagging Service application". This service application provides access to the tag metadata model.

The Tagging Service application can either be created by using the command New-MPTaggingServiceApplication (see "Administrating MatchPoint Tagging Service Applications" in the "PowerShell CmdLets"-section for detailed description) or by using the Central Administration:

1. Navigate to the central administration site of your SharePoint farm.
2. Select "Application Management" and "Manage Service Applications".
3. Select "New" and "MatchPoint Tagging Service Application".
4. Specify the parameters for your service application according to the requirements of your SharePoint environment.

If a timeout exception occurs during the provisioning of a tagging service application ("The timeout period elapsed prior to completion of the operation or the server is not responding. ALTER DATABASE statement failed"), the following SQL command can be used:
ALTER DATABASE [MatchPointDataBase] SET READ_COMMITTED_SNAPSHOT ON
Afterwards, please repeat the configuration of a tagging service application.

Create Additional Web Application Associations

If your SharePoint farm contains more than one web application and if you plan on using MatchPoint for these additional web applications, you need to add them to your MatchPoint instance.

Naturally, if you use MatchPoint functionality on multiple web applications, you have to ensure that the MatchPoint solutions are deployed to each of these web applications. You can use both the MatchPoint Installer or the manual installation to do this. If you are using the Installer, please only select the installation options "Install Tag Inheritance" and 'Install Server Infrastructure'.
Please note that you have to create the instance associations BEFORE deploying the feature "Colygon.MatchPoint.Server.Infrastructure".

To create a web application association, please open the Manage MatchPoint Configurations form, either from the MatchPoint Instance Administration site or by pressing Ctrl + M on any MatchPoint enabled site. Select the button Web Application Associations:

Here you can select any web application within your farm and create an association to the current MatchPoint instance:

In a SharePoint least privilege environment, the "Add Web Application" button is not available within the SharePoint GUI. Instead you need to create web application associations using a PowerShell CmdLet.

Configure Logging and Exception Handling

SharePoint ULS log

MatchPoint uses the SharePoint ULS logging mechanism. To configure logging, please navigate to your farm's central administration site, select "Monitoring" and "Configure diagnostic logging". Within the "Event Throttling" section you can configure the logging level for the various features of MatchPoint.

It is strongly recommended to select MatchPoint's logging level according to the application scenario. For productive environments it is suggested to use the log level 'Error' to avoid performance impacts.

Create Event Log Source

If you used the MatchPoint installer (automated installation), the event log source "MatchPoint" should already exist and you can skip this chapter.

In order to log to the Windows event log you have to create an event log source called "MatchPoint". A PowerShell Command can be used to create the source. Open the SharePoint Management Shell and enter:

New-EventLog -Source MatchPoint -LogName MatchPoint_Log

The source has to be created on every web front-end and application server of the SharePoint farm.

Error Codes

When an error, warning or info is logged try to identify it using the tables below. If the issue could not be resolved by following the instructions, please contact your MatchPoint solution partner for further assistance.

Debugging Settings

MatchPoint implements the following "default" exception handling mechanism:

If an exception occurs within a MatchPoint control (i.e. a Web Part) this control will display only the exception message to the end user. The full stack trace is available within the SharePoint ULS log (if the trace level has been configured accordingly). That way, end users are not confused with detail information in case an exception occurs. For debug scenarios, the stack trace can be enabled for a web application within the web.config file:

<configuration>
  <!-- ... -->
  <appSettings>
    <add key="MatchPoint.ShowCallStack" value="true" />
  </appSettings>
</configuration>

The following setting controls whether the expression text (debug hint) is included in the exception message when the evaluation of an expression fails. When set to true the text of the failing expression is included in the exception message. By default the details of the failing expression is not shown (false).

<configuration>
  <!-- ... -->
  <appSettings>
    <add key="MatchPoint.ShowExpressionDebugHint" value="true" />
  </appSettings>
</configuration>

Configure Self Service Site Creation

If MatchPoint Workspace is used to create sites or site collections, self-service site creation has to be enabled for all web applications that use this functionality:

$webApp = Get-SPWebApplication -Identity <WebAppUrl>
$webApp.SelfServiceSiteCreationEnabled = $True
$webApp.Update()

<WebAppUrl> is the URL of the web application which uses MatchPoint Workspace.

Add MatchPoint Search Content Enrichment Web Service

MatchPoint provides a mechanism to enhance SharePoint Search's support of MatchPoint Tags. The Web Services allows splitting the MatchPointTags managed property to a multi value managed property which results in more accurate/better refiner results. Furthermore, Tag names can optionally be resolved and stored in the index to allow full text search queries against tags. This feature is described in detail in the Tagging chapter in the concepts section.

The MatchPoint Search Content Enrichment Web Service can only be installed when you have a SharePoint Server Enterprise Edition, since Custom Content Enrichment ("Extensible content processing") is a feature of SharePoint Server Enterprise Edition.

To use this feature the following steps are required on your SharePoint environment:

• Modify the managed property MATCHPOINTTAGS by setting "Allow Multiple Values" to true
  Add-MPContentEnrichmentManagedProperties -SearchServiceApplication "<NameOfSSA>" -CreateMatchPointTagRefiners

• Optionally: Create a searchable, multi value managed property called MATCHPOINTTAGNAMES of type TEXT (note that MATCHPOINTTAGNAMES is optional here and working only, when it is activated in the web.config by setting ResolveTagNames to true!) Add MATCHPOINTTAGNAMES managed property
  Add-MPContentEnrichmentManagedProperties -SearchServiceApplication "<NameOfSSA>" -CreateMatchPointTagNames

• Deploy the MatchPoint SearchContentEnrichment Web Service to a WebServer that is part of your SharePoint Farm (the general deployment of a WCF service is described here):
  1. Optionally: Create a new application pool
     Please be aware that anonymous access has to be enabled!
  2. Optionally: Create a new site
  3. Create a new application in a site of your choice
  4. Extract the "Colygon.MatchPoint.SearchContentEnrichment.zip" to the directory of the newly created application
  5. Verify that the service is deployed correctly by accessing: http://<hostname>:<port>/<applicationAlias>/MatchPointContentEnrichmentService.svc Note that you may need additional (read) permissions to the service with the account you're currently logged in, else you may get an access denied page.
     If you want to resolve tag names the application pool user requires at least the following permissions/roles:

     • "SPDataAccess" role on the "SharePont Configuration" database
     • "SPDataAccess" role on the "SharePoint Content" database (where the "MatchPoint Instance" site collection is stored)
     • "Read Access" on the MatchPoint Tagging Service Application
• Adjust the web.config of the web server according to your needs:

  <configuration>
    <!-- ... -->
    <appSettings>
      <!-- ... -->
      <add key="MatchPoint.Instance.URL" value="http://<hostname>/<MPInstance>" />
      <add key="ResolveTagNames" value="false" />
      <add key="CreateTagRefiners" value="true" />
    </appSettings>
    <!-- ... -->
  </configuration>
  

  • MatchPoint.Instance.Url: the Url of the MatchPoint instance (i.e. the result of MPUtility.GetMatchPointInstanceUrl())
  • ResolveTagNames: whether the web service should resolve tag names to e.g. allow fulltext search for tags
  • CreateTagRefiners: whether the splitted tags should be written to the MATCHPOINTTAGREFINERS. This is true by default.

    You might also want to adjust the location of the log file and the log level, according to your needs. Note that the application pool user needs write access to the log file path.

• Register the web service in the SharePoint Search

  $config = New-SPEnterpriseSearchContentEnrichmentConfiguration
  $config.Endpoint = "http://<hostname>/MatchPointContentEnrichmentService.svc"
  $config.InputProperties = "MATCHPOINTTAGS"
  # note that the trigger condition is optional here; it is used to avoid unnecessary calls
  # to the service. In this example the service is called when an item has tags:
  $config.Trigger = "!(IsNull(MATCHPOINTTAGS))"
  # note that MATCHPOINTTAGNAMES is optional here and working only,
  # when it is activated in the web.config by setting ResolveTagNames to true!
  $config.OutputProperties = "MATCHPOINTTAGREFINERS", "MATCHPOINTTAGNAMES"
  $config.SendRawData = $false
  $ssa = Get-SPEnterpriseSearchServiceApplication
  Set-SPEnterpriseSearchContentEnrichmentConfiguration -SearchApplication $ssa
                                                       -ContentEnrichmentConfiguration $config
  

• Start a full crawl

SharePoint Search Center with MatchPoint Tags

As of MatchPoint 4.0.10 it is possible to show MatchPoint Tags in the SharePoint Search Center. This includes showing an item's Tags in the HoverPanel as well as a Refiner for Tags. To use this feature, the following prerequisites are necessary:

• MatchPoint version >= 4.0.10
• A site with SharePoint Enterprise or Basic Search Center
• MatchPoint Content Enrichment Web Service
  • MATCHPOINTTAGREFINERS
  • (optional) MATCHPOINTTAGNAMES with an alias "Tags" and configured as Queryable (to be able to search Tags)

To use this feature, following steps have to be performed:

• Activate "MatchPoint Enterprise Search Center Integration"-feature on the Search Center site (Colygon.MatchPoint.Server.EnterpriseSearchCenter)
• Execute Add-MPResultTypes -Web <SearchCenterSite> CmdLet to reference MP display templates
• Update Result Types on the Search Center site (Site Settings > Manage Result Types)
• Add tag refiner (Edit Page > Refiner Web Part Properties > Choose Refiners)
  • Property: MATCHPOINTTAGREFINERS
  • Display Template: MatchPoint Tag Refinement

Groups can be configured in the filter template (Display Templates > Filters > edit the options-object in Filter_MPTags.html > Publish).

For more information on Search Center customization please refer to MSDN.

Allow Searching for Tags containing stopwords or noisewords

In case you are using special characters in tag names, tag lookup fields will not behave as expected, i.e. they won't find the tag you are searching for. Since MatchPoint uses SQL fulltext queries to lookup tags, this can be fixed by adjusting or creating a SQL fulltext stoplist and associate it with the "TagName" table. Refer to the MSDN article Configure and Manage Stopwords and Stoplists for Full-Text Search for instructions on how to create and use a stoplist.

Note that after changing a stopwords list, a rebuild of the full text index is required. This is done by right clicking the "TagName" table and choosing "Full-Text index --> Start Full Population / Start Incremental Population".

Execute a Full Crawl on the Search Service Application

Depending on your application scenario and whether you created managed properties during the installation process, it might be required to execute a full crawl on the search service application.

$contentsource = Get-SPEnterpriseSearchServiceApplication | Get-SPEnterpriseSearchCrawlContentSource
$contentsource.StartFullCrawl()

This step should not be required in most environments. However, if you are experiencing problems with search related functionality after adding the managed properties, a full crawl will rebuild the SharePoint search indices and thereby fix the problem.

Install the MatchPoint MUI Package

If you are using MatchPoint in a multi-language SharePoint environment, you need to install the MatchPoint MUI package. It is currently available for the following languages:

• German
• French
• Italian

To install the package using the installer application, ensure that Colygon.MatchPoint.MUI.wsp is located in the installation directory before starting the installed. To install the package manually, please add the Colygon.MatchPoint.MUI.wsp solution file to your solution store and deploy it globally:

Add-SPSolution -LiteralPath C:\Colygon.MatchPoint.MUI.wsp
Install-SPSolution -Identity Colygon.MatchPoint.MUI.wsp

After the solution has been installed, the UI elements of MatchPoint will display any text information that is visible to "end users" either in the language that is configured as the default language of the system or in the language the user has selected as his/her display language.

Activate MatchPoint Features

Depending on your application scenario, you might need to activate different MatchPoint features within your SharePoint farm. The following features (with scope site collection or web) are available after you have completed the installation of MatchPoint:

• Colygon.MatchPoint.Core.WebParts
• Colygon.MatchPoint.WorkflowKit
• Colygon.MatchPoint.Workspace
• Colygon.MatchPoint.Tagging.Infrastructure
• Colygon.MatchPoint.Provisioning.SaveSiteAsTemplate
• Colygon.MatchPoint.Server.PageLayouts
• Colygon.MatchPoint.Server.SendTo
• Colygon.MatchPoint.Server.WebParts

Please refer to Architecture Planning for a description of the functionality of those features.

Modify the web.config File

If you are using inline code within ASP.Net pages (ASPX) or within custom user controls (ASCX), you have to modify the web.config file of any web applications where you use this functionality:

Using Assemblies

Depending on the usage of standard Microsoft/SharePoint classes within inline code, it might be required to add assemblies to the following configuration section:

/Configuration/system.web/compilation/assemblies

<add assembly="System.Core,
     Version=3.5.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089" />

The System.Core assembly contains functionality for using Linq extensions. If Linq is used within custom code, the assembly has to be added as shown in the example. Naturally, any other assemblies that are used have to be added as well.

Compilation Settings

For compiling inline code, please specify following settings within the /Configuration/ section:

<compiler language="c#;cs;csharp" extension=".cs"
  type="Microsoft.CSharp.CSharpCodeProvider, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
  warningLevel="4">
  <providerOption name="CompilerVersion" value="v3.5" />
  <providerOption name="WarnAsError" value="false" />
</compiler>