Working with the TaxonomyClientService: Part 4 – Populating Values with the Lists web service

So far I’ve discussed how to get information about getting the types of taxonomy field, working with those fields, and how to get term sets. What about setting values on list items?

It isn’t immediately obvious how to do that. For a start, we wouldn’t actually be using the TaxonomyClientService. To set values on items, you use the Lists web service, using the UpdateListItems() method. This accepts XML describing the field and values.

But what fields do we submit, and what values? After all, as mentioned in part 1, there are two fields – one for the displayed value, and a hidden ‘notes’ field that contains the actual data!

There was no documentation about how to set these values, and limited and contradictory information in blog posts, so I investigated…

What you send depends on the type of field you’re trying to set. Normal managed metadata fields are different to the Enterprise Keywords field.

For normal taxonomy fields – either single or multiple values – you send an empty ‘display’ field, and populate the hidden field as below. This shows single and multi valued fields respectively, and the ‘_0’ fields are the hidden notes fields:

<Field Name='SomeField'></Field>
<Field Name='SomeField_0'>TermName1|12345678-0000-0000-0000-1234567890AB</Field>
<Field Name='SomeField2'></Field>
<Field Name='SomeField2_0'>TermName1|12345678-0000-0000-0000-1234567890AB;TermName2|98765432-0000-0000-0000-BA0987654321</Field>

There are a number of blogs out there that suggest that you need to submit your term’s display name in the display field. You don’t. You also don’t need to submit term IDs, GUIDs or otherwise.

There are also blog posts suggesting that your values you submit to the hidden notes field have to be of the form:

2;#My Term|d511f3c7-377f-480f-aff6-beebecd3c675

In this form, the ‘2’ would represent the term description on the hidden list of taxonomy terms that is stored in the site collection. (I think that this is effectively a cache, though quite why I’m not too sure)

There’s a problem with that though. To submit terms in that form we’d have to look up their ID on that cache list (which is laborious, and it’s a different value for each site collection). Also, what if the term hasn’t been cached already?

Well, other blogs posts (I’m afraid I’ve lost their reference) say that you should submit your values in the form:

-1;#My Term|d511f3c7-377f-480f-aff6-beebecd3c675

The ‘-1’ is supposed to represent the fact that you don’t know what the ID is. But if you don’t know that, how does it get filled in?

Well, there is an event handler that runs for all lists that use a Managed Metadata field. It looks after populating the hidden list of taxonomy terms, and it will insert that ID into the value of an item. It also populates the display text for that Managed Metadata field, which is why we can submit an empty value to that field.

And, in fact, the ‘-1’ is not only unnecessary – that event handler is smart enough to recognise if there is no ID of the term on the hidden list being submitted – but if you want your values to look exactly the same as standard SharePoint’s values, then you should submit your value in the form:

#My Term|d511f3c7-377f-480f-aff6-beebecd3c675

Submitting a value with -1 at the start of it does work – but the value stored internally is not identical to the value that would be stored if you had set it using the SharePoint User Interface.

Now, all of that was for normal Managed Metadata fields…

Enterprise Keyword fields accepted values of a slightly different format. For reasons I can’t quite fathom, you seem to have to submit your values in the form:

<Field Name='TaxKeyword'>;#</Field>
<Field Name='TaxKeywordTaxHTField'>TermName1|12345678-0000-0000-0000-1234567890AB;TermName2|98765432-0000-0000-0000-BA0987654321</Field>

Note that the ‘Display’ field has a value of ;# submitted to it. I don’t know why (again, I found this input via exhaustive seach), but the Enterprise Keywords field does not work if you submit an empty value for that field (as you would for a normal managed metadata field).

Bonus information: As others have noted, the Enterprise Keywords fields will always have the same names and GUIDs to identify them:

  • TaxKeyword – {23F27201-BEE3-471E-B2E7-B64FD8B7CA38}
  • TaxKeywordTaxHTField – {1390A86A-23DA-45F0-8EFE-EF36EDADFB39}

(For those of you interested, I determined the correct input by filling in a number of fields using SharePoint’s user interface. I then looked at the raw data stored against the list item for them.

Then I wrote a console application that used the web service to set those fields, and compared the value that was actually stored with the example values. The console application tried lots of different inputs – various combinations of having a lead ID, of that ID being zero or -1, of having the term text, of having the term GUID, separating values with ; or with ;# etc. – to determine what formats resulted in the correct output. What I’ve written above is based on those tests, and I’ve used these formats of input for an application that I’ve written, and it seems to be working okay.)

Working with the TaxonomyClientService: Part 4 – Populating Values with the Lists web service

One thought on “Working with the TaxonomyClientService: Part 4 – Populating Values with the Lists web service

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.