Let’s be honest: The developer story from SharePoint on-premises to Office365 hasn’t been a straight line. There have been diversions into sandbox solutions, and we’ve dealt with the demons of add-ins and the marketplace. On this journey, we’ve gone from a poor dev story to a pretty compelling dev story today. And if you’ve grown tired of keeping up with the changes, now is a very good time to give things a good second look. The Of ce 365 dev story these days is a combina- tion of many choices. You have to examine the problem as, “Do I want to integrate Office365 into my applica- tion?” or “Do I want to integrate my application into Office365?”
Both scenarios are equally valid.
If you wish to integrate Office365 into your application, you have Microsoft Graph, Azure AD graph, and a deep understanding of Azure AD from a developer point of view to master. Those, paired with your existing skills, on any platform, allow you to integrate Office365 into your application. For example, let’s say that you have a website that sells services to consumers. You require that this website follow your corporate branding guidelines. You don’t want to show the waf e menu on the top, or perhaps you don’t care about any SharePoint functional- ity. However, you do care about showing calendars of the employees on your website. Using Microsoft Graph, you can easily tap into calendar information of the employ- ees in your organization and display them on whatever form you consider appropriate on your highly branded website.
On the other hand, perhaps you want to surface your applications in various well-designated places in Office365. For instance, you may want to surface up a bot or a tab in a team. Or maybe you want to surface up your application as a WebPart on a SharePoint site. Maybe you want to push information into a team.
Increasingly, I see these two camps as the defining paradigm of developing for Office365. And both of these paradigms, thankfully, are being driven by well-accepted standards. There’s a new propensity at Microsoft now to leverage community standards and open source. This means that your skills are portable. If you invest your time in Office365, those skills are not worthless when you need to develop for something other than Office365. And if you invest your time in other technologies, those skills are quite useful in Office365.
In this article, I’ll introduce one such open standard called WebHooks, followed by how Office365 can listen to your WebHooks via connectors. In Part 2 of this ar- ticle (in an issue of CODE Magazine coming soon), I’ll talk about how you can subscribe to WebHooks that Office365 exposes.
Think of it this way: Office365 connectors are how your application can integrate into Office365. And WebHooks exposed by Office365 is how you can integrate Office365 into your applications. Both techniques use the standard WebHooks technique. As I mentioned, WebHooks is an open standard tool, and Office365 currently supports WebHooks only on lists, OneDrive, and mail, but this list will most likely grow.
What Are WebHooks?
WebHooks are user-de ned HTTP callbacks. The problem they intend to solve is “pushing” information to you. Pushing is an unusually complex problem to solve. We’ve gotten so used to server-based applications, such as Office365 resources, to expose a REST API that you “pull” information from. Your application makes an HTTP call to nd out if there is anything new. Pull works, but has some distinct disadvantages. It’s certainly not respon- sive enough for real-time operations, such as chat. And more importantly, it puts an undue load on both your application and the server.
Push, on the other hand would be nice, except, that Office365 (or any server-based resource) doesn’t know where or who to push to. WebHook is an architectural pattern that aims to solve this issue.
Put simply, if you want SharePoint to inform you that a list has changed, you need to get an HTTP POST from Office365 to an endpoint that you expose. Before Office365 can send you a push, it needs to know where to send the push. A WebHook starts with subscribing to an end- point where you express that you’re interested in learn- ing about a speci c noti cation, and that you’d like to be informed at such-and-such endpoint, which that server- based resource can push information or noti cations to.
Before this subscription is considered valid, the server- based resource veri es that there’s an endpoint listening. And if an endpoint is indeed there, the subscription is created. In the future when the event occurs, this end- point is called.
Of course, there are many other nuances to be consid- ered, such as how long should such a noti cation subscription last? If the listener isn’t around to receive a push request, should there be any retry logic? How quickly should your endpoint respond? Should you send secure information in a push? How do you ensure that the server you created a subscription to is the one push- ing the information?
Every platform implements things differently. In Office365, the behavior is as follows:
- The subscription lasts for a maximum of six months.
- There is a retry logic built that retires every five minutes.
- Your endpoint is expected to respond within five seconds. This time is intentionally short to reduce load on Office365 server resources and prevent DDoS scenarios.
- No secure information is sent and you’re expected to call back and get the nature of changes. The WebHook simply noti es you that “something has changed.” This is a good implementation because you want the WebHook to be responsive, and you can only make it responsive if the request size is predictable. Also, not sending sensitive informa- tion on a push noti cation is more secure.
- You can be sure, as a recipient of a push, that the push came from who you subscribed to, by provid- ing a validation code during your subscription. This validation code is your shared secret between Office365 and your service.
Office365 Connectors
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, Mi- crosoft introduced the concept of Office365 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, mod- ern 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.
- Many useful and common tabs are already present. You can add more tabs, too, which is one way to surface up your applications inside Of ce 365, speci cally applications targeted toward a particular group. Notice that a rather interesting tab is already present: Connectors.
Connectors is Office365’s mechanism of allowing numer- ous third-party services to push information into an Office365 team. The idea is that the team sets up a subscrip- tion to a connector. There’s so much information to stay on top of these days, such as tracking search results, Twit- ter 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.
Setting Up the Out-of-the-Box Connector
Because connectors are aimed toward business users, set- ting 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 num- ber of connectors to pick from. If any connectors are al- ready con gured, you’ll see the con guration details of those speci c connectors. One of the simplest connectors is the “Bing News” connector. Go ahead and click on it and con gure it.
That’s it. Hit Save and assuming that you have the per- missions, the connector is set up. You’ll start seeing the information pushed by this connector inside the team’s inbox right away.
How Does It Work?
How does any connector work? Let’s think of connectors generically. The overall ow of the application.
As you can see from Figure 3, when a user wishes to ac- cess any connector, they’re presented with a simple HTML UI, usually a “Connect to Of ce 365” button. It doesn’t have to look exactly like that, but consistency is good, so users know what to expect. The user clicks on that button and is prompted to grant access to the connector. As- suming the user has the rights, your app now gets a URL to which it can push information. These pushes are done using HTTP POST requests, and are sent as JSON objects in a speci c schema. Of ce 365 connectors likes to call them JSON Cards.
You may be thinking that this sounds pretty straightfor- ward. Can you write your own connector? Yup. It’s easy!
Using the Incoming WebHook Connector
Writing Of ce 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 Incom- ing WebHook connector. This greatly simpli es the task of writing connectors. If you wish to have your connec- tor reused across multiple teams, then you might as well write a “real” connector.Let’s rst look at the process of using the Incoming Web- Hook connector. Creating an incoming WebHook is really easy. Just click on the Connectors tab under your team as shown in Figure 1, and look for Incoming WebHook. Click on it, and con gure it, as shown in Figure 4.
When you click the “Create” button, you’re given a long and complex URL, as shown in Figure 5.
This URL is your key to pushing information out to the speci ed 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 con gured incoming WebHook, all you need to do is send an HTTP POST message to the URL you got in the Incoming WebHook screen shown.
When you hit Execute on the request composing screen shown in Figure 6, Fiddler informs you that you were suc- cessful by sending an HTTP 200 status code.
That was quite easy, wasn’t it? Now all you need is some sort of process that sends a POST request to this end- point whenever you want to inform the team of anything. Imagine a team of developers that gets a push noti ca- tion on a successful build? Or a marketing team that gets informed of a new product release? Or a sales staff that gets informed of marketing leads ready to close and that are tied to your CRM system? You now have the power of keeping people informed. And it wasn’t dif cult at all.
But there is one small problem. Trying to re-use the same connector in multiple teams and having to set it up man- ually everywhere could mean a lot of manual work.
Writing a Real Connector
The Incoming WebHook connector works great if you’re okay with setting up a connector manually in each team interested in the connector and then updating the ser- vice with the provided URLs. It doesn’t work so well if you wish to scale to multiple teams. You want to write a “real” connector, one that can scale with minimal atten- tion and effort. Perhaps you want to create something that you could even offer for sale in the marketplace. Or, at the very least, you want to create your Connect to Office365 button, which the user can click on and be guided through a simple set up process.
It turns out that it’s not very dif cult to do. 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 Office365 credentials and pro- vides 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 impor- tant ones are these:
• List the events supported by your connector. This is what the user will see. A single connec- tor can support multiple events. For instance, your source control connector may have a sepa- rate 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 no- ti cation but a successful build noti cation could be ignored.
• Landing page for your users. This is where us- ers will see the Connect to Office365 button. Of course, you can choose to have a different user experience, but the general idea here is that us- ers will have a choice about using your connector. Clicking on that link within the Office365 teams/ connectors tab takes the user to this landing page. On this page, the user is expected to con gure 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 min- utes,” etc.
• Redirect URL: Once the connector is set up, Office365 needs to communicate the endpoint to which you can push JSON cards. This endpoint URL is com- municated to the Redirect URL. Your connector is expected to save this URL in a secure place.
Copy and paste the HTML shown in Figure 8 onto the landing page URL within your application. For dev pur- poses, 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.
The Connect to Office365 Button
I’ve mentioned this button a few times. But what exactly does this button do? Clicking on this button asks the end user to authorize your connector to the Office365 group. It does so by redirecting the user to the Redirect URL of the connector registration page that you set up in the last section. And when it does so, it passes the following information:
Summary
There are so many ways to develop for Of ce 365! Luckily, for the last couple of years, Microsoft has been on the path of open standards and open source. WebHooks is a technology that gained acceptance outside of Of ce 365 before Of ce 365 offered it as an option. You can use this technique to both listen to Of ce 365 WebHooks and be noti ed by Of ce365. Or, you can provide Of ce 365 with noti cations at appropriate places via connectors.
In this article, I talked about pushing noti cations into an Of ce 365 team via connectors. In this set up, you wrote a WebHook. In my next article, I’ll demonstrate how Of ce 365 can push noti cations to you, where Of- ce 365 is the WebHook and you are the listener.
- state: An optional parameter that provides custom state information to the Redirect URL
- app_id: The identi er GUID for your application
- callback_url: The HTTPS Redirect URL for your con-nector 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. In addition to the Redirect URL, it can also get the state informa- tion, the group name to which you are connecting the connector, and any errors that may have occurred during the registration. For instance, if the user decides not to grant access to the connector, you’ll get an access denied error, and you can then show the user an appropriate message.
Sending JSON Cards
Assuming that you’ve registered the connector, created a website with the Connect to Of ce 365 button and a