Wednesday 25 November 2015

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:

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

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

stateYou 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_nameProvide 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_urlProvide 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_urlThe 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:

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!

No comments: