How we integrated Formistica with Office 365 using Graph API
In this post I want to describe how we integrated our digital forms platform, Formistica, with the Microsoft Graph API. The Graph API provides a consolidated API platform for integrating apps with Microsoft’s Office 365 cloud-based apps such as OneDrive, Excel, Outlook, OneNote, SharePoint and others.
We developed this capability so that Formistica could integrate with Office 365 and other widely used Microsoft cloud apps. In the past, each app had its own API so integration was time consuming and costly to develop and support. Now a single API (web service endpoint) has simplified integration considerably. As a result, we managed to build Graph API integration into Formistica quickly and easily.
When a Formistica administrator creates a form, one or more “form actions” can be also defined. Form actions are performed every time a form is submitted. Form actions are typically used to achieve some kind of integration such as exporting or merging submitted form data into formats such as PDF, CSV, Excel, Word, JSON, XML and so on. Form actions can also send customised email notifications or even post tweets.
Here’s a typical use scenario for a form action that needs OneDrive integration: every time a user submits a form, merge the submitted form data with an existing Microsoft Excel spreadsheet template, then upload the spreadsheet to a specific folder on OneDrive. How did we allow Formistica to support that kind of integration reliably?
Step 1. User experience (always comes first!)
We wanted a user experience that would allow a Formistica administrator to easily configure this kind of integration with a form action. Administrators are not developers and would be unlikely to have a working knowledge of APIs. We arrived at a user experience we’re happy with after lots of whiteboarding and by distilling ideas into a simple set of steps with a clear, elegant user interface. Prototyped and refined of course. Formistica uses the latest Bootstrap user interface framework which instantly gives us a responsive UI.
Step 2. Authentication
Our integration development required us to build Microsoft Graph API authentication into the Formistica’s API connections framework but with a simple user interface. In Formistica we allow a client organisation to configure one or more named connections to external integration targets such as Drobox, FTP, Google Drive, TomTom WEBFLEET, Zoho and now Microsoft Graph. This is configured in a “connection settings” area in the Formistica administators web app. Once a connection has been created, configured and tested it can be used and by Formistica administrators when they define form actions for any form.
Step 3. OneDrive Uploads.
Next, we developed capability for a Formistica form action to upload a file to OneDrive. Uploading a file seemed a simple enough requirement. However, this actually required substantial development to deliver the flexibility and reliability we needed.
For example, a form action that needs to upload a file to a new folder within an existing folder on OneDrive. To achieve this our code needed to handle some additional complexity. Find the folder in the OneDrive folder tree (with potentially thousands of folders), check if the new folder already existed and then upload the file.
We also had to develop upload code that would reliably deal with large files by uploading in “chunks”. The upload code also checks each file “chunk” has successfully uploaded. Eventually we got there and with plenty of testing this approach proved to be a reliable way uploading files of all sizes.
The Formistica development roadmap includes a requirement for form actions that will add submitted form data into an existing spreadsheet stored on OneDrive. I’ll add a post of our experience developing that next time.