PowerShell CmdLet

General Information

MatchPoint provides a set of PowerShell CmdLets that can be used to access administrative functionality from the "SharePoint 2016 Management Shell". In least privilege scenarios these CmdLets have to be used for certain administrative tasks since the required permissions for these operations cannot be obtained automatically and therefore, the GUI elements for these actions are not available. The following sub-sections of this chapter describe the MatchPoint CmdLets and their functionality.

The PowerShell CmdLets described within this section may refer to functionality that is not part of this documentation. In that case, please refer to the document MatchPoint Technical Reference for more information.

Adding and Removing Managed Properties in the Search Service Application

If MatchPoint is installed within a SharePoint Server 2016 Server environment, the search functionality requires some custom managed properties to be created on the Search Service Application. These managed properties can be created (and removed) using the following CmdLets:

Add-MPManagedProperties

Parameters

• SearchServiceApplication specifies the search service application. Can be a GUID, a search application name or an instance of a SearchServiceApplication object.

Remove-MPManagedProperties

Parameters

• SearchServiceApplication specifies the search service application. Can be a GUID, a search application name or an instance of a SearchServiceApplication object.

Exporting Search Configuration (Managed Properties) for Importing in the SharePoint Online Search Service Application

If hybrid search functionality is configured for the web application that hosts MatchPoint and MatchPoint managed properties are added to Search Service Application (Cloud or standard) you need to populate those properties to SharePoint online Search Service Application. Use the following command to export the search configuration with the MatchPoint managed properties. The exported search configuration can be imported in the SharePoint Online Search Service Application. (See also Import-MPSearchConfiguration)

Export-MPSearchConfiguration

Parameters

• SPWebAppAddress specifies the local Web Application address that hosts MatchPoint Instance.
• OutputFilePath specifies the path to the output file where the exported search configuration is written.
• NamePrefixFilter (optional) specifies the name prefix for filtering the managed properties. The default value is 'MATCHPOINT'.

Import Search Configuration (Managed Properties) in the SharePoint Online Search Service Application

Use the following command to import the search configuration in the SharePoint Online Search Service Application. (See also Export-MPSearchConfiguration)

Import-MPSearchConfiguration

Parameters

• SPOUserLogin specifies full login for SharePoint Online tenant administrator.
• SPOUserPassword specifies password for SharePoint Online tenant administrator.
• TenantAdminUrl specifies address to SharePoint Online tenant administration page (e.g. https://companySite-admin.sharepoint.com).
• InputFilePath specifies the path to the input file which contains the search configuration to import.

Generating MatchPoint Hybrid Add-in package

Use the following command to generate MatchPoint Hybrid Add-in package.

Get-MPHybridAddInPackage

Parameters

• MatchPointInstanceWebAddress specifies address to the local web that hosts MatchPoint instance.
• OutputLocation specifies the pat to the output file - MatchPoint Hybrid Add-in package.

Adding and Removing MatchPoint Instance Associations

MatchPoint allows the assignment of multiple SharePoint web applications to one MatchPoint instance. These assignments can created and removed using either the GUI (see 5) or the following CmdLets:

Set-MPInstanceAssociation

Parameters

• InstanceSite specifies the MatchPoint Instance Administration site. Can be used with a GUID, a URL or a SPSite object.
• WebApplication specifies the web application, for which an association is created. Can be used either with the web application URL or with a SPWebApplication object.

Remove-MPInstanceAssociation

Parameters

• WebApplication specifies the web application, for which an association is created. Can be used either with the web application URL or with a SPWebApplication object.

Exporting and Importing SharePoint Webs

MatchPoint provides a mechanism to export existing site structures (including content) into a template. Exported templates can also be used with the MatchPoint provisioning template functionality. The following CmdLets are available:

Export-MPWeb

Parameters

• Web specifies the web that is to be exported. Can be an URL, a GUID or a SPWeb object.
• TargetDirectory specifies the file system path where the exported configurations should be stored.
• Recursive specifies whether sub-webs should be exported as well
• IncludeDocuments specifies whether to include documents (within document libraries) into the export.

Import-MPWeb

Parameters

• Lcid specifies the LCID of the new web.
• SourceDirectory specifies the file system path to the import configuration(s).
• Recursive specifies whether sub-webs should be exported as well.
• IncludeDocuments specifies whether to include documents (within document libraries) into the export.
• IsSiteCollection specifies whether the new web should be created as a site collection.
• TargetUrl specifies the target URL of the new web
• SiteName specifies the site title.

The export/import of documents is only supported from the PowerShell CmdLets. If an exported template that contains documents is used with MatchPoint provisioning templates, documents will be ignored.

Executing and Rescheduling MatchPoint TimerJobs

MatchPoint timer jobs are used i.e. to import tags and terms into your metadata model. They are executed as standard SharePoint timer jobs, yet they provide a simplified interface that allows the scheduling of timer jobs directly within the timer job configuration file. The following commands can be used to execute a MatchPoint timer job as a one-time SharePoint timer job or to schedule a timer job according to the configured schedule.

Execute-MPTimerJob

Parameters

• WebApplication specifies the MatchPoint Instance Administration site. Can be used either with the web application URL or with a SPWebApplication object.
• FileName specifies the file name of the timer job configuration file.
• Type specifies the configuration type name of the timer job configuration file

Reschedule-MPTimerJobs

Parameters

• WebApplication specifies the MatchPoint Instance Administration site. Can be used either with the web application URL or with a SPWebApplication object.

Publishing Provisioning Templates

Before a MatchPoint provisioning template can be used, it has to be deployed to the SharePoint farm. This deployment job can be triggered either within the MatchPoint Administration site or using the following CmdLet:

Publish-MPProvisioningTemplate

Parameters

• WebApplication specifies the MatchPoint Instance Administration site. Can be used either with the web application URL or with a SPWebApplication object.
• FileName specifies the file name of the provisioning configuration file.

Set Credential Store Master Key

MatchPoint allows the configuration of user credentials that can be used to access external systems. These credentials are stored within the MatchPoint configuration file, encrypted with a master key. The master key itself is stored within the Windows registry of the SharePoint server. It can be defined using the following CmdLet:

Set-MPMasterKey

Parameters

• Key
• WebApplication specifies the MatchPoint Instance Administration site. Can be used either with the web application URL or with a SPWebApplication object.

If your SharePoint farm consists of multiple servers, you need to set the credential store master key on each of the servers separately.

Administrating MatchPoint Tagging Service Applications

Create a new tagging service application

A tagging service application can be created either from Central Administration UI or by using the following command:

New-MPTaggingServiceApplication

Parameters

• DefaultLanguage The default language for the service application.
• Name Name of the service application.
• DatabaseServer Database server where MSSQL service is running.
• DatabaseName Name of the tag database.
• ApplicationPool Name of the application pool where the tagging service application will run.
• AnonymousAccessEnabled Whether anonymous access to the service application is allowed or not.

Pinging a tagging service application

If MatchPoint is installed with the tagging functionality, the tag metadata model is maintained within a "tagging service application". The following command allows pinging a tagging service application:

Ping-MPTaggingService

Parameters

• WebApplication specifies the web application of the MatchPoint Instance site
• TagStoreId specifies the ID of the tag store that should be pinged.

Setting the Tag Store ID of a tagging service application

Once a tagging service application has been created, the tag store ID of that service application can be changed with the following command:

Set-MPTagStoreId

Parameters

• TaggingServiceApplication specifies the MatchPoint tagging service application. Can be used with a SPServiceApplication object (PowerShell: Get-SPServiceApplication) or a GUID
• Id specifies the tag store ID.

After tag store id was changed, each tagging service needs to be restarted.

Please remember that the tag store ID is stored on any SharePoint content that is tagged with MatchPoint tags as part of the tag string. Therefore, the tag store ID must not be changed after content has been tagged with tags from that tag store.

Installing and uninstalling a Tagging Service Instance on Additional Servers

Per default, the tagging service instance is installed on every server in the SharePoint farm. The initial state of the service instance is "Stopped" in multi-server environments and "Started" in single-server environments. If the service instance needs to be installed or uninstalled on a server in the farm, the following commands can be used:

Install-MPTaggingServiceInstance

Parameters

• Server specifies the server where the tagging service instance should be installed. The local server is used if not specified
• Provision specifies whether the tagging service instance should be started on the server. If tagging service instance is installed on a different server than local server it is recommended to use "Provision". If "Provision" was omitted, the instance can be started from Central Administration (System Settings / Manage services on server).

Uninstall-MPTaggingServiceInstance -Server

Parameters

• ServerRemoves the tagging service instance from the specified server. The Server parameter is optional, if not specified the local server is used.

User Control Security Settings

Set User Control Restriction Level

The execution of any custom code that is deployed within an ASCX user control or a MatchPoint configuration file can be prevented by setting the user control restriction level with the Set-MPUserControlRestrictionLevel cmdlet. This cmdlet modifies the web.config file of the specified web application by adding an entry with the key MatchPoint.UserControlRestrictionLevel in the appSettings section.

Set-MPUserControlRestrictionLevel

Parameters:

• WebApplication The web application for which the user control restriction level needs to be set.
• Level The user control restriction level you would like to set.

Following options for the Level parameter are available:

• Unrestricted (default): ASCX files which are deployed to the server layouts directory and made available through the MatchPoint configuration SolutionPaths setting and all user controls specified in UserControlConfiguration configurations are available in the expression engine as expression variables. This is the default option if nothing is specified.
• LayoutsOnly: Only ASCX files which are deployed to the server layouts directory and made available through the MatchPoint configuration SolutionPaths are available as expression variable. All UserControlConfiguration configuration files are ignored.
• UserControlsDisabled: User controls cannot be used as expression variables. This is the most restrictive setting.

If no user control restriction level is set, the restriction level is Unrestricted.
When setting a restriction level, make sure that this setting exists on every front end web server, especially when adding a new server to the farm.

Remove User Control Restriction Level

If a user control restriction level was set with the Set-MPUserControlRestrictionLevel cmdlet, it can be removed with the Remove-MPUserControlRestrictionLevel cmdlet. This removes the entry in web.config file of the specified web application.

Remove-MPUserControlRestrictionLevel

Parameters:

• WebApplication The web application for which the user control restriction level needs to be removed.

RunAsConfiguration Element Security Settings

Set RunAsConfiguration Restriction Level

MatchPoint RunAsConfiguration element allows to configure another identity than the current to be impersonated in order to execute a specific operation. Users can be chosen from the credential store (a MatchPoint configuration with encrypted credentials and connections strings) or the system account which refers to the Application Pool account or the SharePoint system account. The use of the RunAsConfiguration element can be restricted by setting the run as restriction level with the Set-MPRunAsRestrictionLevel cmdlet. This cmdlet modifies the web.config file by adding a MatchPoint.RunAsRestrictionLevel key to the appSettings section.

Set-MPRunAsRestrictionLevel

Parameters:

• WebApplication The web application for which the run as restriction level needs to be set.
• Level The run as restriction level you would like to set.

Following options for the Level parameter are available:

• CurrentUserOnly: Only the current user can be chosen to execute a specific operation. This means that in fact no impersonation is possible at all. This is the most restrictive setting.
• CredentialStore: Only users from the credential store can be picked.
• Unrestricted (default): User from the credential store and system account (app pool account) can be picked. This is the default setting if nothing is specified.

If no run as restriction level is set, the restriction level is Unrestricted.
When setting a restriction level, make sure that this setting exists on every front end web server, especially when adding a new server to the farm.

Remove RunAsConfiguration Restriction Level

If a run as restriction level was set with the Set-MPRunAsRestrictionLevel cmdlet, it can be removed with the Remove-MPRunAsRestrictionLevel cmdlet. This removes the entry in web.config file of the specified web application.

Remove-MPRunAsRestrictionLevel

Parameters:

• WebApplication The web application for which the run as restriction level needs to be removed.