Posted by on Aug 24, 2016 in #Office365Dev | 0 comments

Office 365 connectors is a great way to enrich your Office 365 groups with content relevant to its members. It’s a way of creating a pipeline from other services, to feed into the conversation feeds of your Office 365 groups. Today, you’ll find many popular services already integrated with their own Office 365 connectors into Office 365 groups. Such as Twitter, Trello, Wunderlust, GitHub and many more. Users get engaged, without having to reach into these services individually. The content joins up in one place, relevant to the users.

In this post, we will look at the very basics of Office 365 connectors. This will introduce you how they work, and how you can go on about building your own – allowing users to connect their Office 365 groups with your services.

To start of, head into any Office 365 group and find the Connectors tab.

Connector2

In the Configurations tab, you can browse all of the available Office 365 connectors that you can add to the Office 365 group. In this blog post, we will use the Incoming Webhook connector. You can find it by either browsing through the list or searching for it. Once you have located it, click on the Add button.

IncomingWebhook

Once you’ve grasped the concept of how an Office 365 connector works, you’ll be able to publish your own Office 365 connectors. Using the existing Incoming Webhook connector will allow us to get going faster. Start small, and build your way up.

Enter a name for your Incoming Webhook connector and click on the Create button.

ConnectorConfig

This will create the Incoming Webhook connector and generate a webhook URL. Save this (you’ll need it) and click on the Done button.

What is a webhook? In short, it’s a registered URL (or callback if you will) for which you can send payloads. This is mostly done via a HTTP POST request message, which is what we will do. This concept is usually driven by events and notifications. For instance, you can register a webhook (from your service) with Office 365 that would notify that URL once a certain event has occurred within Office 365 (http://graph.microsoft.io/en-us/docs/api-reference/beta/resources/webhooks). In this reversed case, it’ll be you that notifies an Office 365 group about something that happened in your own service. Adding to the conversation feeds. You can read more about webhooks here: https://webhooks.pbworks.com/w/page/13385124/FrontPage

When the Incoming Webhook has been created, you’ll find a card like this in your conversation feed.

ConnectorSetup

These cards is what you’ll be creating with the Incoming Webhook or any Office 365 connect for that matter. They can be as simple as the one above, to more complex. These are defined by a JSON payload. Meaning you are simply instructing what should be included within the card, but the client owns the responsibility to render the card. Saving you a lot of time.

Below is a couple of examples of the JSON payload. Here’s a simple one:

A more complex one, which is what I’ll use in this blog post:

The above attributes/properties are fairly straight forward. You’ll be able to figure out most of them on your own. For anything else, the following reference is a great place to lookup the available attributes: https://dev.outlook.com/connectors/reference 

A section defines an area which contains a set of potential attributes (such as a title, images and more). At the bottom, you’ll find a potentialAction. This is an action which the user can take (for instance by clicking a button). The ViewAction type (noted by the @type attribute) allows you to create a button with a target URL to be viewed.

To send this payload, you can use whatever development stack that you’re familiar with. I created a simple C# console application to illustrate the concept. Be sure to append the Content-Type header (as application/json) in the request message. Create an HTTP POST message and send it to the webhook URL that we created with the Incoming Webhook connector. Be sure to replace the WebhookUrl with your own.

Should everything go well, you’ll find both an OK in the console application – but also a new card in the Office 365 group conversation feed.

ConnectorSuccess

I’m using the more complex card (JSON payload) in my request message (it even contains GIFs!). What you see above is what gets rendered – without me having to express anything in terms of rendering. Bear in mind that this is only one of many surface areas for the conversation feeds, so not having to considering this part (rendering) is huge. Office 365 groups and Outlook (as of right now) will take care of making sure that your cards are displayed properly. Your job is to supply to best and most relevant elements that make up the cards!

You can learn more about Office 365 connectors and how to build them here: https://dev.outlook.com/Connectors

The following GitHub repository by Richard diZerega (richdizz) also contains a ton of useful resources: https://github.com/OfficeDev/Office-365-Connectors

-Simon Jaeger