Someone at work recently asked if you could configure the Authoritative Pages settings in SharePoint 2013 Search using PowerShell or whether the only way to do it was using the Search Service UI.  After a bit of research I found out that indeed you can configure the settings using PowerShell.  But I also found out that there isn’t a lot of documentation available on the web about exactly how to do it.  The difficulty is made worse by the fact that most of the documentation that does exist is for SharePoint 2010 Enterprise Search and there is a new required parameter in 2013 that makes all those Blog posts invalid.  So I decided it would be a good idea to write a “How To” post that would explain the required PowerShell.

What are Authoritative Pages?

When SharePoint web site pages and documents are returned in Search results one of the factors that effects their relevance placement is static rank.  Static rank is computed as the smallest number of clicks it would take a user to navigate from an authoritative page to a document. The closer a document is to the most authoritative page, the higher its static rank is.  Search Administrators can enter three (3) levels of authoritative pages for calculating the static rank of a search result.  They can also add site addresses to a fourth level which will demote the static rank of a specific result when compared to all other references.  In other words the closer a specific document is to one of the three authoritative pages the higher it will appear in a set of search results, while results that come from the non-authoritative sites will be at the bottom of the search results list.  For example, you might list a team site that contains draft copies of documents in the Non-authoritative sites and the home page of a document center site contains published copies in the most authoritative pages section.  This would lead to the elevation of published copies in search results instead of draft copies.

The PowerShell Cmdlets

There are two sets of PowerShell Cmdlets used to manipulate the authoritative pages settings.  First, there are four (4) Cmdlets for creating/managing the three (3) main authoritative page lists.  They are:

• Get-SPEnterpriseSearchQueryAuthority – retrieves existing authoritative page(s)
  -Identity <AuthorityPagePipeBind>
  -Owner <SearchObjectOwner>
  -SearchApplication <SearchServiceApplicationPipeBind>
• New-SPEnterpriseSearchQueryAuthority – creates a new authoritative page setting
  -Url <String>
  -Level <Single>
  -Owner <SearchObjectOwner>
  -SearchApplication <SearchServiceApplicationPipeBind>
• Set-SPEnterpriseSearchQueryAuthority – changes the level of an existing authoritative page
  -Identity <AuthorityPagePipeBind>
  -Level <Single>
  -Owner <SearchObjectOwner>
  -SearchApplication <SearchServiceApplicationPipeBind>
• Remove-SPEnterpriseSearchQueryAuthority – removes an existing authoritative page
  -Identity <AuthorityPagePipeBind>
  -Owner <SearchObjectOwner>
  -SearchApplication <SearchServiceApplicationPipeBind>

There are also three (3) Cmdlets for creating/managing the non-authoritative page list.  They are:

• Get-SPEnterpriseSearchQueryDemoted – retrieves existing non-authoritative page(s)
  -Identity <AuthorityPagePipeBind>
  -Owner <SearchObjectOwner>
  -SearchApplication <SearchServiceApplicationPipeBind>
• New-SPEnterpriseSearchQueryDemoted – creates a new non-authoritative page setting
  -Url <String>
  -Owner <SearchObjectOwner>
  -SearchApplication <SearchServiceApplicationPipeBind>
• Remove-SPEnterpriseSearchQueryDemoted – removes an existing non-authoritative page
  -Identity <AuthorityPagePipeBind>
  -Owner <SearchObjectOwner>
  -SearchApplication <SearchServiceApplicationPipeBind>

The Parameters

As I mentioned before some of the parameters have changed since SharePoint 2010.  Most importantly the –Owner parameter is now a required parameter and it wasn’t in 2010.  Here’s what you need to know about each of the parameters:

• Url – The New commands require a Url to designate the page or site address to be added as an authoritative page entry.
• Identity – Identity is optional for the Get command.  Without an Identity the Get command will return all the authoritative pages.  The Set and Remove commands require that a specific page be identified.
• Level – Specifies the level where the page address should be added.  Valid values are integers 0, 1, and 2 with 0 being the Most Authoritative Pages and 2 being the Third-level Authoritative Pages.
• Owner – This was optional for 2010 but is required in 2013.  It must be set to a Search Object Owner designating either a Search Service Application or a Tenant Subscription in a Multi-tenant environment.  I’ll provide an example of how to get the Search Object Owner in the sample code below.
• SearchApplication – This is the Search service application object to which the pages will be added.

PowerShell Sample

Now that we’ve looked at the commands and parameters lets look at a sample script that demonstrates how to use the commands.

   1:  #Get the Enterprise Search Service Application

   2:  $ssa = Get-SPEnterpriseSearchServiceApplication

   3:  

   4:  #Get the Search Owner object.  

   5:  #Must be either SearchServiceApplication (Ssa) or Multitenancy SiteSubscription (SPSiteSubscription) 

   6:  $owner = Get-SPEnterpriseSearchOwner -Level Ssa

   7:  

   8:  #Identity is either a valid url or an AuthorityPage Object(Retrieved with Get-SPEnterPriseSearchQueryAuthority)

   9:  $url1 = "http://siteURL/"

  10:  $url2 = "http://siteURL/sites/sitecollection/"

  11:  $url3 = "http://siteURL/Pages/Default.aspx"

  12:  

  13:  $mostAuthoritative = 0

  14:  $secondMostAuthoritative = 1

  15:  $thirdMostAuthoritative = 2

  16:  

  17:  #Try to get an existing Authoritative Page 

  18:  $sqa = Get-SPEnterpriseSearchQueryAuthority -Identity $url1 -Owner $owner -SearchApplication $ssa -ErrorAction SilentlyContinue

  19:  if ($sqa -eq $null)

  20:  {

  21:      #Create a new Authoritative page if one doesn't exist

  22:      $sqa = New-SPEnterpriseSearchQueryAuthority -Owner $owner -SearchApplication $ssa -Url $url1 -Level $secondMostAuthoritative

  23:  }

  24:  else

  25:  {

  26:      #Change the level of an exiting Authoritative page

  27:      Set-SPEnterpriseSearchQueryAuthority -Identity $sqa -Level $thirdMostAuthoritative -SearchApplication $ssa -Owner $owner

  28:  }

  29:  

  30:  $sqa2 = Get-SPEnterpriseSearchQueryDemoted -Identity $url3 -Owner $owner -SearchApplication $ssa -ErrorAction SilentlyContinue

  31:  if ($sqa2 -eq $null)

  32:  {

  33:      New-SPEnterpriseSearchQueryDemoted -Owner $owner -SearchApplication $ssa -Url $url2

  34:  }

  35:  

  36:  Remove-SPEnterpriseSearchQueryAuthority -Identity $url3 -Owner $owner -SearchApplication $ssa -Confirm:$false