Troubleshooting interactions with Office Online

When integrating with Office Online, it may be necessary to work with Microsoft engineers to diagnose problems. Following the steps below will help both you and Microsoft diagnose problems more quickly.

Before reporting issues

Before reporting any issues to Microsoft, ensure that you have done the following:

  1. Check that the WOPI Validation application tests are passing. Most common issues are easily diagnosed using the validator, and passing tests are a pre-requisite for any investigations into issues you’re encountering.

    Tip

    In cases where the validator tests are not consistent with the documentation, assume that the validator is correct. Also please file an issue so that we can address the gaps in the documentation.

  2. Check the Common implementation problems to see if you have made one of the more common mistakes in your WOPI implementation.

  3. Check the Known Issues to see if what you’re encountering is already known. When possible, workarounds will be provided in the issue notes.

Fiddler traces

The most useful tool when troubleshooting Office Online integration issues is Fiddler. When you run Fiddler while reproducing an issue, it will record all HTTP requests and responses. You can then save the Fiddler trace and share it with Microsoft engineers. Fiddler traces are an invaluable tool when troubleshooting problems because they provide a full record of the HTTP traffic between the browser and Office Online. As a rule of thumb, hosts should always provide a Fiddler trace when reporting Office Online integration issues to Microsoft.

Enabling HTTPS decryption in Fiddler

Because Office Online traffic is encrypted, Fiddler must be configured to decrypt the HTTPS traffic in order to be useful. In order to enable HTTPS encryption in Fiddler, do the following:

  1. From Fiddler, click Tools ‣ Fiddler Options... to open the options dialog.
  2. On the HTTPS tab, check the Capture HTTPS CONNECTs check box.
  3. Check the Decrypt HTTPS traffic check box. When you do this Fiddler will display a dialog asking if you wish to trust the Fiddler Root certificate. Click Yes. You may also see some security warnings from the operating system asking if you want to install the certificate. Click Yes to all of these prompts.
  4. In the drop-down, select ...from browsers only.
  5. Click OK in the options dialog.
  6. Close Fiddler and restart it.

Fiddler is now configured to decrypt HTTPS traffic.

An image showing the HTTPS decryption configuration UI in Fiddler.

Figure 9 Fiddler must be configured to decrypt HTTPS traffic in order to produce useful traces

Using Fiddler to trace a session

Using Fiddler to trace HTTP activity is straightforward:

  1. Open Fiddler.
  2. If needed, begin capturing traffic (File ‣ Capture Traffic). Note that Fiddler starts in capture mode when it is opened, so this step may not be necessary.
  3. Navigate to the host page URL while Fiddler is running, then reproduce the issue if needed.
  4. Once the issue is reproduced, save the Fiddler session as an archive (File ‣ Save ‣ All sessions...). The resulting file should have the file extension .saz.

Using Fiddler in Linux or OS X

Fiddler works very well in Windows, but can also be used in Linux and OS X using Mono. See http://fiddler.wikidot.com/mono for more information on installing and configuring it.

Alternatives to Fiddler: HTTP Archives (HAR)

If you cannot use Fiddler to get session traces, you can also use the Chrome browser developer tools to save HTTP Archive (HAR) files containing the HTTP requests made by the browser. To do this, do the following:

  1. Open the Chrome developer tools and select the Network tab.

  2. Check the Preserve log check box if you wish to retain the request log across multiple page navigations. This makes the network tracing behave more like Fiddler, and makes it less likely that you’ll lose your request log by accidentally refreshing the page or navigating away before you save the log. Office Online applications are single-page applications, so you don’t need to check this if you’re only planning to trace a single session.

    An image showing the :guilabel:`Network` tab in the Chrome developer tools.

    Figure 10 Network tab in the Chrome developer tools

  3. After you are done reproducing the issue, right-click in the network view and select the Save as HAR with Content option.

    An image showing the :guilabel:`Save as HAR with Content` option in the Chrome developer tools.

    Figure 11 Save as HAR with Content option in the Chrome developer tools

  4. Zip the resulting HAR file, since they can be quite large and generally compress well.

Tip

Other browsers’ developer tools have similar capabilities to Chrome to save session HTTP requests as an HTTP Archive.

Session IDs

Whenever an action URL is navigated to, Office Online creates a unique session ID. This session ID allows Microsoft engineers to quickly retrieve all server logs related to that session, including information about the WOPI calls that were made to the host. The session ID is passed back in the WOPI action URL HTTP response in the X-UserSessionId response header. It is also passed on every subsequent request made by the browser to Office Online in the X-UserSessionId request header, and it is included in all PostMessages sent from Office Online to the host page in the wdUserSession value.

The easiest way to retrieve the session ID is to use Fiddler, as described previously. However, you can also use the request tracking features in the Chrome and Internet Explorer developer tools to capture HTTP requests and determine the value of the X-UserSessionId response header.

An image showing the Chrome developer tools.

Figure 12 The Chrome developer tools can be used to retrieve a session ID.

An image showing the Internet Explorer developer tools.

Figure 13 As can the Internet Explorer developer tools.

Full Fiddler traces are always preferred, but in cases where they’re not available, session IDs can still be used by Microsoft engineers to retrieve Office Online server logs.

Getting session IDs after an error has occurred

In some cases, you may not be running Fiddler or browser developer tools when your session encounters an error. In these cases, the Office Online application will display an error either in a modal dialog or in a yellow bar at the top of the document below the ribbon.

Sometimes the error dialog will include the session ID in the dialog itself:

An image of an error dialog in Word Online that includes a session ID.

In such cases, you can copy the session ID from the error dialog.

Tip

Please do not simply send a screen shot of the error dialog. Copy the session ID as text and send the session ID itself to Microsoft engineers. If you send a screen shot, the Microsoft engineer will be forced to transcribe the session ID from the image, which is error-prone and tedious. Always provide the session ID as text.

In other cases, the session ID might not be available in the UI.

An image of an error in Word Online displayed in a yellow bar under the ribbon.

At this point, it is still often possible to get the session ID by using the following steps:

  1. Before closing the browser, refreshing the page, or clicking any buttons in the dialog or notification bar, start Fiddler or open the browser developer tools.
  2. Navigate away from the Office Online application or click a button in the dialog or notification bar.
  3. You should see a request to either WsaUpload.ashx or RemoteUls.ashx. The response to those requests should include the X-UserSessionId header with the session ID.

Correlation IDs

Every WOPI request Office Online makes to a host will have a unique ID, called the correlation ID. This ID will be included in the WOPI request using the X-WOPI-CorrelationId request header. Hosts should log this ID for each incoming WOPI request; doing so will allow hosts to easily correlate their own logs with Office Online’s server logs.

There are other WOPI request headers that may be useful for hosts to log. See the Standard WOPI request and response headers for more information.

Tip

In many cases, a single correlation ID is all that’s needed in order for a Microsoft engineer to retrieve complete server logs for an Office Online session for analysis. While hosts should provide Fiddler traces or session IDs whenever possible, a correlation ID will often suffice if necessary.