Tuesday, 17 November 2015

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.


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:

Local Property Name

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.

Monday, 16 November 2015

Install and Update Sandbox Solutions with CSOM

So recently, I was working on a SharePoint Online project and was looking for a way to automate the installation and update of a No Code Sandbox Solution (NCSS).

I was aware that you can install and activate Sandbox solutions in SPO with the following CSOM method:

There are a number of articles already covering this:



The Office Dev Patterns and Practices project also uses this method to install a solution:

Just so you know, there are a couple of caveats to this approach as mentioned in the PnP documentation:
// NOTE: The lines below (in OfficeDev PnP) wipe/clear all items in the composed looks aka design catalog (_catalogs/design, list template 124).
Also, installing and activating the solution with this method will also automatically activate all Site-Collection level features, even if they have been set to AutoActivate = False

What I have found is, by changing the Major and Minor version numbers (which renames the WSP), you can also use the same method to update an existing solution

Here is my PowerShell script which Installs a solution (if it does not already exist) or updates it if the solution already exists, and the Major or Minor version number is different.

The PowerShell script:

The script is straightforward and similar to the other posts. The main difference from the PnP version being I do not run the DesignPackage.Uninstall method before Installing the solution and I also run the DesignPackage.Apply method after Installing the solution

1) Install a Solution:

After the script is run, I can see my WSP installed in the solution gallery with the Major and Minor versions I specified:

2) Update a Solution:

To update the solution, first we will need an updated WSP. It should have the relevant sections specified in the UpgradeActions Feature XML element.
@cann0nf0dder has a great post on configuring a sandbox solution for update here: Upgrading Sandbox Solutions in SharePoint

Once you have the updated WSP, all you need to do is change the Major and Minor version numbers in the script and Install your new WSP.

After the script is run, I can see my WSP is updated to the new version in the solution gallery with the Major and Minor versions I specified:

This way, the same DesignPackage.Install and DesignPackage.Apply methods can be used for updating sandbox solutions in SharePoint Online. 

Friday, 13 November 2015

Update user language and regional settings with CSOM

Following my previous post around multilingual aspects of SharePoint Online: Modify Site Regional and Language settings with JSOM and JavaScript

Here is a bunch of CSOM code which will update the personal regional settings of the current user or another user (if you are a tenant admin and have the rights to update user profiles):

Before update:

The code:

After update:


Tuesday, 11 August 2015

Avoid customizing the SharePoint Online root site collection

I had an interesting decision to make recently: Should the root site collection of the SharePoint Online tenant be used to host the main intranet landing site? A very common requirement for a SharePoint Online project is a customized landing site with the company's branding, logo and some custom functionality. You might refer to this as the Home page, Intranet home, Portal site, News hub etc. It's a site where the users will first land when they arrive on the Intranet/Digital Workspace.

So where should this site be located? Right now, I would NOT recommend this to be the root site collection in SharePoint Online (https://tenant.sharepoint.com) It is much more convenient to use another site collection like /sites/intranet or /sites/portal etc. In fact, I would recommend that the root site collection should be left alone and no customizations should be deployed to it. Here are the reasons why:

1) Custom Scripts

In the SharePoint Online admin portal, you can assign a site collection under which the self-service sites will be created. (by default it is the root site collection of the tenant e.g. https://tenant.sharepoint.com) So whenever a user creates a self-service site, it will be created as a sub site of this site collection.

SharePoint Online also gives you the ability to turn off custom scripts on self-service created sites. (The default is that custom scripts are NOT allowed on self service sites). This is to prevent users from injecting scripts into web parts and compromising the integrity of the site. This article describes this feature in detail:

But what the article does not mention is that the custom scripts are disabled only on the site collection (and its sub sites) which is assigned for creating self service sites. All other site collections in the tenant can still run custom scripts.  I have highlighted the relevant areas in the image below:

(click to zoom)

Now just to recap, here are the defaults when you create a new Office 365 tenant:

1) Root Site collection is assigned for creating self service sites.
2) Custom Scripts are turned OFF for the site collection under which the self service sites will be created. 

Naturally, your customized intranet portal will have lots of JSOM or REST API/Ajax code embedded in Script Editor or Content Editor Web Parts. If this custom site is to be located at the root site collection, you will have to change at least one of these default settings. Either nominate a different site collection for creating the self service sites or change the Custom Scripts option to "Allow users to run custom script on self-service created sites"

Depending on how strict the governance is, changing default settings can be easy in some cases but more often that not, you will have to have a valid reason if you are going to do this in production tenants. 

2) Root Site collection cannot be created using PowerShell Cmdlets

There is a limitation in the SPO PowerShell Cmdlets which prevents you from creating the root Site collection. When you try doing so, you get the following error:

Now in most projects I have worked on, we have had a deployment script which runs off the build server. For integration testing, the deployment script creates a new site collection once every day and deploys the latest code to it. If you have a similar continuous integration process, you will not be able to create a new root site collection with the deployment script. It will have to be a manual step each time the deployment is done. This can get bit annoying.

3) No flexibility to delete and re-create the Site collection as everything else stops working. 

If something goes wrong in the deployment or some site columns or content types are corrupted, I do like to have the flexibility to delete the site collection and start afresh by creating a new one with the same url.  This is not really an option if you are deploying to the root site collection.

If you delete the root site collection, all other site collections in the tenant will stop working. I have also observed that SharePoint Search also stops working. This is why when you try to delete the root site collection from the admin portal, you get a big red warning message:

(click to zoom)

Now if this is a developer tenant and multiple developers are working in their own site collections, they will be blocked until a new site collection is created at the root.

If this is a production tenant and something else like the collaboration solution is already deployed to another site collection in the tenant, it will also stop working.  

The reason for this seems to be that when a user wants to navigate to any site collection in the tenant, the authentication is done via a page located in the root site. If the root site collection is missing, the user cannot be authenticated and hence cannot navigate to any site collection.

(click to zoom)

Due to all these reasons, I feel that the root site collection is an important piece for SharePoint Online to work correctly. I recommend treating it as you would treat a configuration site. It is best to leave it alone and not deploy any customizations to it.

Hope you find this article helpful!

Thursday, 6 August 2015

Modify Site Regional and Language settings with JSOM and JavaScript

Recently, the ability to modify the Regional and Language settings of a site has been added to the client APIs in SharePoint 2013 and SharePoint Online. While the support for SharePoint 2013 was added in the December 2014 CU (as announced by Vesa here), the support for SharePoint Online has been a more recent addition.

There are some really nice code examples for the CSOM Regional and Language APIs in the Office Dev PnP Library:

But, I could not find JSOM code example of these APIs. So I am listing down some of the most frequently used Regional and Language functions here.

1) Add a Supported UI Language:

2) Remove a Supported UI Language:

3) Disable Multi Lingual and Remove all UI Languages:

4) Get Regional Settings:

A full list of all the regional settings properties is available here:

5) Set Regional Settings:

6) Set Time Zone of a site:

This one was a bit tricky but I finally got there in the end. You will need to know the ID of the Time Zone you want to set in the site. A full list of SharePoint TimeZone IDs is here:

Hope this helps!

Sunday, 26 July 2015

JSOM Provisioning: Creating SharePoint artifacts without declarative XML

The recent guidance from Microsoft regarding the provisioning of SharePoint artifacts is pretty clear. The recommendation is to completely move away from declarative creation of Site Columns, Content Types etc. and instead, create them completely from code.

To support this approach of programmatically creating artifacts, a lot of work is being done on the "Provisioning Engine" in the OfficeDev Patterns and Practices Library on GitHub. To put it very simply, the Provisioning Engine reads a predefined XML file called the "PnP Provisioning Schema" and creates all the SharePoint artifacts using CSOM. Since this engine predominantly uses C#/.NET, it is expected to be run from somewhere like an Azure Web Job, a Web Application on an IIS server or a simple console application.

This method of provisioning is great for clients who opt for Azure subscriptions or IIS servers along with their SharePoint roll-outs. But this is not necessarily true with clients who only want to go for SharePoint or who do not have enough budget for additional Azure or IIS installs. So far, the only option in these cases is to go with the traditional declarative XML based provisioning using No Code Sandbox Solutions (NCSS). This approach is still valid at this time and Microsoft has stated that No Code Sandbox Solutions continue to remain supported:

Still, in this post I am going to explore another form of provisioning SharePoint artifacts completely based on the JavaScript Object Model (JSOM). Since the provisioning is done completely from JavaScript running in the browser, there is no need for a platform like Azure or IIS to run this code. I came across the following project in Office Dev PnP which shows how to use a SharePoint hosted Add-In (App) to create artifacts like Site Columns and Content Types etc. in the host web.


Some code examples from the project:

1) Create Site Column:

2) Create Content Type:

Here are my observations about this approach:

1) This project uses a SharePoint Hosted Add-In (App) to run the JSOM code. But with a few modifications, it can be made to run from a JavaScript file provisioned to a document library with a No Code Sandbox solution. The readme file of this solution mentions an additional project "Provisioning.Jsom.Ncss" which seems to be missing from the solution. My guess is this project did the exact same thing. With this approach, we remove the dependency on the Add-In (App) Model for provisioning.

2) Currently for values like site column names, types, content type names etc hard coded strings are being used. This can be modified to be read from an XML file, preferably the PnP Provisioning Schema. The schema XML file can be deployed with the Provisioning JavaScript file in the NCSS itself.

3) This approach can be used to create sub sites but not site collections as there is no way right now to create site collections through JSOM. So the deployment process will have to be manual creation of a Site Collection with an empty web template, and then to upload the WSP which will deploy the JS file to the SharePoint site. This file will then do the artifact provisioning.

I am going to explore these options and will post something in the future around this approach.

Thanks for reading. Hope you find this information useful in some way!

Friday, 8 May 2015

Using the Microsoft Graph (Office 365 Unified API) in ASP.NET MVC

In my previous post, I wrote about Getting started with the Office 365 Unified API. In that post, I introduced the new Office 365 Unified API and created a basic console application which used Azure AD for authentication and consumed the Office 365 Unified API. But chances are that a console application is not going to be a solution to most of your business needs. That is why, in this post we will see how the Office 365 Unified API can be used in an ASP.NET MVC application.

The complete code for this blog post is available on GitHub: https://github.com/vman/O365UnifiedAPIMVC

Full credit to Jason Johnston's article Getting Started with the Outlook Mail API and ASP.NET on which I have based my code.

The Authentication flow:

Since the Office 365 Unified API uses Azure AD for authentication, these are the basic steps to get your application authenticated:

1) Request an authorization code

2) Request an access token based on the authorization code. (when you successfully make this request, you also get back the refresh token along with the access token)

3) Make a request to the desired resource e.g. "https://graph.microsoft.com/beta/myOrganization/users" using the access token.

4) When the access token expires, use the refresh token to get a new access token instead of going through the entire authentication flow again.

See the following links for more details on the Office 365 Unified API and the Azure AD authentication flow:

Authorization Code Grant Flow

Office 365 Unified REST API authentication flow

Register your application in Azure AD:

Now let's get started on how to actually go through this process in an MVC application.

As mentioned in my previous post, the very first thing you need to do is register your application in Azure AD. Here are the steps to do that:


I have registered a Web Application in this case and here are the permissions I have granted:

Windows Azure Active Directory:
  • Access your Organization's Directory

Office 365 unified API (preview): 
  • Read and write all users' full profiles
  • Access directory as the signed in user
  • Enable sign-in and read user profile

If the Office 365 unified API (preview) application is not available by default, click on "add application" and add it.

After you register your application, copy the ClientID and the ClientSecret in the web.config file of your MVC application.

    <add key="ida:ClientID" value="your client id" />
    <add key="ida:ClientSecret" value="your client secret" />

Now that the application is successfully registered in Azure AD, we can go ahead and write the code for the authentication flow in our MVC app.

The ASP.NET MVC Application:

The first thing you need to do now is to get the following NuGet package installed in your project:

Active Directory Authentication Library 2.14.201151115

Alright, we are finally ready to write some code now :)

In your MVC Controller, create an action called SignIn. We will use this action to redirect the application to the Azure AD Authorization Request Url:

This will take the application to the Azure AD login page where the user will have to enter his/her credentials. Once the credentials are successfully authenticated, the application will be taken to the redirectUrl mentioned in the code. This redirectUrl is a url to another Action in our MVC app. At this time, the url will also contain the Authorization code mentioned in step 1 and 2 above.

The Authorize action mentioned in the redirectUrl looks like this:

This will get the Authentication code from the request parameters. Based on the Authentication code, it will make a call to Azure AD to get the Access token. Once we get the Access token, we will store it in the session so that we can use it for multiple requests.

A production level solution will probably need a better mechanism to store the Access token. Andrew Connell has written a great article on storing the access token in a database. See the article here:

Azure AD & ASP.NET MVC - Walk-Through Implementing ADAL & OWIN

Now that we have a valid Access token, we are ready to actually make a call to the Office 365 Unified API resource to get data. I have used a simple HttpClient to make the REST call

Once the call is successful, you get JSON back which then you are free to mangle in your code.

In my sample application, I have also written calls for getting all the users from the tenant and the tenant details. Check it out here: https://github.com/vman/O365UnifiedAPIMVC

Additional Reading/Fiddling:

Here is the complete list of REST calls you can currently make using the Office 365 Unified API:

Office 365 unified API reference (preview)

Also, if you want to try out REST API without actually writing any code, this is a great tool which can help you make calls and see the response: http://graphexplorer2.azurewebsites.net/

Only thing is you will need credentials to install the application in your Azure Tenant.

Hope you found this post useful!