WOPI discovery

WOPI discovery is the process by which a WOPI host identifies Office Online capabilities and how to initialize Office Online applications within a site. WOPI hosts use the discovery XML to determine how to interact with Office Online. The WOPI host should cache the data in the discovery XML. Although this XML does not change often, we recommend that you issue a request for the XML periodically to ensure that you always have the most up-to-date version. 12-24 hours is a good cadence to refresh although in practice it is updated much less frequently.

Another more dynamic option is to re-run discovery when proof key validation fails, or when it succeeds using the old key. That implies that the keys have been rotated, so discovery should definitely be re-run to obtain the new public key.

Finally, another option is to run discovery whenever one of your machines restarts. All of these approaches, as well as combinations of them, have been used by hosts in the past; which approach makes the most sense depends on your infrastructure.

Important

Hosts should not rely on the Expires HTTP header on the WOPI discovery URL in order to know when to re-run WOPI discovery. While this may change in the future, currently the value in the Expires header is not appropriate for this purpose.

Tip

See WOPI discovery URLs for URLs you should use to retrieve discovery XML for the Office Online test and production environments.

WOPI discovery actions

The action element and its attributes in the discovery XML provides some important information about Office Online.

Element or attribute Description
action element

Represents:

  • Operations that you can perform on an Office document.
  • The file formats (in the form of file extensions) that are supported for the action.
requires attribute The WOPI REST endpoints that are required to use the actions.
urlsrc attribute The URI that you navigate to in order to invoke the action on a particular file.

The following example shows an action element in the Office Online discovery XML:

<action name="edit" ext="docx" requires="locks,update"
        urlsrc="https://word-edit.officeapps.live.com/we/wordeditorframe.aspx?
        <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>

This example defines an action called edit that is supported for docx files. The edit action requires the locks and update capabilities. To invoke the edit action on a file, you navigate to the URI included in the urlsrc attribute. Note that you must parse the urlsrc value and add some parameters. For a full description of this process, see Action URLs.

Note that some actions require specific permission from Microsoft to use in the Office Online cloud service; these actions are marked Special permission required for use in Office Online. If you wish to use these actions you must contact Microsoft to have them enabled for your WOPI host.

WOPI actions

Note

All WOPI actions require hosts implement CheckFileInfo and GetFile.

view

An action that renders a non-editable view of a document.

edit

An action that allows users to edit a document.

Requires:update, locks
editnew

An action that creates a new document using a blank file template appropriate to the file type, then opens that file for editing in Office Online.

Requires:update, locks
convert

An action that converts a document in a binary format, such as doc, into a modern format, like docx, so that it can be edited in Office Online. See Editing binary document formats for more information about this action.

Requires:update, locks
getinfo

An action that returns a set of URLs that can be used to execute automated test cases. This action is only used by the WOPI Validation application and is meant to be used in an automated fashion.

interactivepreview

Special permission required for use in Office Online

An action that provides an interactive preview of the file type.

mobileView

An action that renders a non-editable view of a document that is optimized for viewing on mobile devices such as smartphones.

Tip

Office Online automatically redirects view to mobileView when needed, so typically hosts do not need to use this action directly.

embedview

An action that renders a non-editable view of a document that is optimized for embedding in a web page.

imagepreview

Special permission required for use in Office Online

An action that provides a static image preview of the file type.

formsubmit

An action that supports accepting changes to the file type via a form-style interface. For example, a user might be able to use this action to change the content of a workbook even if they did not have permission to use the edit action.

formedit

An action that supports editing the file type in a mode better suited to working with files that have been used to collect form data via the formsubmit action.

rest

An action that supports interacting with the file type via additional URL parameters that are specific to the file type in question.

present

Special permission required for use in Office Online

An action that presents a broadcast of a document.

presentservice

Special permission required for use in Office Online

This action provides the location of a broadcast endpoint for broadcast presenters. Interaction with the endpoint is described in [MS-OBPRS].

attend

Special permission required for use in Office Online

An action that attends a broadcast of a document.

attendservice

Special permission required for use in Office Online

This action provides the location of a broadcast endpoint for broadcast attendees. Interaction with the endpoint is described in [MS-OBPAS].

preloadedit

An action used to preload static content for Office Online edit applications.

preloadview

An action used to preload static content for Office Online view applications.

syndicate

Special permission required for use in Office Online

legacywebservice

Special permission required for use in Office Online

rtc

Special permission required for use in Office Online

collab

Special permission required for use in Office Online

documentchat

Special permission required for use in Office Online

Action requirements

The WOPI protocol exposes a number of different REST endpoints and operations that you can perform via those endpoints. You don’t have to implement all of these for all actions. Actions define their requirements as part of the discovery XML. The requirements themselves are groups of WOPI operations that must be supported in order for the action to work.

update
Requires:PutFile, PutRelativeFile
locks
Requires:Lock, RefreshLock, Unlock, UnlockAndRelock
cobalt

OneNote Online Note

This requirement is only used in OneNote Online. Word, Excel, and PowerPoint Online do not require that any of the WOPI operations encompassed by this action requirement be implemented.

OneNote Online integration is not included in the Office 365 Cloud Storage Partner Program.

Requires:ExecuteCellStorageRequest, ExecuteCellStorageRelativeRequest
containers

OneNote Online Note

This requirement is only used in OneNote Online. Word, Excel, and PowerPoint Online do not require that any of the WOPI operations encompassed by this action requirement be implemented.

OneNote Online integration is not included in the Office 365 Cloud Storage Partner Program.

Requires:CheckFolderInfo, DeleteFile, EnumerateChildren (folders)

Action URLs

The URI values provided in the urlsrc attribute in the discovery XML are not in a valid format. Simply navigating to them will result in errors. A WOPI host must transform the URIs provided in order to make them valid action URLs that can be used to invoke actions on a file. There are two key components to transforming the urlsrc attribute:

  1. Parsing and replacing Placeholder values with appropriate values, or discarding them completely
  2. Appending a WOPISrc value to the URI as a query string parameter

After the URL is transformed, it is a valid URL. When the URL is opened, the action will be invoked against the file indicated by the WOPISrc parameter.

Transforming the urlsrc parameter

Some WOPI actions expose parameters that hosts can use to customize the behavior of the Office Online application. For example, most actions support optional query string parameters that tell Office Online what language to render the application UI in.

These parameters are exposed in the urlsrc attribute in the discovery XML. Each of these optional parameters are contained within angle brackets (< and >), and conform to the pattern <name=PLACEHOLDER_VALUE[&]>, where name is the name of the query string parameter and PLACEHOLDER_VALUE is a value that can be replaced by the host. By convention all placeholder values in Office Online action URIs are capitalized.

The list of all placeholder values used by Office Online and what values are valid replacements for each placeholder are listed in the Placeholder values section.

The placeholders are replaced as follows:

  • If the PLACEHOLDER_VALUE is unknown to the host, the entire parameter, including the angle brackets, is removed.
  • Similarly, if the PLACEHOLDER_VALUE is known but the host wishes to ignore it or use the default value for that parameter, the entire parameter, including the angle brackets, should be removed.
  • If the PLACEHOLDER_VALUE is known, the angle brackets are removed, the name value is left intact, and the PLACEHOLDER_VALUE string is replaced with an appropriate value. If present, the optional & must be preserved.

The following section contains a list of all current placeholder values that Office Online exposes in its discovery XML. Note that Office Online may add new placeholders and actions at any time; hosts must ignore - and thus remove from the URL per the instructions above - any placeholder values they don’t explicitly understand.

Placeholder values

BUSINESS_USER
This value can be set to 1 to indicate that the current user is a business user. This placeholder value must be used by hosts that support the business user flow. See Supporting document editing for business users for more information.
DC_LLCC

This value represents the language that Office Online should use for the purposes of data calculation. For a list of currently supported languages, see What languages does Office Online support?

In addition to the values provided in the Locale ID column, any language can be supplied provided it is in the format described in RFC 1766. Typically this value should be the same as the value provided for UI_LLCC, and will default to that value if not provided.

DISABLE_ASYNC

Note

This value is used in the attend action only.

This value can be set to true to prevent a broadcast attendee from navigating a file independently.

DISABLE_BROADCAST

Note

This value is used in broadcast related actions only.

This value can be set to true to load a view of a document that does not start or join a broadcast session. This view looks and behaves like a regular broadcast frame.

DISABLE_CHAT
This value can be set to 1 to disable in-document chat functionality.
EMBEDDED

Note

This value is used in broadcast related actions only.

This value can be set to true to indicate that the output of the action will be embedded in a web page.

FULLSCREEN

Note

This value is used in broadcast related actions only.

This value can be set to true to load the file type in full-screen mode.

HOST_SESSION_ID
This value can be passed by hosts to associate an Office Online session with a host session identifier. This can help Office Online engineers more quickly find logs for troubleshooting purposes based on a host-specific session identifier.
PERFSTATS

Attention

Sorry, this documentation hasn’t been written yet. You can track the status of issue #52 through our public GitHub issue tracker.

RECORDING

Note

This value is used in broadcast related actions only.

This value can be set to true to load the file type with a minimal user interface.

THEME_ID

Note

This value is used in broadcast related actions only.

This value can be set to either 1 or 2 to designate the a specific user interface appearance. 1 denotes a light-colored theme and 2 denotes a darker colored theme.

UI_LLCC

This value represents the language the Office Online application UI should use. Note that Office Online does not support all languages, and may use a substitute language if the language requested is not supported. For a list of currently supported languages, see What languages does Office Online support?

In addition to the values provided in the Locale ID column, any language can be supplied provided it is in the format described in RFC 1766. If no value is provided for this placeholder, Office Online will try to use the browser language setting (navigator.language). If no valid language can be determined Office Online will default to en-US (US English).

VALIDATOR_TEST_CATEGORY

Note

This value is used to run the WOPI Validation application in different modes.

This value can be set to All, OfficeOnline or OfficeNativeClient to activate tests specific to Office Online and Office for iOS. If omitted, the default value is All.

  • All: activates all WOPI Validation application tests.
  • OfficeOnline: activates all tests necessary for Office Online integration.
  • OfficeNativeClient: activates all tests necessary for Office for iOS integration.

Appending a WOPISrc value

After parsing and replacing any placeholder values in the urlsrc parameter, hosts must add a WOPISrc query string parameter to the URL. Once this is done, the URL is a valid action URL and, when loaded by a browser, will instantiate an Office Online application.

The WOPISrc parameter tells Office Online the URL of the host’s WOPI Files endpoint. In other words, it is a URL of the form http://server/<...>/wopi/files/(file_id), where file_id is the file id of the file. The WOPISrc parameter value must be encoded to a URL-safe string, then the parameter is appended to the action URL.

See also

See WOPISrc for more information about the WOPISrc value.

Session context parameter

In addition to the Placeholder values listed above, hosts can optionally append an sc query string parameter to the action URLs. This parameter is called the session context and, if provided, will be passed back to the host in subsequent CheckFileInfo and CheckFolderInfo calls in the X-WOPI-SessionContext request header. There is no defined limit for the length of this string; however, since it is passed on the query string, it is subject to the overall Office Online URL length limit of 2047 bytes.

Additional notes

Depending on the specific scenario where action URLs are invoked, there are additional relevant components to action URLs. Since action URLs are typically invoked from the host page, these are covered in the Building a host page section.

Favicon URLs

The discovery XML includes a URL to an appropriate favicon for all Office Online applications in the favIconUrl attribute of the app element. For example:

<app name="Excel"
     favIconUrl="https://excel.officeapps.live.com/x/_layouts/resources/FavIcon_Excel.ico"
     checkLicense="true">
    ...
</app>

Hosts should use this URL as the favicon for their host page, so that the appropriate application icon is shown when Office Online is used.