Some words about TaxonomyFieldValue and its WssId property

In these weeks I’m busy with planning and POCing a custom social site solution built on top of SP 2010. Lot of the requirements are related to the new managed metadata framework, so I’m planning to post some of the most exciting results in my blogs.

In this post I will introduce you the not-so-obvious WssId property of the TaxonomyFieldValue class.

TaxonomyFieldValue has three important properties (at least, for now):

Label (string): It is the Value (string) property of the Label selected by the user from the Labels property of the Term object

TermGuid (string, not Guid): it is the Id (Guid) property of the Term (inherited from TaxonomyItem)

WssId (int): What is that and where its value comes from?

When you assign value a TaxonomyField, an item is created for the selected Term (or if there is already an item for the term, that item is used)  in a hidden list called TaxonomyHiddenList in the root web of the site. The WssId is the Id of that item in the TaxonomyHiddenList .

To track the call chain of this process, see the following internal or private methods of TaxonomyField (if you don’t like boring deep technical content, you can skip this section):

The ValidateTaxonomyFieldValue is to validate the field value. First if the value is not yet resolved it tries to resolve that using the GetOrResolveUnvalidatedTaxonomyFieldvalue method. Both of these methods call the AddTaxonomyGuidToWss method, that calls with elevated privileges the AddTaxonomyGuidToWssCore method. This method calls first the GetLookupList method to get the TaxonomyHiddenList for the current site through the GetLookupListHelper method. There is a private static class of type ThreadSafeDictionary<Guid, Guid> called  lookupListIDs to help this lookup process and make that faster. After creating the new item in the hidden list, the  AddTaxonomyGuidToWssCore method returns with the ID of the new item.

But where should we get the WssId from if we have only a Term object that has not this information?

I’ve found two alternatives. The first – trivial – one is the static GetWssIdsOfTerm method of the TaxonomyField class:

int[] wssIds = TaxonomyField.GetWssIdsOfTerm(site, term.TermStore.Id, term.TermSet.Id, term.Id, false, 1);

wssIds[0] will contain the ID we need.

The other way is a bit more complicated but it illustrates how to work with the TaxonomyHiddenList list:

1. private int GetWssIdByTermId(SPWeb rootWeb, Guid termId)
2. {
3.     int result = –1;
4.  
5.     if (rootWeb.Properties.ContainsKey("TaxonomyHiddenList"))
6.     {
7.         Guid taxonomyHiddenListId = new Guid(rootWeb.Properties["TaxonomyHiddenList"]);
8.         SPList taxonomyHiddenList = rootWeb.Lists[taxonomyHiddenListId];
9.         SPQuery query = new SPQuery();
10.         // we might have included the IdForTermSet in the query but we assume that Guid is really unique
11.         // so there should not be temrs in other terms sets having the same ID
12.         query.Query = String.Format(@"<Where><Eq><FieldRef Name='IdForTerm' /><Value Type='Text'>{0}</Value></Eq></Where>", termId);
13.         SPListItemCollection items = taxonomyHiddenList.GetItems(query);
14.         if (items.Count == 1)
15.         {
16.             result = int.Parse(items[0]["ID"].ToString());
17.         }
18.     }
19.     return result;
20. }

OK, but why is it good for us to know the WssId of the TaxonomyFieldValue?

There might be several reasons, but one of them is that it can be used to query the list items through the CAML syntax, as illustrated:

1. private SPListItemCollection GetItemsByTerm(SPList list, String fieldName, Term term)
2. {
3.     SPSite site = list.ParentWeb.Site;
4.     SPWeb rootWeb = site.RootWeb;
5.  
6.     int wssId = GetWssIdByTermId(rootWeb, term.Id);
7.     
8.     // or we could use this one
9.     // wssIds[0] will be the WssId we need
10.     //int[] wssIds = TaxonomyField.GetWssIdsOfTerm(site, term.TermStore.Id, term.TermSet.Id, term.Id, false, 1);
11.  
12.     SPQuery query = new SPQuery();
13.     query.Query = String.Format(@"<Where><Eq><FieldRef Name='Metadata' LookupId='TRUE' /><Value Type='Lookup'>{0}</Value></Eq></Where>", wssId);
14.     SPListItemCollection items = list.GetItems(query);
15.     return items;
16. }

You could use the following format either:

<Where><Contains><FieldRef Name=’YourTaxonomyFieldName’ /><Value Type=’Text’>Title of your term</Value></Contains></Where>

But the above syntax queries the items only as text, not by reference ID.

To call the GetItemsByTerm method:

1. SPListItemCollection result = GetItemsByTerm(list, "YourTaxonomyFieldName", term);
2.  
3. foreach (SPListItem item in result)
4. {
5.     Console.WriteLine("Title: {0}", item["Title"]);
6. }

It is even easier to query items if you have a TaxonomyFieldValue:

1. private SPListItemCollection GetItemsByTaxonomyFieldValue(SPList list, String fieldName, TaxonomyFieldValue value)
2. {
3.     SPSite site = list.ParentWeb.Site;
4.     SPWeb rootWeb = site.RootWeb;
5.  
6.     SPQuery query = new SPQuery();
7.     query.Query = String.Format(@"<Where><Eq><FieldRef Name='Metadata' LookupId='TRUE' /><Value Type='Lookup'>{0}</Value></Eq></Where>", value.WssId);
8.     SPListItemCollection items = list.GetItems(query);
9.     return items;
10. }

To call the GetItemsByTaxonomyFieldValue method:

1. SPListItemCollection result = GetItemsByTaxonomyFieldValue(list, "YourTaxonomyFieldName", value);
2.  
3. foreach (SPListItem item in result)
4. {
5.     Console.WriteLine("Title: {0}", item["Title"]);
6. }

The code samples here show only a simple CAML query, you can create more complex ones, for example combining multiple conditions using logical And or Or to look up items having all or any of the meta data applied.