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.

• 3. Proof Key For Excel

When you construct a URL for proof key verification, you MUST use the exact URL that Microsoft used to call your WOPI service. The Excel client application encodes its parameters in service calls differently from Word and PowerPoint. Don’t assume a specific encoding mechanism – use the URL as Microsoft created it. It is common for implementors to recreate the URL from scratch when performing proof key verification. This often leads to the wrong encoding mechanism being used which leads to proof key failure. If proof key is failing only in Excel, it is likely that this is the cause.

• 4. Malformed WOPISrc

Your WOPISrc URL should be simple and as described. Microsoft use the URL to identify an individual file. This is somewhat surprising as you provide as file id in the URL. However, MS use the whole URL to identify the file, not just the id. So for co-authoring to work, the entire URL must be identical for two users. A common error that we see is implementors adding extra parameters on to the WOPISrc which make the URL different for different users for the same file. Keep it simple!

• 5. Not Following The Host Page Instructions

This related to the “Malformed WOPISrc” error above. We commonly see implementors trying to use a different mechanism to trigger the WOPI client. The only reliable way to do this is to exactly follow the instructions on creating a host page in the CSPP WOPI documentation: https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/online/hostpage

We sometimes see implementors trying to trigger the page using a GET instead of a form post. This results in the implementor adding the access_token to the WOPISrc, which breaks the co-authoring as the URL for the same file then differs between different users. It’s also worth knowing that MS will ignore an access_token submitted in this manner.

• 6. Broken FavIcons

The Discovery endpoint (https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/online/build-test-ship/environments) sometimes incorrectly returns the “http” scheme instead of “https”. I would recommend automatically tweaking the scheme to be “http” when this happens.

• 7. The Infamous “PutUnlockedFile” Validator Test

It is very common for the “PutUnlockedFile” test to fail for new WOPI implementors. This is almost always because the implementor is checking the wrong file size! For this test, one must check the file size of the existing file for a zero length, not the size of the inbound file. This is stated in the documentation (https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/putfile), but it’s really easy to misread! Essentially it is permitted to overwrite an existing zero length file without a Lock in a PutFile request.

• 8. Page Numbers No Displaying Correctly In Word

Page numbers in Word do not always display correctly. For example, you may see this: Page 4 or < # >. This is bug in Word. You cannot fix it – we are waiting for Microsoft to fix it.

• 9. Incorrectly Encoded SHA256 In CheckFileInfo

In CheckFileInfo, you should include a SHA256 digest of your file to help Microsoft determine if it has changed. A lot of programming languages hex encode SHA256 by default, but CSPP WOPI requires base64 encoding. As a hint, your SHA256 should be exactly 44 characters long. If it isn’t you have probably incorrectly encoded it.

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.