At its heart, Office365 facilitates collaboration. Sure, there are tools like Word, Excel, etc. But the bottom line is that Office365 helps you manage information, and it helps you do so between teams.
With that in mind, Microsoft introduced the concept of Office 365 Groups. A group is exactly what it sounds like: a number of people, a group, who want to work together. You create this group, and “hang” different things on the group.
For instance, a group can have a team site. In fact, modern team sites are backed by a group. The groups can have an email address and a shared inbox. But why stop there? They can also have a shared calendar, a shared OneNote notebook, planner etc. In fact, if you create a new group in Office365 and you examine the top tab bar, you’ll see these various things “hanging off” of the group.
Connectors is Office365’s mechanism of allowing numerous third-party services to push information into an Office365 team. The idea is that the team sets up a subscription to a connector. There’s so much information to stay on top of these days, such as tracking search results, Twitter feeds, news headlines, and so much more. Whenever the third-party has anything of value to contribute, it can push it into the team’s user interface via this connector.
Because connectors are aimed toward business users, setting one up is easy. It doesn’t require you to write any code; a connector can be set up using point-and-click. Just visit the team within your Outlook site, and on the tab, look for the Connectors link.
When you click on the Connectors tab, you’ll see a number of connectors to pick from. If any connectors are already configured, you’ll see the configuration details of those specific connectors. One of the simplest connectors is the “Bing News” connector. Go ahead and click on it and configure it.
That’s it. Hit Save and assuming that you have the permissions, the connector is set up. You’ll start seeing the information pushed by this connector inside the team’s inbox right away.
How does any connector work? Let’s think of connectors generically. The overall flow of the application can be seen below
You may be thinking that this sounds pretty straightforward. Can you write your own connector? Yup. It’s easy!
Incoming WebHook Connector
Writing Office 365 connectors can be accomplished in two ways. If you wish to have a connector that pushes information into a single team, you can use the Incoming WebHook connector. This greatly simplifies the task of writing connectors. If you wish to have your connector reused across multiple teams, then you might as well write a “real” connector.
Let’s first look at the process of using the Incoming WebHook connector. Creating an incoming WebHook is really easy. Just click on the Connectors tab under your team and look for Incoming WebHook. Click on it, and configure it, as shown below
When you click the “Create” button, you’re given a long and complex URL, as shown below
This URL is your key to pushing information out to the specified team. Copy and paste it into notepad because you’ll need it soon. Now to send a JSON card to your team via this newly configured incoming WebHook, all you need to do is send an HTTP POST message to the URL you got in the Incoming WebHook screen. You can do it as shown below
You’ll see the information pop up in your team’s page as shown below
But there is one small problem. Trying to re-use the same connector in multiple teams and having to set it up manually everywhere could mean a lot of manual work.
First, you need to register your connector at this URL: http://go.microsoft.com/fwlink/?linkid=780623. This page asks you to sign in using your Office 365 credentials and provides a simple user interface where you can register one or more connectors.
The form asks for a number of things. Most of them, such as name, logo etc., are self-explanatory, but the important ones are these:
- List the events supported by your connector. This is what the user will see. A single connector can support multiple events. For instance, your source control connector may have a separate event for successful or failed build. Perhaps the failed build could be set up differently, so it’s obviously different from a successful build. Maybe you want all developers to see a failed build notification but a successful build notification could be ignored.
- Landing page for your users. This is where users will see the Connect to Office 365 button. Of course, you can choose to have a different user experience, but the general idea here is that users will have a choice about using your connector. Clicking on that link within the Office 365 teams/connectors tab takes the user to this landing page. On this page, the user is expected to configure the connector. For instance, a Twitter connector may ask for search terms or a connector for your garage door may ask you for the events you’re interested in, such as “Garage door left open for > 15 minutes,” etc.
- Redirect URL: Once the connector is set up, Office 365 needs to communicate the endpoint to which you can push JSON cards. This endpoint URL is communicated to the Redirect URL. Your connector is expected to save this URL in a secure place.
Filling out this form and clicking the Save button gives you the HTML for the Connect to Office 365 button as shown below
Copy and paste the HTML shown in the above figure onto the landing page URL within your application. For dev purposes, you can use localhost. However, if you choose to use the “Publish to store” option, which is a matter of clicking a button on your app registration page, you’ll need to use a real URL.
<a href=”https://outlook.office.com/connectors/Connect?state=myAppsState&app_id=xxxxx-xxxx-xxxx-xxxx-xxxx&callback_url=https%3a%2f%2flocalhost%3a44361%2fHome%2fConnect”><img src=”https://o365connectors.blob.core.windows.net/images/ConnectToO365Button.png” alt=”Connect to Office 365″></img></a>
Query string parameters:
- state: An optional parameter that provides custom state information to the Redirect URL
- app_id: The identifier GUID for your application
- callback_url: The HTTPS Redirect URL for your connector registration
The Redirect URL, as I mentioned above, is a URL that your connector exposes. It receives the WebHook URL, which is the URL that you send JSON cards to.
Access the URL on the browser – https://outlook.office.com/connectors/Connect?state=myAppsState&app_id=xxxxx-xxxx-xxxx-xxxx-xxxx&callback_url=https%3a%2f%2flocalhost%3a44361%2fHome%2fConnect
Open Fiddler and Connect with your group
Check the Response on the fiddler
We are interested in this part
<h2>Object moved to <a href=”https://localhost:44361/Home/Connect?state=myAppsState&webhook_url=https%3A%2F%2Foutlook.office.com%2Fwebhook%2Fsomelongids&user_objectId=guid&app_type=Groups&group_name=someName“>here</a>.</h2>
Now close the Fiddler
Go to PostMan and post a card as shown below
And that’s basically it! As long as you send the request to the correct WebHook URL, along with a properly formatted JSON schema, you should see the cards appearing in the team’s inbox.
This article is originally posted on codemage.com.