How to Create User Contexts, Custom User Context Properties and Site Promotions from PowerShell for SharePoint 2010

PowerShell is a powerful tool when combined with FAST. When dealing with a large site collection with multitudes of taxonomies and sites underneath it, promoting sites and keeping user contexts from environment to environment can be a long and taxing job, especially when you are working with the SharePoint/FAST UI. Luckily, this is where PowerShell comes in and saves your day.

User Context Properties

In SharePoint, you can create and edit user contexts through the UI. Under Site Settings –> FAST Search User Context, you will find all of your user contexts. The page to create a User Context looks like this out of the box:

How to Create User Contexts, Custom User Context Properties and Site Promotions from PowerShell for SharePoint 2010

Useful page, but not really right? If you want some more depth, you will have to do some digging into User Profiles. Go to Central Administration –> Service Applications –> <Your User Profile Service Application> –> Manage User Properties. Here you will find a list of user properties that are used in SharePoint, and these will be the key to making User Contexts and Site Promotions valuable and create a rich user experience for searches.

So first, let’s add a new property to the User Context. Let’s say that the User’s “Department” is an important factor in search relevancy. Therefore we want items relevant to the User’s Department to show up first in search results. To do this, we need to execute a couple PowerShell scripts.

View Current User Context Properties

First, let’s see what User Context properties are already available. If we haven’t touched them before, then we should see two of them, “SPS-Location,SPS-Responsibility”. We will be using the SharePoint PowerShell.

$properties = Get-SPEnterpriseSearchExtendedQueryProperty -SearchApplication "FASTQuery" -Identity "FASTSearchContextProperties"
$properties.Value







Where “FASTQuery” is the <Name of your FAST Query SSA>.



How to Create User Contexts, Custom User Context Properties and Site Promotions from PowerShell for SharePoint 2010



Add User Context Property



We need to make sure that we use the Name of the User Profile Property rather than the Display Name. This is especially important if we are using custom user profile properties. Also, we will need to include the old user context properties in this script, otherwise, they will be overwritten.




Set-SPEnterpriseSearchExtendedQueryProperty -SearchApplication "FASTQuery" -Identity "FASTSearchContextProperties" -Value "SPS-Location,SPS-Responsibility,Department"







Troubleshooting: Now if you go to your UI, often you won’t see any changes (the changes will be reflected in PowerShell however)! The fastest way that I’ve seen to get these changes to show is an IIS Reset. If there is a way around this, please let us know. Therefore, type in iisreset into your PowerShell, then check the UI after it has completed. It should now look like this:



How to Create User Contexts, Custom User Context Properties and Site Promotions from PowerShell for SharePoint 2010



How to Create User Contexts, Custom User Context Properties and Site Promotions from PowerShell for SharePoint 2010



Add User Contexts Using PowerShell



Now that we have some new properties to play around with, let’s add some User Contexts! In the FAST PowerShell, run the command Get-FASTSearchSearchSettingGroup. This will return the FAST Search Setting Group(s) that are on the machine. There should only be one straight out of the box. We will need the Name for the next step.



How to Create User Contexts, Custom User Context Properties and Site Promotions from PowerShell for SharePoint 2010




$searchSettingGroup = Get-FASTSearchSearchSettingGroup -Name "69d025ce-96a7-4131-adc0-7da1603e8d24"

$context = $searchSettingGroup.Contexts.AddContext("USA Marketing")

$andExpression = $context.AddAndExpression()

$orExpression = $andExpression.AddOrExpression()

$orExpression.AddMatchExpression('SPS-Location','USA')

$orExpression.AddMatchExpression('Department','Marketing')

# Optional not Expression (remove #)
# $not = andExpression.AddNotExpression()
# $not.AddMatchExpression('SPS-Location','Japan')
# $not.AddMatchExpression('SPS-Location','Canada')







This next script will add a new User Context. The true usefulness of doing this in PowerShell is the added ability to use the “not” expression to truly filter your User Context. Besides that, why is this even useful over the UI? Mainly because it’s easily portable, and you can quickly execute your PowerShell script when it’s time to move from development to production. This is handy, especially if you have multiple User Contexts, but even more so when we begin adding Site Promotions.



How to Create User Contexts, Custom User Context Properties and Site Promotions from PowerShell for SharePoint 2010



Add Site Promotions Using PowerShell



Handling site promotions and demotions can be a real hassle, especially when we begin dealing with an environment with many sites and sub-sites. Having PowerShell will make this process quick and portable from a development environment to a production environment.



Here, we begin talking about the use of “boosting” relevance and using Site Promotions. Here, we will be working with a promotion without using Keywords. This could be considered something closer to “scoping”, however the search will still extend beyond the scope of the sites included in the search. PowerShell allows you to choose your boost value automatically, assign multiple websites to your boost, and select the User Context(s) to include.



 




1:  # This PowerShell Script Adds Site Promotions for USA Marketing
3:
4: # Register the FASTSearch Powershell Snapin (if needed)
5: Add-PSSnapin Microsoft.FASTSearch.Powershell
6:
7: # Current Search Setting Group
8: $searchSettingGroup = Get-FASTSearchSearchSettingGroup -Name "69d025ce-96a7-4131-adc0-7da1603e8d24"
9:
0: # Type of Promotion
1: $globalPromotions = $searchSettingGroup.PromotionsWithoutKeyword
2:
3: # Promotion Name
4: $globalPromotion = $globalPromotions.AddPromotion("USA Marketing Sites")
5:
6: # Boost Value
7: $globalPromotion.BoostValue = 12000
8:
9:
0: ######### Begin Site Promotions Section #########
1:
2: $sitePromotionsToBeAdded = @(
3:
4: "http://intranet/USA/",
5: "http://intranet/marketing/",
6: "http://intranet/marketing/USA/",
7: "http://intranet/HR/Marketing",
8: "http://intranet/USA/Research/Marketing/",
9: "http://intranet/USA/Support/Marketing/"
0:
1: )
2:
3: # loop through site collection
4: foreach ($site in $sitePromotionsToBeAdded)
5: {
6: $uri = New-Object -Typename System.Uri -ArgumentList $site
7: $globalPromotion.PromotedItems.AddPromotedLocation($uri)
8: }
9:
0: # Add Site Promotion Individually (if needed)
1: # $uri = New-Object -TypeName System.Uri –ArgumentList http://intranet/USA
2: # $globalPromotion.PromotedItems.AddPromotedLocation($uri)
3:
4:
5: ########### End Site Promotions Section ##########
6:
7: # Added User Context
8: $userContexts = ({USA Marketing})
9: $globalPromotion.Contexts.AddContext($userContexts)







PowerShell is a clean method of adding Site Promotions to specific User Contexts in FAST Search. If you check under Site Settings –> FAST Search site promotion and demotion, you should see your new site promotion with its User Context(s) attached.



How to Create User Contexts, Custom User Context Properties and Site Promotions from PowerShell for SharePoint 2010



References:



 http://technet.microsoft.com/en-us/library/ff191225.aspx



http://blogs.technet.com/b/speschka/archive/2009/12/09/using-custom-properties-to-create-a-fast-search-for-sharepoint-2010-user-context.aspx