Monday, May 23, 2011

Configuring metadata navigation settings on SharePoint lists with PowerShell

The feature is configured in the user interface by selecting “Metadata navigation settings” from the list settings. This will display an administration interface similar to the one shown below:


As you can see from the screenshot above, I have two custom columns called Document Status (single-value Choice type) and Technology (single-value Managed Metadata type) available in the Available Hierarchy Fields and Available Key Filter Fields boxes ready to add as a navigation hierarchy or key filter. Note the default setting for Selected Hierarchy Fields is Folders.

For this example, I will use PowerShell to configure both the navigation hierarchy and key filters settings to include my custom columns. I will also show you how to add the Content Type and Folders options too.

First, we will assign the site that contains the list to a variable and use this variable to get the list:

#Get Web and List objects
$web = Get-SPWeb
$list = $web.Lists["Shared Documents"]

Next, we will get the current metadata navigation settings for the list and assign them to a variable:

#Get metadata navigation settings for the list
$listNavSettings = [Microsoft.Office.DocumentManagement.MetadataNavigation.MetadataNavigationSettings]::GetMetadataNavigationSettings($list)

The next two lines of the script clear the configured hierarchies and configured key filters on the list. You could use these commands in combination with the SetMetadataNavigationSettings and $list.RootFolder.Update() commands mentioned later to remove any currently configured metadata navigation settings for the list:

#Clear current metadata navigation settings on the list

These commands will add my two custom columns to the Selected Key Filter Fields:

#Configure key filters by adding columns
$listNavSettings.AddConfiguredKeyFilter($list.Fields["Document Status"])

These next two lines are quite important. I have found that the navigation hierarchy configuration does not work when configuring it from PowerShell unless you add the default Folders item to the Selected Hierarchy Fields first. Without this step, the custom columns will be added successfully in the Metadata navigation settings page, but they will not appear in the Tree View interface:

#Add folder navigation hierarchi$listes into list settings
#This is required to enable and show navigation hierarchies in the Tree View
$folderHierarchy = [Microsoft.Office.DocumentManagement.MetadataNavigation.MetadataNavigationHierarchy]::CreateFolderHierarchy()

The next step is optional, but contains the commands needed to add Content Type navigation hierarchies to the settings, if required:

#Optionally add content type navigation hierarchies into list settings if required
$ctHierarchy = [Microsoft.Office.DocumentManagement.MetadataNavigation.MetadataNavigationHierarchy]::CreateContentTypeHierarchy()

We now add the custom columns to the Selected Hierarchy Fields:

#Configure extra navigation hierarchies by adding list columns
$listNavSettings.AddConfiguredHierarchy($list.Fields["Document Status"])

And finally, set the metadata navigation settings and update the root folder of the list, which is where the settings are stored:

#Set the new metadata navigation settings and update the root folder of the list
[Microsoft.Office.DocumentManagement.MetadataNavigation.MetadataNavigationSettings]::SetMetadataNavigationSettings($list, $listNavSettings, $true)

The Metadata navigation settings page should now look as follows:


To test the metadata navigation feature, you will need to switch on the Tree View setting for the site. This can be done in the UI by selecting Site Settings > Tree view > Enable Tree View or you can change it with a couple of extra lines in your PowerShell script:

#Enable Tree View on the site so that navigation hierarchies can be used in the UI
$web.TreeViewEnabled = $true


The metadata navigation and key filters features will show up on the left-hand side of the SharePoint user interface, underneath the quick launch menu, as shown above. To complete the script, don’t forget to dispose of the Web object:

#Dispose of the Web object

No comments: