Sunday, June 30, 2013

SharePoint 2013 Code Tips – Setting a Managed Metadata Field with the Client Object Model(CSOM and JSOM)

Technorati Tags: ,,,

This is my first blog post on SharePoint 2013 code tips. I am going to start this series by tackling a problem most SharePoint developers have run across when using the client object model with SharePoint 2010. The problem is updating managed metadata fields. Fortunately, this has become easier in SP2013 with the new Microsoft.SharePoint.Taxonomy.Client and the SP.Taxonomy.js file in JSOM. I wrote a blog post about updating managed metadata fields in SP2010 and you can read it here SP2010 Managed Metadata . I explained how you had to update two fields when updating managed metadata. This was confusing and error prone. Now you no longer need to update the additional field. In this post I will show you how to do this using both the managed CSOM and JSOM in the app model. I will cover updating single and multi valued managed metadata fields and a few things about accessing lists outside of the application host in Office 365. The code for this article can be found here Managed Metadata Code Samples

Updating Managed Metadata using CSOM

In order to update a managed metadata field in SP2010 you had to update two fields. One was the managed metadata field itself and the other was it’s corresponding backing text field. This was very cumbersome. First you had to use the managed metadata’s SchemaXml property to parse out the ID of its backing field and then use this ID to set the backing field. Fortunately, the new Microsoft.SharePoint.Client.Taxonomy namespace in SP2013 has made this much easier. No longer do you need to update two fields. It is also much easier to lookup the GUID for a term. The GUID is needed to update managed metadata fields. In SP2010 you needed to call the Taxonomy web service to get these and parsing the returned xml was a nightmare. The following code uses the managed SharePoint 2013 client object model to either update a single managed metadata value field or a multi-valued metadata field. The method takes a site URL, list name, item ID, the name of the managed metadata field and the label of the term. The caller of the method does not have to know anything about the term or field since the code will do all the work to get the appropriate information.

public static void SetManagedMetaDataField(string siteUrl,
string listName,
string itemID,
string fieldName,
string term)

ClientContext clientContext = new ClientContext(siteUrl);
List list = clientContext.Web.Lists.GetByTitle(listName);
FieldCollection fields = list.Fields;
Field field = fields.GetByInternalNameOrTitle(fieldName);

CamlQuery camlQueryForItem = new CamlQuery();
string queryXml = @"



camlQueryForItem.ViewXml = queryXml.Replace("!@itemid", itemID);

ListItemCollection listItems = list.GetItems(camlQueryForItem);

clientContext.Load(listItems, items =>; items.Include(i =>; i[fieldName]));

TaxonomyField txField = clientContext.CastTo(field);
string termId = GetTermIdForTerm(term, txField.TermSetId, clientContext);

ListItem item = listItems[0];

TaxonomyFieldValueCollection termValues = null;
TaxonomyFieldValue termValue = null;

string termValueString = string.Empty;

if (txField.AllowMultipleValues)

termValues = item[fieldName] as TaxonomyFieldValueCollection;
foreach (TaxonomyFieldValue tv in termValues)
termValueString += tv.WssId + ";#" + tv.Label + "|" + tv.TermGuid + ";#";

termValueString += "-1;#" + term + "|" + termId;
termValues = new TaxonomyFieldValueCollection(clientContext, termValueString, txField);

termValue = new TaxonomyFieldValue();
termValue.Label = term;
termValue.TermGuid = termId;
termValue.WssId = -1;
txField.SetFieldValueByValue(item, termValue);


The code uses the CSOM taxonomy classes TaxonomyFieldValueCollection and TaxonomyFieldValue. These make it easier for setting the different properties that are required for managed metadata values. Also the new TaxonomyField class enables the code to check whether the field accepts multiple values by using the AllowMultipleValues property. Also, these new classes expose methods for updating the field. You no longer set the field value directly on the item. The example above shows how you can append a new term to an existing group of terms. Finally, below is the code for the GetTermIdForTerm method which uses the new CSOM capabilities to search for a term’s unique ID based on a given term label using the new LabelMatchInformation class.

 public static string GetTermIdForTerm(string term,
Guid termSetId, ClientContext clientContext)
string termId = string.Empty;

TaxonomySession tSession = TaxonomySession.GetTaxonomySession(clientContext);
TermStore ts = tSession.GetDefaultSiteCollectionTermStore();
TermSet tset = ts.GetTermSet(termSetId);

LabelMatchInformation lmi = new LabelMatchInformation(clientContext);

lmi.Lcid = 1033;
lmi.TrimUnavailable = true;
lmi.TermLabel = term;

TermCollection termMatches = tset.GetTerms(lmi);


if (termMatches != null && termMatches.Count() > 0)
termId = termMatches.First().Id.ToString();

return termId;


What about Office 365 and JSOM

Implementing the same CSOM code in JSOM to run in Office 365 proved to be much more complex. For example, the code needs to lookup the term’s GUID before you can update the field.The CSOM is easier since it is synchronous and the calling thread waits until the lookup is completed. However when using JSOM you must make all your calls asynchronously. So in the code below subsequent calls must be made in the success call back functions. This of course makes the code hard to follow. The asynchronous requirement of JSOM also forced me to make the GetTermIdForTerm method asynchronous. In Office 365  to access lists residing in the hosting web you must set up a new SP.AppContextSite object in order to get the host web and list. All the same classes that are available in CSOM are also available in JSOM.  The Taxonomy classes are contained in the SP.Taxonomy.js file and is not loaded by default. So you must make sure this is loaded.

function SetManagedMetaDataField(listName,
term) {

appweburl = decodeURIComponent(getQueryStringParameter('SPAppWebUrl'));
hostweburl = decodeURIComponent(getQueryStringParameter('SPHostUrl'));
context = new SP.ClientContext(appweburl);
factory = new SP.ProxyWebRequestExecutorFactory(appweburl);
appContextSite = new SP.AppContextSite(context, hostweburl);

var list = appContextSite.get_web().get_lists().getByTitle(listName);
var item = list.getItemById(itemID);
var field = list.get_fields().getByInternalNameOrTitle(fieldName);
var txField = context.castTo(field, SP.Taxonomy.TaxonomyField);


function () {

var termSetId = txField.get_termSetId().toString();
var termId;

getTermIdForTerm(function success(id) {
termId = id;
var value = item.get_item(fieldName);
var terms = new Array();

if (txField.get_allowMultipleValues()) {

var enumerator = value.getEnumerator();
while (enumerator.moveNext()) {
var tv = enumerator.get_current();
terms.push(tv.get_wssId() + ";#" + tv.get_label() + "|" + tv.get_termGuid());

terms.push("-1;#" + term + "|" + termId);
termValueString = terms.join(";#");
termValues = new SP.Taxonomy.TaxonomyFieldValueCollection(context, termValueString, txField);
txField.setFieldValueByValueCollection(item, termValues);
else {
var termValue = new SP.Taxonomy.TaxonomyFieldValue();
txField.setFieldValueByValue(item, termValue);

function () {
alert('field updated');
}, function (sender, args) {
alert(args.get_message() + '\n' + args.get_stackTrace());
}, function (sender, args) {
alert(args.get_message() + '\n' + args.get_stackTrace());
},context, term, termSetId);

}, function error(err) {


function getTermIdForTerm(success, error, clientContext, term, termSetId)
var termId = "";

var tSession = SP.Taxonomy.TaxonomySession.getTaxonomySession(clientContext);
var ts = tSession.getDefaultSiteCollectionTermStore();
var tset = ts.getTermSet(termSetId);
var lmi = new SP.Taxonomy.LabelMatchInformation(clientContext);


var termMatches = tset.getTerms(lmi);


function () {

if (termMatches && termMatches.get_count() > 0)
termId = termMatches.get_item(0).get_id().toString();

}, function (sender, args) {


function getQueryStringParameter(p) {
var params =
var strParams = "";
for (var i = 0; i < params.length; i = i + 1) {
var singleParam = params[i].split("=");
if (singleParam[0] == p)
return singleParam[1];


Managed Metadata and SharePoint 2013

Managed metadata remote API has become a full citizen in SharePoint 2013. The taxonomy web service has been deprecated and replaced with a CSOM and JSOM client API allowing you to standardize on one remote api. Unfortunately, there is no support for manage metadata manipulation in the SharePoint 2013 REST api. So you will be forced to mix in JSOM into your REST applications for managed metadata.


Anonymous said...


I am getting below error:
SCRIPT5007: Unable to get property 'TaxonomyField' of undefined or null reference

Could you please help me.

Anonymous said...

Thank you very much for this article, I have been stuck with this for the whole day, just copied your code, it's working great!!!
Thank you, Thank you and Thank you.

vvita said...

We've been using a CSOM script to set default values in hundreds of libraries. Now, the script runs as usual, but documents are not inheriting default values set on libraries!

The Change Default Column Values show correctly on the library. However, when clicking the first column, the radio button option selected is the one for Do not specify a default value for this location. Setting the value manually, makes all other columns work! When setting this manually, a Source of Default Value column on the page switches from Document Library to This Folder.

Have you seen this? I don't find a way for CSOM to switch this column value? Thanks for any comments and help!

vvita said...

We've been using a CSOM script in the last month to set default values for libraries. Suddenly, the script runs as usual, but documents are not inheriting the default values.

I found that even though default values display on the Change Default Values page, they are not set. Clicking on the first column shows the radio button for Do not specify a default value for this location is selected. When I set the value manually, all other columns work! There is a column on this page named Source of Default Value that switches from Document Library to This folder when setting this manually. Obviously, the CSOM script is not modifying this.

Have you seen this behavior on SPO? I find no way to access the Source of Default Value to switch to This folder! Help, please!

beckie said...

If I'm trying to set the Default Column Values on a library using this method, but not using Managed Metadata, what modifications are necessary? (Trying to pass specs to a developer, as I'm just not one!)


elked said...

Wonderfull code :) Thx!

Arshad said...

Thank you.

Anonymous said...

Hi Steve,
I am getting this exact error "Unable to get property 'TaxonomyField' of undefined or null reference" when trying to access Autocomplete feature on WIKI page([[....
We are running SP2013 on SP2010 compatibility mode. And I was told by MS support it should work just fine...Any suggestions? Much appreciated,

Anonymous said...

Hi Steve,
I'm trying to get & set the Description of the Term(Tag) in a TermStore, in Sharepoint 2013.
Any idea on how to implement he GetDescription() & SetDescription()?
Althoug I can't tell the difference of the GetDescription() and GetDescription(Int32).
Any suggestion would be very much appreciated.

Thank you in advance.

Anonymous said...

Hi Steve,
Is there any way to get the Description of the Taxonomy Term, not the Label?Thank you in advance.

Post a Comment