MatchPoint Snow Powershell Essentials

In a previous post, we did show you how to use MatchPoint and Powershell. Based on that article, we're taking matters a step further in this article: How to use Powershell to manipulate MatchPoint Snow workspaces.

Date: 22. Nov 2017

Instantiating the MatchPoint Instance Scope is also a requirement when it comes to MatchPoint Snow interactions.

From that starting point, let's work on a couple of potential administrative tasks:

Basic example: Update a particular workspace

Let's assume that you have a MatchPoint instance at http://sharepointsite/admin and need to change the description of the workspace that is to be found at URL http://sharepointsite/Workspaces/WS_000015. We then might use the following script to achieve the given task:

$TargetInstanceUrl = "http://sharepointsite/admin"
$TargetWorkspaceUrl = "http://sharepointsite/Workspaces/WS_000015"
$NewWorkspaceDescription = "This is the new workspace description"

# Start MatchPoint Scope Init
$web = Get-SPWeb -Identity $TargetInstanceUrl
$mpInstance = New-Object -TypeName Colygon.MatchPoint.Core.MPInstance $web
$mpInstanceScope = New-Object -TypeName Colygon.MatchPoint.Core.MPInstanceScope $mpInstance
# End MatchPoint Scope Init

$ws = New-Object -TypeName Colygon.MatchPoint.Workspaces.Model.Workspace $TargetWorkspaceUrl
$ws.Description = $NewWorkspaceDescription
$ws.Update()

As you see from the above code, getting the MatchPoint Workspace object (in the example: $ws) is quite straightforward, once the MatchPoint Instance Scope is in place. It's important to know and remember that validating and saving any changes to a MatchPoint Snow Workspace is being done using the workspace objects' Update() method.

Create a workspace

A typical migration task, especially when first installing MatchPoint Snow, might be the initial creation of Workspaces. For the creation of workspaces, we do need to provide the workspace template object to be applied for workspace creation.

There are some potential pitfalls and errors you may encounter during the workspace creation with Powershell, due to the absence of an HTTP context in Powershell. This means that any MatchPoint configurations that are used during the workspace creation containing references depending on an HTTP context will fail when being called by a Powershell script.

A good example for such a missing HTTP context is the MPSnow.Workspace.Template.xml, where the RequestAccessEmail field may contain the following expression: {SPHelper.GetCurrentUser().Email}. The GetCurrentUser relies on the HTTP context, which is not available.

Other candidates for a missing HTTP context are expressions containing references to the Self-object. In a standard Workspace Template, the TargetUrlExpression is such a candidate.

The solution is to "overwrite" such MatchPoint expressions by setting their value directly from the Powershell script, which we'll do in the following example:

$ServerUrl = "http://sharepointsite/"
$TargetInstanceUrl = $ServerUrl + "admin"

# Start MatchPoint Scope Init
$web = Get-SPWeb -Identity $TargetInstanceUrl
$mpInstance = New-Object -TypeName Colygon.MatchPoint.Core.MPInstance $web
$mpInstanceScope = New-Object -TypeName Colygon.MatchPoint.Core.MPInstanceScope $mpInstance
# End MatchPoint Scope Init

#Instantiate the template using the GUID for the MPSnow.Workspace.Template.xml
$templateId = [GUID]("52ebe923-a64d-4a6f-b5b1-eb86a2a6e1b2")
$tpl = [Colygon.MatchPoint.Workspaces.Configuration.WorkspaceTemplateConfiguration]::GetTemplate($templateId, $mpInstance)

#Overwrite the expression in the template's RequestAccessEmail field by the result
$tpl.RequestAccessEmail = "jane.doe@cycl.ch"

#Overwrite the TargetUrlExpression by using SPHelper.CombineUrl() and ensuring the template URL is absolute
$TemplateUrl = $tpl.TargetUrlExpression.Evaluate($null);
if (!$templateUrl.StartsWith("http://") -and !$templateUrl.StartsWith("https://"))
{
    $tpl.TargetUrlExpression = """" + [Colygon.MatchPoint.Core.SPHelper]::CombineUrl($ServerUrl, $TemplateUrl) + """"
}

#Create the workspace object with a minimal set of properties
$ws = New-Object -TypeName Colygon.MatchPoint.Workspaces.Model.Workspace $tpl
$ws["Title"] = "Workspace from Powershell"
$ws["Description"] = "A Description for this workspace."
$ws["WorkspaceTypeId"] = "Project"
$ws["WorkspaceIconUrl"] = "/_layouts/15/images/colygon.matchpoint.snow/workspace_icons/project_200.png"
$ws.Update($true)

Write-Host "Created workspace with url" $ws.Url

#Well... we forgot to add an owner to the workspace, so we'll use this 
#as an opportunity to show futher updating the same workspace object. 
#At this point, you might as well want to add business tags, upload content,
#create posts - or anything else that your script should automate.

$ws.UserRoleAssignments["Owner"].Add("i:0#.w|sharepoint\jane.doe")
...

$ws.Update()

Creating or Updating several workspaces

A typical script execution might iterate over many site collections/workspaces.

• It is essential to dispose of your Snow Workspace and MatchPoint Instance objects appropriately!
• There is an Exists method which allows you to test, whether the site collection is a MatchPoint Snow workspace or just a standard SharePoint site collection.

Your script may, therefore, look as follows:

#Start MatchPoint Scope Init
...

#Iterate over all site collections of a SP web application (Get-SPWebApplication)
foreach($site in $webapp.sites)
{
  foreach($web in $site.AllWebs)  
  {  
    $ws = New-Object -TypeName Colygon.MatchPoint.Workspaces.Model.Workspace $web.url
    if ($ws.Exists)
    {
      #Do all your workspace stuff here
      ...
      $ws.Dispose() 
    }     
  }
}
$mpInstance.Dispose()

Hope, the above is informative for you. As in the previous powershell post, the final disclaimer:

Important Notes:

• Make sure that your Powershell session has sufficient rights. This is one of the most common problems you might run into.
• Test your scripts on a dev system before production. Powershell makes it very, very easy to destroy or corrupt an entire working SharePoint farm in milliseconds.