Adding Office 365 Connectors from a Mobile App

Office 365 Connectors are a powerful way to aggregate group information and content into one place (regardless of the source). Third parties can use connectors to send useful information and content into Office 365 Groups where users can have conversations, collaborate, and take action on that third party data. Developers can leverage the Connectors Developer Dashboard to register custom Connectors and even generate the HTML markup for integrating the Connector with their websites. However, there is little guidance on adding the same functionality to a mobile application. In this post, I will detail the steps to integrate a third-party Office 365 Connector with a custom mobile application.

[embed]https://www.youtube.com/watch?v=m8zLuQDDiBQ[/embed]

Adding Connectors from Mobile Apps

The two documented ways for adding a Office 365 Connector to a group are through the Connector Catalog in Office 365 or via "Connect to Office 365" button on a third party website. All published Connectors are displayed in the Connector Catalog, but third parties can choose to update their website(s) to support the "Connect to" flow. I call this a "flow" because it involves navigating the user to Office 365 to select a group and consent the Connector before returning to the third party website with connection details. I found this very similar to a OAuth2 code authorization flow. So much so, I thought I could use OAuth2 mobile patterns to add Connectors from a mobile application.

The "Connect to" flow for Connectors involves a redirect to the Connector consent screen (where the user also selects a group). This redirect includes a callback_url that Office 365 will use to send back connection details (the group name and webhook URL). This can be accomplished in a native mobile application by leveraging a browser control or in-app browser plug-in and an event listener for when the callback_url is called. Every mobile platform supports some form of a browser control with events for address changes in that control. Below is a code block in TypeScript that uses the Cordova InApp Browser Plugin to "listen" for the callback and then grab the group and webhook details off that response.

Use of In-App Browser to perform Connector consent flow (TypeScript/Cordova):

   connectToO365() {
    let ctrl = this;
    let ref = cordova.InAppBrowser.open("https://outlook.office.com/connectors/Connect?state=myAppsState&app_id=4b543361-dbc2-4726-a351-c4b43711d6c5&callback_url=https://localhost:44300/callback", "_blank", "location=no,clearcache=yes,toolbar=yes");
    ref.addEventListener("loadstart", function(evt) {
      ctrl.zone.run(() => {
        //listen for the callback URI
        if (evt.url.indexOf('https://localhost:44300/callback') == 0) {
          //decode the uri into the response parameters
          let parts = evt.url.split('&');
          ctrl.sub.webhook = decodeURIComponent(parts[1].split('=')[1]);
          ctrl.sub.group = decodeURIComponent(parts[2].split('=')[1]);
          ref.close();
        }
      });
    });
  }

Final Thoughts

I believe that Office 365 Groups are incredibly powerful and the future of Microsoft collaboration. In fact, most of the mobile applications I have been building are group-centric (checkout Good with Faces), so incorporating Connectors just adds an additional layer of integration value. You can download the full Angular2/Ionic2/TypeScript sample used in this post at the repo below:

https://github.com/richdizz/Adding-O365-Connector-From-Mobile-App