Troubleshooting WOPI API with The Cloud Storage Partner Program

This article examines common problems with implementing a WOPI API and host, looking at the best development practice to minimise your problems. We take you step-by-step through the troubleshooting process, with a closer look at wopitest and how the Cloud Storage Partner Program (CSPP) could help you.

Remember, implementing WOPI for the first time is quite daunting, so if you need assistance, please get in touch with us to find out how our experts can help.

Logging

Most of the time, these types of problems are caused by errors in your API implementation, with errors rarely on the Microsoft side.

The main difficulty with WOPI troubleshooting is that the WOPI client does not give useful error messages, so you should build extensive logging into your WOPI API implementation. This will help you track down problems much more easily.

The errors you will see in the WOPI client are usually an error message, like, “Sorry, there was a problem and we can’t open this document. If this happens again, try opening the document in Microsoft Word.” You might also see some bizarre JavaScript errors in the developer console!

Using NGrok For Debugging

In the past, most developers have relied on the “Logging” approach outlined above for debugging their WOPI implementation. This is a slow approach as it requires code changes to be made and the WOPI service to be redeployed and then re-tested. Depending on how quick and well-automated deployment is, this approach can be slow.

We recommend using NGrok (and similar products like Cloudflare) for improving the debugging experience. The core challenge is that most developers use the “localhost” domain name for running their WOPI implementation locally. MS will not (for obvious reasons) send WOPI API calls to localhost, which means that you can’t debug your WOPI implementation in real time.

NGrok solves this problem by allowing you to use a fully qualified domain name (FQDN) with an Internet-valid IP address for your WOPI implementation which can be redirected to your local development machine. This approach circumvents any firewall-related issues too.

(Note that you will need at least an NGrok Pro account [$20 / month at the time of writing] for this to work, as this requires NGrok to accept your custom domain.)

The first step is to set up your custom FQDN (which must be allow-listed with CSPP) up on NGrok.  NGrok will manage the SSL certificate for you! Once it is all working and your DNS has updated, you can download the NGrok client.

Then, once you have it installed, run a command like this:

– ngrok http –scheme=https –region=eu–hostname=wopi.mydomain.com 8080

This command line tells NGrok to intercept all “https” traffic going to wopi.mydomain.com and redirect it to port 8080 running on the local machine. With this in place, you can run the WOPI validator tests or a WOPI editor and debug the traffic on your local machine.

Common WOPI API Issues

1. .wopitest Validation

The first step is to get the .wopitest validation working. If you don’t have these tests working, then your WOPI API implementation is unlikely to work. However, having these validation tests working does not mean that your WOPI API implementation will work, as the tests are not exhaustive.

For example, the SHA256 test only checks that you are supplying some text in the SHA256 property of CheckFileInfo. It does not check that the SHA256 is valid! So if you have your SHA256 calculation wrong, the validation test will pass, but the WOPI editor will fail to load with a strange JavaScript error.

2. Known Issues

Check ‘Known Issues’, which can be found on the Microsoft Documentation page. This page looks at some of the issues that users have run into and offers fixes where possible.

Detailed WOPI API Debugging

Before reporting a problem to Microsoft, you should check the log of your own WOPI implementation for errors and warnings first. Look for Exceptions, 500s and other unexpected responses. Most of the problems we see reported to CSPP are because of a failure at the host side, not the Microsoft side.

Typical problems are:

• The domain for your WOPI API is not on the test allow list
• You are not providing:
  • OwnerId in CheckFileInfo
  • Size in CheckFileInfo
  • A valid SHA256 in CheckFileInfo
  • A Version in CheckFileInfo
  • A valid LastModifiedTime in CheckFileInfo
  • The required properties in CheckFileInfo
• You are providing additional unexpected properties in CheckFileInfo
• You are not handling Locks correctly
• Incorrect proof key validation implementation
• access_token_ttl has expired
• access_token_ttl is invalid (e.g. 1678387986000 is a valid number of milliseconds since January 1, 1970 UTC)

In our experience, most of our clients’ problems are with their initial response to CheckFileInfo, so make sure that you go through that very carefully.

At this point, it’s a slow process of checking each individual property for all of your WOPI API calls to make sure that they conform exactly to the documentation. Microsoft has a document on the CheckFileInfo operation, and this might be a good place to start. Although it’s a slow process doing this, requesting support from CSPP can be slower as they are very often busy.

Top tip: check in your log for the last operation that Microsoft called in your WOPI API, as it can be a good guide to sorting out problems. Sometimes the last response you sent to Microsoft was the incorrect one! For example, if that last operation called was “Lock” and no further calls were made, there’s a good chance that there was a problem with your Lock response.

Help from the Cloud Storage Partner Program

For help from Microsoft, you should provide Microsoft with a Fiddler trace and a session ID. Be aware that it may take two weeks or more to get a reply, and the reply is generally something like “You did not supply OwnerId in CheckFileInfo.” It’s much quicker to find the issue and debug it yourself if possible.

For more information on WOPI integration, including using WOPI to embed Microsoft Word, please take a look at our blog posts covering these topics in detail. Please contact McKenna Consultants to find out how we can help you with your WOPI Integration.