Wednesday, 20 March 2013

Clear (Delete) the value of a taxonomy field using PowerShell

[Update, 3/July/2013]: I've converted this PowerShell into a script which can be downloaded from the Microsoft TechNet Gallery, here: http://gallery.technet.microsoft.com/sharepoint/Update-or-Clear-Metadata-94959cb3

The script makes it easy to clear or update the metadata values of a metadata column.

E.g.

Import-Module C:\Scripts\Update-MetadataField.ps1
$listitems = (Get-SPWeb http://devmy101).Lists["mylistwithdatainit"].Items 
Clear-MetadataField -items $listitems -MetadataFieldInternalName metadataField -ClearAllItems

[Original Article]

Yesterday I got stumped working out how to clear the value of taxonomy field when helping someone on the Microsoft forums. I could clear the value of the field using the TaxonomyField.ParseAndSetValue(item, value) method of the field, setting the value to $null, but it only worked if the list item belonged to a list. If the item was in a document library, the value wouldn't be cleared. Eventually (after a little persistence), I worked it out, and thought I'd share it here.
The proper way to clear a taxonomy field (which seems obvious upon reflection!), is to get an empty taxonomy value, using the Taxonomy.GetFieldValue method, and then pass it to the TaxonomyField.SetFieldValue method.

The only other difference between working with lists and document libraries, is the way in which we retrieve the list item.

Working with Lists
$web = get-spweb http://my
$list = $web.Lists["my list"]
$item = $list.items[1] #Get an item that currently has a value set in the Taxonomy (Managed Metadata) field
$taxField = $item.Fields["metadataField"] -as [Microsoft.SharePoint.Taxonomy.TaxonomyField] 
$taxFieldValue = $taxField.GetFieldValue("");
$taxField.SetFieldValue($item,$taxFieldValue)
$item.Update()

Working with Document Libraries
$web = get-spweb http://my
$list = $web.Lists["document library"] -as [Microsoft.SharePoint.SPDocumentLibrary]
$item = $list.items[1] #Get an item that currently has a value set in the Taxonomy (Managed Metadata) field
$url = [String]::Format("{0}{1}",$web.Url, $item.File.Url)
$file = $web.GetFile($url)
if($file.CheckOutStatus -eq "None")
{
$file.CheckOut()
$fileItem = $file.Item
$taxField = $fileItem.Fields["metadataField"] -as [Microsoft.SharePoint.Taxonomy.TaxonomyField]
$taxFieldValue = $taxField.GetFieldValue("");
$taxField.SetFieldValue($fileItem,$taxFieldValue)
$fileItem.Update()
$file.CheckIn("Updated Taxonomy Field Value")
}
else
{
$msg = [String]::Format("This file, {0}, is checked out and cannot be edited at the moment",$file.Name)
Write-Host $msg -ForegroundColor DarkYellow
}

Other tips...

Getting an item by it's ID
$item = $list.GetItemById(12)

Looping through the list
$web = get-spweb http://my
$list = $web.Lists["my list"]
$items = $list.items
$taxField = $list.Fields["metadataField"] -as [Microsoft.SharePoint.Taxonomy.TaxonomyField] 
$taxFieldValue = $taxField.GetFieldValue("");
foreach($item in $items)
{
$taxField.SetFieldValue($item,$taxFieldValue)
$item.Update()
}