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.
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.
Common WOPI API Issues
- .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.
- 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_ttl has expired
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.