Microsoft Office Add-Ins and WOPI Update

Since late last year, the Microsoft Cloud Storage Partner Program (CSPP) has officially supported Microsoft Office add-ins for WOPI. The process for getting an add-in working in WOPI is not as simple as getting an add-in working in standard MS Office, so this blog post will take you through the process.

How to Use Add-Ins with WOPI

  1. Get Your Add-in Into AppSource

Microsoft only supports add-ins distributed via AppSource – other methods will not work reliably in the WOPI editor. These include:

  • Sideloading
  • Centralised deployment
  • Sharepoint catalogue

This means that your add-in must comply with Microsoft’s guidelines for MS Office add-ins, and you need to submit your add-in for their approval.

We can help you out with add-in development and submission to Microsoft (including Enterprise submissions, which are not subject to all of Microsoft’s guidelines). Please get in touch with our team if you would like to discuss your project.

  1. Implement The App_IsFrameTrusted Post Message

Before Microsoft will enable add-ins for your WOPI configuration, you will need to follow the instructions on implementing the App_IsFrameTrusted Post message and return the appropriate “Host_IsFrameTrusted” Post message. This is a fairly trivial programming task that you should be able to accomplish quickly. You can find the official documentation on using PostMessage with Office Online on the Microsoft website. You will also need to include a query string: &sftc=1 to the Action Url of the POST request sent to the M365 server url, to indicate to the Office app that the Hosts support frame trust post Message. (sftc is short for supportsFrameTrustedPostMessage).

  1. Tell Microsoft That You Want To Enable Add-Ins

Next you need to tell Microsoft that you want to enable add-ins for your WOPI configuration. For this, use the new CSPP support process to raise a support ticket with Microsoft. Include a link to your add-in in AppSource and mention that you have already implemented App_IsFrameTrusted. This is the next question they’ll ask, so answering it saves you time and Microsoft will not enable add-ins for you until you’ve done this.

It takes about four weeks for them to globally roll out any configuration changes they make for your WOPI implementation, including enabling add-ins. In the UK, we found that the add-in feature was enabled after about two and a half weeks.

  1. Tweak Your Host Page

This is also a really easy step that you can do while you wait to hear back from Microsoft. On the host page where you submit your access_token and access_token_ttl, you need to add one more HTML input field. This field is a JSON array of the add-in identifiers that you wish to load into the WOPI editor.

To get the identifier for your add-in (it’s not the one in your manifest file), you need to go to the AppSource website and find your add-in. The identifier you need is found in the URL.

For example, if your add-in was the Emoji Keyboard, you would navigate to the Emoji Keyboard page in AppSource and find the identifier in the URL– in this case, the identifier is ‘WA104380121’.

Use this identifier in a new input parameter alongside your access_token and access_token_ttl like this:

<input name=”host_install_addins” value='[{“addinId”: “WA104380121”, “type”: “TaskPaneApp”}]’ type=”hidden” />

You may include more than one add-in if you want to.

Note that this is an array of JSON objects. There are incorrect examples online of the syntax for this which show {{ instead of [{.

  1. The User Experience

Once add-ins are enabled for your WOPI configuration, the first time a user opens the Edit document action, they will be prompted to accept that they consent to the use of this add-in. Microsoft refer to this as the Consent Experience.

After the user consents, the Consent window will close. Your add-in will not open automatically, but your add-in button will appear in the toolbar.

Testing WOPI Add-ins

At the start of January 2022, CSPP sent out a newsletter that stated that they were starting to remove the ‘add-ins’ button from the WOPI toolbar. This was probably a good decision, as add-ins loaded using this button (e.g. sideloaded, centralized deployment etc) do not work reliably!

What this means is that the only way you will be able to test your add-in with WOPI is by having your add-in live in AppSource. Testing your add-in is important, as a few bugs in officejs behaviour have been noted by teams implementing add-ins in WOPI which do not exist for Microsoft 365.

Please contact McKenna Consultants to find out how we can help you with your WOPI integration. For more information on WOPI and add-ins, including using WOPI to embed Microsoft Word, please see our previous blog posts.

Nick McKenna
Since 2004, Nick McKenna, BSc, MBCS Biography has been the CEO of McKenna Consultants. McKenna Consultants is a bespoke software development based in North Yorkshire, specialising in Cloud development, mobile App development, progressive web App development, systems integration and the Internet of Things development. Nick also holds a First Class Degree in Computer Science (BSc) and wrote his first computer program at the age of nine, on a BBC Micro Model B computer. For the last 21 years, Nick has been a professional computer programmer and software architecture. Nick’s technical expertise includes; Net Core, C#, Microsoft Azure, Asp.Net, RESTful web services, eProcurement, Swift, iOS mobile development, Java, Android mobile development, C++, Internet Of Things and more. In addition, Nick is experienced in Agile coaching, training and consultancy, applying modern Agile management techniques to marketing and running McKenna Consultants, as well as the development of software for clients. Nick is a Certified Enterprise Coach (Scrum Alliance), SAFe Program Consultant (SAI), Certified LeSS Practitioner (LeSS) and Certified Scrum@Scale Practitioner. Outside the office, Nick is a professional scuba diver and he holds the rank of Black Belt 5th Dan in Karate.