Configuring Search Authoritative Pages with PowerShell

logo-powershellSomeone 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

MCSD: SharePoint Certification Officially Announced

MCSD SharePoint Applications

There have been rumors running around for months about what exams would be required to earn the Microsoft Certified Solution Developer certification for SharePoint 2013.  MS Learning officially added MCSD: SharePoint to their site today.  You can see all the SharePoint certifications, including MCSD, here.

The Two SharePoint specific Development exams haven’t been released yet, but should be available later this summer.  In the meantime you can get started on the two non-SharePoint specific certification exams.

Another point that should be noted.  This announcement continues the trend started with the SharePoint Microsoft Certified Masters certification.  Certifications will now be time constrained.  You must recertify every two years to maintain the MCSD: SharePoint certification.  This is also true for MCSM: SharePoint (three years) and MCSE: SharePoint (two years).  This recertification requirement reflects Microsoft’s move away from doing major specific releases, like 2007, 2010, and 2013, to a more continuous release cycle with quarterly service releases for Office 365.  You can expect to see On-premise SharePoint going to a more continuous evolution over the next several years also.  These new certs anticipate that development in both the Online and On-Premise environments.

Make App Icons that Change with a Composed Look

Animated

Recently a developer friend was wondering why all the built-in App Icons changed colors on his SharePoint 2013 site when he applied a different color scheme using the “Composed Looks” functionality,but Icons for custom apps he had deployed remained their original color.  The screenshot below shows the Site Contents page both before (Left Side) and after a Theme has been applied using a Composed Look (Right Side).  You can see that all the Icons on the page changed except the last one on the right.  This is the App that I installed using the Visual Studio 2012 SharePoint Hosted App project.  So the question is Why do all the other Icons change?

Appssidebyside

The first theory was that the App Icons were being recolored using the Theme CSS support that has been available since SharePoint 2010.  But the ability to recolor an image using CSS has always been limited to background images loaded through CSS.  These Icons are loaded using an <IMG> element so there is no way to specify the image in CSS and no way to recolor it.

After using IE’s Developer toolbar to examine the HTML and CSS on the pages above I found that the image itself doesn’t get recolored. But the <a> (anchor tag) that surrounds the Icon is a square rectangle occupying the space behind each image that has its background set to one of the theme colors.  You can see in the screenshot below that the <a> tag has its background set to a class of “ms-storefront-appiconspan’ which is set to an rgb color from a themable css file.  But why does changing the background behind the Icon change the color of the Icon?

appIconBackground

The trick is that the Icon file itself is a transparent PNG that is the same size, 90 X 90 pixels, as the anchor tag with the background color behind it.  That way the background color shows through the Icon and appears to recolor the icon itself.  So let’s see what happens to my Visual Studio project if I replace the blue in my App Icon with a Transparent background.  the image below shows the original Icon on the left and the new transparent Icon on the right after I cut the background out using Paint.Net.

appIcons

After uploading the new Icon image into my visual Studio project and redeploying the custom app you can see that the custom app Icon changes colors along with the Theme in the screenshot below.  If you restrict your Icon to white images and text on a transparent background then your Icon should look like it fits no matter what Composed Look is applied to your site.

AppAfter

Office Developer Tools for Visual Studio 2012 ships full RTM

visual_studio_logo-new-300x225

If you who have been learning to develop the new SharePoint 2013 Apps then you know that the toolset for doing that in Visual Studio 2012 didn’t ship a finished RTM version when SharePoint 2013 shipped its RTM version in November.  Instead we’ve all still been working on a Preview 2 version.  Well no longer! The final version of Office Developer Tools for Visual Studio shipped today.  You can read more about the announcement here:

http://blogs.msdn.com/b/somasegar/archive/2013/03/04/now-available-office-developer-tools-for-visual-studio-2012.aspx 

And more importantly you can download the new tools via web platform Installer from the following URL:

http://aka.ms/OfficeDevToolsForVS2012