Add TermStore Managers and Contributors using CSOM

A new version of CSOM was released today for SharePoint Online. You can find more information about that here: http://dev.office.com/blogs/new-sharepoint-csom-version-released-for-Office-365-may-2016

This version adds the ability to add/retrieve Managers and Contributors to a Term Group in the SharePoint Online Term Store.

Here is a quick code snippet I put together for achieving this:

Once executed, you can see that the Term Group in the Term Store is updated:

Search a Taxonomy term in a TermSet using JSOM

Here is some code I put together to search a term within a term set. This is for scenarios when you have a large term set and need to efficiently find a term with a specific label.

Here is a link which describes the exact combinations needed to make this work (Thanks Jose!)
https://msdn.microsoft.com/en-us/library/hh626704%28v=office.12%29.aspx

In this code, I am searching for all terms which start with an "A" in a term set which contains locations from around the world:

Note: I am using JSOM here but this also works with CSOM



Result:

Custom multilingual text in SharePoint Online using Taxonomy and JSOM

I have been working on an Office 365 intranet which will be rolled out globally. Naturally, one of the core requirements of the solution is that it should be multilingual. In my previous posts on this topic, Modify Site Regional and Language settings with JSOM and JavaScript, we had a look at how to set alternate languages for a site and in Update user language and regional settings with CSOM, we saw how to set the preferred display languages for a user.

This allows a user to see the SharePoint site chrome in their own preferred language. Now in this post, lets have a look at how to have localized custom text so that the user can see custom labels, headings etc. in their preferred language.

Some notes around this:

1) This approach is based on the multilingual features of SharePoint Term Sets:

It is possible to have multi-lingual term sets because each term in a term set has a unique ID and each term can have multiple labels. You can designate a default label for a term in each language available for a term store. A term can then have multiple synonyms in each of these languages, as well as labels and synonyms in other languages.

Users will also see managed terms displayed in their preferred language, regardless of the actual default language of the term store.

If no labels are specified for terms in the language in which a user is viewing a term, then the default label for the term in the default language of the term store will be displayed to users.

https://support.office.com/en-us/article/Work-with-multi-lingual-term-sets-D04098AF-282B-45C3-97CB-59363042C1B3

3) Based completely on JSOM, JavaScript and the SharePoint Term Store.

4) This approach is built on top of the MUI features in SharePoint. Which means that the user created content such as list item data, documents etc. will NOT be translated.

5) The SharePoint Online Term Store is treated as a "data source" for custom multilingual text. Each custom text is a term in the "Translations" term set. For each language that you have to support add a new label to the term for that language.

Lets get started:

1) Setup the Term Store to support term labels in multiple languages

I have set the default language of the Term Store as English and then added Dutch as a Working Language. This means that the term store will be able to support labels for a term in English as well as Dutch.

After adding the working languages, I have created a new Term Group called "My Group".
Under "My Group", I have created a Term Set called "Translations".
Under "Translations", I have created 3 terms: Communications, Marketing and News.
We will use these 3 terms to show the custom multilingual text.

We need to add the default language labels for each term:

After a label has been specified for each term, they will appear in the following way:

When English (default) is selected:

When Dutch is selected:

The translation framework will work in the following way:

If I am an English user and I have set my preferred language as English, when the terms for the "Translations" term set will be returned,  JSOM will return the English language labels by default. 

If I am a Dutch user and I have set my preferred language as Dutch, when the terms for the "Translations" term set will be returned,  JSOM will return the Dutch language labels by default. 

If I am an Italian user and have set Italian as my preferred language in my user profile,  SharePoint will return the English labels for the Translations term set as we have not selected Italian as one of the Working Languages of the Term store, nor have we set any labels in Italian.

2) Add Local Custom Properties to Terms

Next, we will add a local custom property for each term to identify it regardless of the language. This will serve as the ID of the term when we fetch it from JSOM:

This is the list of the local custom properties I have created for my terms:

Term	Local Property Name	Value
Communications	TranslationID	MUITextCommunication
Marketing	TranslationID	MUITextMarketing
News	TranslationID	MUITextNews

We could use the Term GUID here but I prefer using a custom ID as it is more readable. Also, if someone deletes one of the terms by mistake, it is easy to create a new Term and set the custom ID in the properties. If we were using a GUID, we would have to use code to create a new term with a specific GUID.

3) The Translation framework

After the Term Store is correctly setup, all we need to do is get the terms from the "Translations" term using the JavaScript Client Object Model (JSOM) and display them in the UI:

• Query the term store to get the terms from the "Translations" term set.
• SharePoint will return the term labels in the current user's preferred language if:
• The alternate language is enabled on the current site
• The current user has set the language as a preferred language in their user profile
• The term store supports the language as a "Working Language" as shown in step 1
• A default label is defined for the terms in that language.
• If any one of these conditions is not fulfilled, then the English labels for the terms will be fetched as it is the default language of the Term Store. 
• The term labels will be stored in the cache.

4) Performance/Caching

Since it is not advisable to make a call to the Term Store on every page load, it is a good idea to cache the labels for a particular user. My recommendation would be to use the browser web storage. Whether you use session storage or local storage depends on the implementation of the solution. MDN has a great article on this https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API

For demo purposes, I am using the sessionStorage and storing the term labels as a JSON object.

When the preferred language of the current user is English:

When the preferred language of the current user is Dutch:

5) Using the framework to show localized text

After the framework is correctly setup, all we need to do is call the framework correctly to show the custom text in the language of the current user:



When this code runs, if the preferred language of the current user is English, they will see the English text:

If the preferred language of the current user is Dutch, they will see the custom text in Dutch:

This way, you can utilize the multilingual features of the SharePoint Taxonomy Term Store to show multilingual custom text in your solution.

Custom Taxonomy Picker for Provider Hosted Apps

When working with SharePoint Online or developing cloud friendly solutions, it can be tricky to replicate some functionality which is easily available on-premises. We had a scenario recently where the user should be able to set values for a Managed Metadata user profile property. Now if this was a farm solution, we could have used a variety of methods like User Controls, Taxonomy Pickers etc. But since this was a Provider Hosted App, all those options were not available to us.

I knew that the Office Dev Patterns and Practices project has a cloud friendly taxonomy picker but that did not fit our requirements. It requires the creation of an App web in which sense it is not a "pure" provider hosted app. Also, there were some specific requirements around styling and business logic which meant that a custom Taxonomy Picker was the only way forward.

GitHub link for this project:
https://github.com/vman/CustomTaxonomyPicker

So without much further ado, here is how the custom User Profile property taxonomy picker looks:

1) When loaded first on a page, it gets the values from the "Skills" user profile property and displays them as tags:

2) When you start typing into the input box, the auto-complete suggestions are based on the "Keywords" termset. (You can change this to get terms from another termset)

3) When you are happy with the values, click on update and your Skills user profile property will be updated with the selected values:

And that's basically how it works from an end user perspective.

Advantages:

1)  Pure provider hosted app. No App web required.  If you are on-prem and in a big enterprise, this means that you don't have to wait for a wild card DNS entry to be setup. We all know how long that can take. This can be implemented as a pure provider hosted app because all calls to SharePoint are made by using CSOM in an MVC controller.

2) Complete control. Can be customized anyway you want. If you have specific business logic which needs to manipulate data before sending it to SharePoint, then you are easily able to do so.

3) Customisable UI: The jQuery Tag-It plugin is used in this taxonomy picker. It supports jQuery ui themes and a whole lot of other styling options. More about this in the Technical details section below.

Limitations:

1) As is, this control only works with SharePoint Online/Office 365. This is because the API for writing user profile properties is not yet available for SharePoint On-Premises. But if you are up for it, you can use the UserProfileService.asmx for accomplishing the same functionality. Check out this sample to see how to do it:
https://github.com/OfficeDev/PnP/tree/master/Samples/Core.UserProfilePropertyUpdater

2) At this time, it can only be used with user profile properties. If this has to work with Taxonomy fields in a list, you will have to modify the code but the principles behind the approach would stay the same.

But hey, the source is on GitHub so you don't get to complain! Submit a pull request and I will be happy to merge it :)

Technical Details:

1) Permissions:

Since the app interacts with the Managed Metadata Service and writes to the User Profile Service, the following permissions are needed:

2) jQuery Tag-It plugin:

The completely awesome jQuery Tag-It plugin is used to present the terms as tags in the UI. It provides a wide variety of options for selecting tags. It accepts a JavaScript array of values to show auto-complete suggestions.  Check out the plugin home page for more details.

3) Get current user's skills:

When the page loads, we need to get the skills for the current user to show them by default in the control, this can be done by making a simple call to the UserProfile Service.

4) Get terms from the Keywords termset:

To show the auto-complete suggestions, the Tag-It plugin requires a JavaScript array of values. We will use a MVC controller to get the keywords from the Managed Metadata Service and pass the values as a JavaScript array to the plugin. You can use any other termset to get your values. It would also be a good idea to cache these values in the browser localStorage so you don't have to make a call to the Managed Metadata service every time the control loads.

5) Update current user's skills:

When the Update button is clicked, another call is made to the Skills MVC controller which uses the recently released user profile write methods from CSOM. More about them on Vesa Juvonen's blog:
http://blogs.msdn.com/b/vesku/archive/2014/11/07/sharepoint-user-profile-properties-now-writable-with-csom.aspx

If you are on-premises, you can still use the UserProfileService.asmx for that. See this Office Dev PnP sample:
https://github.com/OfficeDev/PnP/tree/master/Samples/Core.UserProfilePropertyUpdater

Thanks for reading! Hope you found this useful.

Working with Taxonomy and JavaScript in SharePoint 2013

SharePoint 2013 has introduced some nice new features, one of which is the ability to manipulate managed metadata with the JavaScript Object Model. Unlike SharePoint 2010, we can now do a variety of operations with the Taxonomy Items in SharePoint 2013. Unfortunately, at the time of this writing, there is not a lot of documentation available on MSDN with regards to this particular feature.There is some preliminary documentation available for the Taxonomy in .NET Managed Client Object Model but the JavaScript API Reference has not been updated yet. So hopefully this blog will come in handy for someone looking to explore. All right lets get started:

First and foremost, you will have to load the SP.Taxonomy.js on your page explicitly as it is not loaded by default in SharePoint. Also make sure that you have loaded the SP.Runtime.js and SP.js files before continuing with your taxonomy code. Various errors like "SP.Taxonomy is not defined" or "Unable to get property 'TaxonomySession' of undefined or null reference" might come up if you have not loaded all the 3 necessary files on your page.

A simple way to load all the 3 files is with the jQuery.getScript function:



Now lets see some actual code which you can use to Manipulate the Taxonomy Items:

1) Query a particular Term Set and get all the Terms under it:

2) Create new Term Group under the Term Store:

3) Create new Term Set under a Term Group:

4) Create new Term under a Term Set:

5) Get Value of a Single Value Taxonomy Column in a List:

6) Get Values of a Multi Value Taxonomy Column in a List:

Hopefully you found this helpful. Happy SharePointing!