A New Hampshire based startup was working on adding a change log to their platform. The one issue they were trying to tackle was how to communicate the changes to team members. After some initial discovery the Office 365 Connector for Groups was selected to manage this task.

Core Team

  • Steve Brunton — Brick River, Lead Developer
  • Paul Schneider — Brick River, Founder/CEO
  • Joshua Drew — Microsoft, Sr Technical Evangelist

Customer Profile

Brick River is a Content, Communication and Customer Management Platform that simplifies managing one or many web properties. From creating and publishing content to keeping contacts up to date, their platform allows the flexibility to use it our way. Event creation as well as payment and other forms can easily expand your presence on the web. Brick River is part of the Microsoft BizSpark program.

Problem Statement

One of the issue facing Brick River and its customers was to keep track of changes that occur within their platform. More specifically surrounding creation of events. Multiple authors can create events within the system but there was not an obvious way to view the changes to these events by multiple people. A notification as well as ability to edit or view the change was functionality that was needed.

Solution, Steps and Delivery

I sat down with Steve and Paul to discuss how we can help solve this problem, more specifically with the Office 365 Connector for Groups. We looked at some of the features in the Connector, such as the ability to push these messages into an Outlook Group as well as the ease of implementation, it was decided upon to use the Connector for the Brick River event change log.

The first step of the project was to start configuring the Connector for use, we did this on Outlook Dev Center. Visit the Connector Developer Portal and login with your Office 365 credentials. If you do not have an Office 365 subscription you can get a one year FREE Office 365 Subscription under the Office 365 Developer Program. Alternately, if you have an existing MSDN subscription, you can activate your free Office 365 benefit.

Click on New Connector and Fill out the basic information such as name, logo, description & redirect URL. When developing the connector you can provide your localhost redirect URL.

To enable your connector with actionable message, you can provide one or more target URLs. This is one or more domains corresponding to URLs that will process the actions. Your target URL can correspond to the top level domain or the subdomain of the TLD. They need to be https enabled URLs. Example: https://api.myservice.com.

Choose whether your Connector needs to work with Office 365 Groups, Inbox or both. Make sure your users will benefit from those Connectors in those communication spaces.

Once you save the connector information, the html code snippet for the Connect to Office 365 button is generated. The name, logo, description, company website & events you shared are displayed to a user when he tries to add a new configuration or view an existing one.

Now that we had the connector configured we had to look at the user flow as well as where the integration points would be within Brick River platform. The goal was to provide a seamless experience from Brick River into the Connector as well as provide configuration and functionality back to the user. The way we accomplished this was to provide an “integrations” page within the Brick River user profile section. The Connector would be displayed there with an action button for the user to login to their Office 365 account to authenticate to the connector. Once connected, the Connector flow would present a landing page to allow the user to select the Outlook Group where they would want these change messages to appear.

Once authorized, the Connector flow would drop the user back into the Brick River Integration configuration page. This page controls what type of “changes” would be monitored and sent over to the Connector. We also provided the user the ability to remove the connection if it was no longer needed.

This page provides full control to the user and allows for robust information to be tracked from various sources going forward.

When changes are now made to events we process the call to the webhook, along with the Connector Card information, to perform the Connector action to process the message to the Outlook Group.

Lessons

There were a many of lessons we learned along the way.

  • Unique URL vs Shared URL
  • The Brick River platform uses domain masking for the public facing website. However, for the administrative control it is all user based. We had to come up with a way to allow the Connector to return a unique URL based on the user that is making the connection. This was done using the “state” property of the webhook. The callback URL would be static, however the “state” would be pertinent to the customer by encrypting the time and hostname of the customer for lookup later.
  • Integration Controls
  • Since we were allowing the user to store specific changes that would use the Connector, we had to create a process to track and store that information. This information is stored in a “config” table that is tied back to the user. This way we now have full control of each of the items they user wants to be tracked and we also store the actual webhook for each of these items. We call this the TriggerConfig.
  • Deep Linking
  • We wanted to provide more than showing the changes within the Connector Card. We wanted to provide actions for the user to get back into the Brick River platform to review the record. We did this by using the customer hostname as a value in the Connector Card action link as well as the record id as a parameter.

Example

Additional Resources