TaxonomyClientService.AddTerms Wrong Documentation

I’ve been working lately on a project that requires access to the Managed Metadata Service in SP2010.  I got to a point where I needed to add a term to the default term store under a term set.

I have some code in my project that takes in the following parameters and creates a term in the term store:

– TaxonomyClientService proxy instance

– Term name

– Term store ID

– Term Set ID

I needed to use the AddTerm method of the proxy to create a new term, and spent most of my afternoon wrestling with the format of the NewTerms parameter of the method.

The following MSDN documentation is wrong! (here) – or at least not informative.

The MSDN documentation stipulates to use NewTerm nodes to wrap new terms in the XML passed to the service.  What the documentation did not tell me was:

1. The term set must be open, otherwise the method returns an empty string.

2. The method need the exact syntax for the XML to work – looking on the web, I found no real answer to this problem, and ended up reflecting the web service code to get my answer.  Below is a sample piece of XML.

<newTerms><newTerm label="MyTerm" clientId="1" parentTermId="GUID of parent or empty GUID if none"></newTerm></newTerms>

Worth noting with the above XML…

1. Notice the lowercase use of newTerms and newTerm (not uppercase N as in the MSDN documentation)

2. clientId does very little and so you can pass the value 1

3. The parentTermId must be a real GUID, and Guid.Empty if no parent

4. New terms wrap in the newTerms node, which MSDN failed to mention.

I hope this post saves others an afternoon worth of work, which it cost me.

8 thoughts on “TaxonomyClientService.AddTerms Wrong Documentation

  1. Abin

    I am trying to add terms into my Office 365 site’s term store using taxonomyclientservice.asmx from my Client ASP.NET application. I am passing authentication cookies correctly and is authorized correctly because i can access the list data . My problem is ,that its not adding terms to termstore and always AddTerms() Method returns null. Here is code I am using.

    helper = new MsOnlineClaimsHelper(

    Taxonomywebservice txnmyWebService = new Taxonomywebservice();

    CookieCollection cookieColl = helper.CookieContainer.GetCookies(new Uri(“”));

    txnmyWebService.CookieContainer = new CookieContainer();

    string sspIds = “cf1a07fc-9293-4903-a066-c1967afc6998”;
    string termSetId = “c3945e82-4873-4429-95cf-cc9b87689455″;

    string newTerms = @”


    // AddTerms is always returning Null. I am trying to AMERICAS just under my termset

    string result = txnmyWebService.AddTerms(new Guid(sspIds), new Guid(termSetId), CultureInfo.CurrentCulture.LCID, newTerms);

    Why it is always returning Null?. PLease help me….

  2. Pingback: MetaData Navigation « Sladescross's Blog

  3. Bhavna

    Hi Rob,

    I have been facing the issue with the AddTerms method of the Taxonomy web service. I used the same structure for the term as you mentioned. But the web method returns only a string with value: ”

    I have checked the term store Submission policy and it is Open. I dont know what could be the issue. 🙁

    Please help.


  4. Bhavna

    Pasted the code for your reference:

    string strSSPID = “cb1d4195-fd96-4a55-8007-324928f90676”;
    string strTermSetId = “c96c4bc7-b355-43be-90ab-98b07b69d903″;

    TaxonomyService.TaxonomywebserviceSoapClient ts = new TaxonomyService.TaxonomywebserviceSoapClient();

    ts.ClientCredentials.Windows.ClientCredential = System.Net.CredentialCache.DefaultNetworkCredentials;
    ts.ClientCredentials.Windows.AllowedImpersonationLevel = System.Security.Principal.TokenImpersonationLevel.Impersonation;

    string newTermID = string.Empty;

    string newTerm = @”

    newTermID = ts.AddTerms(new Guid(strSSPID), new Guid(strTermSetId), 1033, newTerm);

  5. John

    Thanks Rob, you are a life saver! Couldn’t work out what to put for the newTerm until I found your article.

Comments are closed.