Using Office 365 Connectors for Groups in ASP.NET MVC

At Connect(); 2015, a new feature for Office 365 Groups called custom connectors was launched. With custom connectors, a new conversation can be started within an Office 365 Group programmatically, from your own custom application.

A very handy guide to custom connectors is available on the Outlook Dev Center: Office 365 Connectors for Groups (Developer Preview)

In this post, lets have a very simple look at how to use a custom connector from your ASP.NET MVC application.

The sample code for this post is available here: https://github.com/vman/Office365GroupsConnector

Before we get started, it is recommended to have SSL configured for your ASP.NET MVC application:
Configuring an ASP.NET project for development with SSL

1) The Connect to Office 365 button:

The way the connect to Office 365 button works is really simple, all it does is to redirect the user to the connectors page for Outlook and then after authentication, redirects the user back to a specified callback page. Here is the html for the button

	<a href="https://outlook.office.com/connectors/ConnectToO365?state=myAppsState&app_name=My Custom App&app_logo_url=http://www.catb.org/hacker-emblem/glider.png&callback_url=https://vrdmn.local.net:44301/Start">
	<img src="https://connecttoo365.blob.core.windows.net/images/ConnectToO365Button.png" alt="Connect to Office 365"></img>
	</a>

view raw connectbutton.html hosted with ❤ by GitHub

And the description for each query string parameter from the Outlook Dev Center page:

Parameter	Details
state	You can use the state parameter to save your application state. If you supply a value for state it is returned back to the specified callback_url when the application returns. This is an optional parameter.
app_name	Provide your application name. This name will show up in the authorization popup and in the connector list page that your users would see. The app_name is a mandatory parameter and can range from 1 to 100 characters.
app_logo_url	Provide the URL to your application logo. Ensure that the link is not behind an authentication wall and is publicly reachable. Use a logo of size under 10KB (preferably 256x256px) and type JPEG, PNG, GIF, TIFF, BPM, X-ICON or SVG+XML. The app_logo_url is a mandatory parameter.
callback_url	The callback URL should be a valid HTTPS URL without any query parameters. When the application returns successfully, the state passed, name and webhook URL of the selected group are returned as query parameters to the callback_url. If the application encounters a failure the state passed and the error code are returned to the callback_url.

This is how the button is rendered on your custom page:

2) Authentication:

When you click on the button, you are taken to the Office 365 Sign-in page if you are not already signed in. Next, you get a list of Office 365 Groups which you are a member of. You have to select a group in which the message will be posted, and click on Allow:

3) The Code:

The next step is to actually post the Office 365 Group card. Behind the scenes, I have used RestSharp in an MVC controller to make the post:

	public ActionResult PostMessage(string webHookUrl)
	{
	var client = new RestClient(webHookUrl);
	var request = new RestRequest(Method.POST);
	request.AddHeader("Content-Type", "application/json");
	request.RequestFormat = DataFormat.Json;
	request.AddBody(new
	{
	title = "Outlook Custom Connector Webhooks Demo",
	text = "Message posted from my ASP.NET MVC Appplication",
	themeColor = "DB4C3F"
	});
	var response = client.Execute(request);
	var content = response.Content;
	if (response.StatusCode == System.Net.HttpStatusCode.OK)
	{
	return View("Success");
	}
	else
	{
	return View();
	}
	}

view raw posttoo365group.cs hosted with ❤ by GitHub

4) Navigate to the Office 365 Group:

And if you now navigate to the Office 365 Group in Outlook, you will see 2 new messages, the first one is when the connection to the custom application is set:

And the next one is the actual message we posted from the MVC controller:

Thanks for reading!

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.

	var VRD = window.VRD || {};
	VRD.TranslationConfig = {
	TermSetId: "a772a1e4-8026-483d-91d4-f4fb0ec09cdf", //GUID of the Translations Term Set
	CacheKey: "VRD_translations" //Used to store the translation labels in the cache
	};
	VRD.Translation = (function ($) {
	"use strict";
	//Function to ensure that the init function only gets term store values once no matter how many times it is called from a page.
	var ensurize = function (promiseCallback) {
	var dfd = null;
	return function () {
	if (!dfd) {
	dfd = $.Deferred();
	promiseCallback().then(dfd.resolve, dfd.reject);
	}
	return dfd.promise();
	};
	};
	//Fetch the term labels and store them in the cache.
	var init = ensurize(function() {
	var deferred = new $.Deferred();
	var translations = getFromCache(VRD.TranslationConfig.CacheKey);
	if (translations === null) {
	SP.SOD.executeFunc("sp.js", "SP.ClientContext", function () {
	SP.SOD.registerSod("sp.taxonomy.js", SP.Utilities.Utility.getLayoutsPageUrl("sp.taxonomy.js"));
	SP.SOD.executeFunc("sp.taxonomy.js", "SP.Taxonomy.TaxonomySession", function () {
	//Get terms in the current user's language from the term store.
	var ctx = SP.ClientContext.get_current();
	var termStore = SP.Taxonomy.TaxonomySession.getTaxonomySession(ctx).getDefaultSiteCollectionTermStore();
	var termSet = termStore.getTermSet(VRD.TranslationConfig.TermSetId);
	var terms = termSet.getAllTerms();
	ctx.load(terms, 'Include(Name, LocalCustomProperties)');
	ctx.executeQueryAsync(function () {
	var termsEnumerator = terms.getEnumerator();
	var translationLabels = {};
	while (termsEnumerator.moveNext()) {
	//Build a JSON object
	var currentTerm = termsEnumerator.get_current();
	var labelID = currentTerm.get_localCustomProperties().TranslationID;
	var labelText = currentTerm.get_name();
	translationLabels[labelID] = labelText;
	}
	//Store the JSON object in the cache.
	setInCache(VRD.TranslationConfig.CacheKey, translationLabels);
	deferred.resolve(translationLabels);
	}, function (sender, args) {
	deferred.reject(sender, args)
	});
	});
	});
	}
	else {
	deferred.resolve(translations);
	}
	return deferred.promise();
	});
	function translate(translationID, elementID, containerID) {
	init().then(function () {
	//Get the label from cache
	var label = getLabel(translationID);
	//Add it to the html element.
	$(elementID).text(label);
	//The html element will be hidden by default. Show the element after translation to improve user experience.
	$(containerID).show();
	});
	}
	function getLabel(translationID) {
	var translationLabels = getFromCache(VRD.TranslationConfig.CacheKey);
	var label = translationLabels[translationID];
	return label;
	}
	//Temp function to demonstrate basic caching using session storage.
	function getFromCache(key) {
	var val = window.sessionStorage[key];
	if (val) {
	return JSON.parse(val);
	}
	else {
	return null;
	}
	}
	//Temp function to demonstrate basic caching using session storage.
	function setInCache(key, val) {
	if (key && val) {
	window.sessionStorage[key] = JSON.stringify(val);
	}
	}
	return {
	Init: init,
	GetLabel: getLabel,
	Translate: translate
	};
	})(jQuery);

view raw VRD.Translation.js hosted with ❤ by GitHub

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:

	<style>
	/*Hide the html elemets by default and show them after translation to improve user experience*/
	.CommContainer, .MarketingContainer, .NewsContainer {
	display: none;
	}
	</style>
	<div class="CommContainer">
	<span id="CommunicationElement">Communication</span>
	</div>
	<div class="MarketingContainer">
	<span id="MarketingElement">Marketing</span>
	</div>
	<div class="NewsContainer">
	<span id="NewsElement">News</span>
	</div>
	<script src="//code.jquery.com/jquery-1.11.3.min.js"></script>
	<script src="../Style Library/Scripts/VRD.Translation.js"></script>
	<script>
	VRD.Translation.Translate("MUITextCommunication", "#CommunicationElement", ".CommContainer");
	VRD.Translation.Translate("MUITextMarketing", "#MarketingElement", ".MarketingContainer");
	VRD.Translation.Translate("MUITextNews", "#NewsElement", ".NewsContainer");
	</script>

view raw Use_Translation.html hosted with ❤ by GitHub

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.

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:
Microsoft.SharePoint.Client.Publishing.DesignPackage.Install

There are a number of articles already covering this:

http://blog.symprogress.com/2013/07/apply-designpackage-using-client-object-model/

http://blogs.msdn.com/b/frank_marasco/archive/2014/08/10/upload-and-activate-sandbox-solutions-using-csom.aspx

The Office Dev Patterns and Practices project also uses this method to install a solution:
https://github.com/OfficeDev/PnP-Sites-Core/blob/master/Core/OfficeDevPnP.Core/AppModelExtensions/WebExtensions.cs

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:

	Add-Type -Path "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.dll"
	Add-Type -Path "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"
	Add-Type -Path "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Publishing.dll"
	#Utility function to authenticate CSOM and return the Client Context
	Function Authenticate-CSOM($siteUrl, $adminUsername, $secureAdminPassword) {
	$ctx = New-Object Microsoft.SharePoint.Client.ClientContext($siteUrl)
	$credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($adminUsername, $secureAdminPassword)
	$ctx.Credentials = $credentials
	return $ctx
	}
	Function InstallOrUpdateSolution($SiteUrl , $wspFullFilePath, $WspFileName, $wspPackageName, $majorVersion, $minorVersion, $scAdminUsername, $secureAdminPassword){
	$ctx = Authenticate-CSOM $SiteUrl $scAdminUsername $secureAdminPassword
	#Upload wsp to Solution Gallery
	Write-Host "Uploading file to Solution Gallery"
	$solutionGallery = $ctx.Web.Lists.GetByTitle("Solution Gallery")
	$solutionGalleryRootFolder = $solutionGallery.RootFolder
	$ctx.Load($solutionGallery)
	$ctx.Load($solutionGallery.RootFolder)
	$ctx.ExecuteQuery()
	$wspfileStream = New-Object System.IO.FileStream($wspFullFilePath, [System.IO.FileMode]::Open)
	#Create the FileCreationInformation object and prepare to upload it to the solution gallery
	$fileCI = New-Object Microsoft.SharePoint.Client.FileCreationInformation
	$fileCI.Overwrite = $true
	$fileCI.ContentStream = $wspfileStream
	$fileCI.URL = $WspFileName
	#upload the solution to the gallery
	$uploadedFile = $solutionGallery.RootFolder.Files.Add($fileCI);
	$ctx.Load($uploadedFile);
	$ctx.ExecuteQuery();
	Write-Host "done"
	#Install the solution
	Write-Host "Installing solution"
	#Create the DesignPackageInfo object
	$wsp = New-Object Microsoft.SharePoint.Client.Publishing.DesignPackageInfo
	$wsp.PackageGuid = [System.Guid]::Empty
	$wsp.PackageName = $wspPackageName
	$wsp.MajorVersion = $majorVersion
	$wsp.MinorVersion = $minorVersion
	#Install the solution from the file url
	$filerelativeurl = $solutionGallery.RootFolder.ServerRelativeUrl + "/" + $WspFileName;
	[Microsoft.SharePoint.Client.Publishing.DesignPackage]::Install($ctx, $ctx.Site, $wsp, $filerelativeurl)
	$ctx.ExecuteQuery()
	Write-Host "done"
	#Apply/Activate the solution
	Write-Host "Applying solution"
	[Microsoft.SharePoint.Client.Publishing.DesignPackage]::Apply($ctx, $ctx.Site, $wsp);
	$ctx.ExecuteQuery()
	Write-Host "done"
	#The Install and Apply methods create a copy of the solution. This copy is renamed according to the Major and Minor Version specified in the DesignPackageInfo object.
	#Once this copy is activated, we no longer need the original wsp file uploaded to the solution gallery.
	Write-Host "Deleting temporary files"
	$uploadedSolutionFile = $solutionGallery.rootFolder.Files.GetByUrl($filerelativeurl);
	$uploadedSolutionFile.DeleteObject();
	$ctx.ExecuteQuery()
	Write-Host "done"
	}

view raw InstallOrUpdateSolution.ps1 hosted with ❤ by GitHub

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:

	$siteUrl = "https://yoursite.sharepoint.com/sites/pub/"
	$fullWSPPath = "C:\v1\MySolution.wsp" #to differentiate v1 and v2 wsps, I have stored them in different folders called v1 and v2
	$wspFileName = "MySolution.wsp"
	$wspPackageName = "MySolution"
	$wspMajorVersion = 1 #important
	$wspMinorVersion = 0 #important
	$scAdminUserName = "scadmin@yoursite.onmicrosoft.com"
	$secureAdminPassword = $(convertto-securestring "password" -asplaintext -force)
	InstallOrUpdateSolution $siteUrl $fullWSPPath $wspFileName $wspPackageName $wspMajorVersion $wspMinorVersion $scAdminUserName $secureAdminPassword

view raw install.ps1 hosted with ❤ by GitHub

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.

	$siteUrl = "https://yoursite.sharepoint.com/sites/pub/"
	$fullWSPPath = "C:\v2\MySolution.wsp" #to differentiate v1 and v2 wsps, I have stored them in different folders called v1 and v2
	$wspFileName = "MySolution.wsp"
	$wspPackageName = "MySolution"
	$wspMajorVersion = 2 #important This will rename the wsp which will determine if your solution has to be updated.
	$wspMinorVersion = 0 #important
	$scAdminUserName = "scadmin@yoursite.onmicrosoft.com"
	$secureAdminPassword = $(convertto-securestring "password" -asplaintext -force)
	InstallOrUpdateSolution $siteUrl $fullWSPPath $wspFileName $wspPackageName $wspMajorVersion $wspMinorVersion $scAdminUserName $secureAdminPassword

view raw update.ps1 hosted with ❤ by GitHub

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. 

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 some CSOM code which updates 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:

	using Microsoft.SharePoint.Client;
	using Microsoft.SharePoint.Client.UserProfiles;
	using System.Security;
	namespace UpdateLanguagePreference
	{
	class Program
	{
	static void Main(string[] args)
	{
	//Tenant Admin Details
	string tenantAdministrationUrl = "https://yoursite-admin.sharepoint.com/";
	string tenantAdminLoginName = "tenantadmin@yoursite.onmicrosoft.com";
	string tenantAdminPassword = "password";
	//AccountName of the user whos property you want to update.
	//If you want to update properties of multiple users, you can fetch the accountnames through search.
	string UserAccountName = "i:0#.f|membership|user@yoursite.onmicrosoft.com";
	using (ClientContext clientContext = new ClientContext(tenantAdministrationUrl))
	{
	var passWord = new SecureString();
	foreach (char c in tenantAdminPassword.ToCharArray()) passWord.AppendChar(c);
	clientContext.Credentials = new SharePointOnlineCredentials(tenantAdminLoginName, passWord);
	// Display languages
	var muiLanguages = "en-GB,nl-NL,fr-BE,de-DE";
	var customRegionalSettings = "False"; //Override the site regional settings with custom settings for user.
	var locale = "2057"; //English (United Kingdom)
	//Full list of timezone id's available here: https://msdn.microsoft.com/library/microsoft.sharepoint.spregionalsettings.timezones.aspx
	var timeZoneID = "2";// "(UTC) Dublin, Edinburgh, Lisbon, London";
	// Get the people manager instance for tenant context
	PeopleManager peopleManager = new PeopleManager(clientContext);
	peopleManager.SetSingleValueProfileProperty(UserAccountName, "SPS-MUILanguages", muiLanguages);
	//This is important.
	peopleManager.SetSingleValueProfileProperty(UserAccountName, "SPS-RegionalSettings-FollowWeb", customRegionalSettings);
	peopleManager.SetSingleValueProfileProperty(UserAccountName, "SPS-Locale", locale);
	peopleManager.SetSingleValueProfileProperty(UserAccountName, "SPS-TimeZone", timeZoneID);
	clientContext.ExecuteQuery();
	}
	}
	}
	}

view raw Update_User_RegionalSettings.cs hosted with ❤ by GitHub

After update:

Thanks!