WOPI discovery

WOPI discovery is the process by which a WOPI host identifies Office for the web capabilities and how to initialize Office for the web applications within a site. WOPI hosts use the discovery XML to determine how to interact with Office for the web. 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 for the web test and production environments.

WOPI discovery actions

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

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 for the web 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 are not supported within the Office 365 - Cloud Storage Partner Program. These operations are marked Not supported in the CSPP.

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 for the web.

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 for the web. 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

Not supported in the CSPP

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 for the web 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

Not supported in the CSPP

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

Not supported in the CSPP

An action that presents a broadcast of a document.

presentservice

Not supported in the CSPP

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

attend

Not supported in the CSPP

An action that attends a broadcast of a document.

attendservice

Not supported in the CSPP

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 for the web edit applications.

preloadview

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

syndicate

Not supported in the CSPP

legacywebservice

Not supported in the CSPP

rtc

Not supported in the CSPP

collab

Not supported in the CSPP

documentchat

Not supported in the CSPP

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 for the web Note

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

OneNote for the web integration is not included in the Office 365 - Cloud Storage Partner Program.

Requires

ExecuteCellStorageRequest, ExecuteCellStorageRelativeRequest

containers

OneNote for the web Note

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

OneNote for the web 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. To transform the urlsrc attribute into a proper action URL, the host must parse and replace Placeholder values with appropriate values or discard them completely.

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.

Transforming the urlsrc parameter

Some WOPI actions expose parameters that hosts can use to customize the behavior of the Office for the web application. For example, most actions support optional query string parameters that tell Office for the web 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 for the web action URIs are capitalized.

The list of all placeholder values used by Office for the web 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 for the web exposes in its discovery XML. Note that Office for the web 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 for the web should use for the purposes of data calculation. For a list of currently supported languages, see What languages does Office for the web 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 for the web session with a host session identifier. This can help Office for the web 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.

SESSION_CONTEXT

This placeholder can be replaced by any string value. If provided, this value 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 for the web URL length limit of 2048 bytes.

New in version 2018.12.15: Prior to this version, session context was supported but hosts were required to add it to the action URL manually using the sc query parameter. This placeholder enables hosts to handle session context in the same way as other URL parameters.

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 for the web application UI should use. Note that Office for the web 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 for the web 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 for the web will try to use the browser language setting (navigator.language). If no valid language can be determined Office for the web 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 for the web 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 for the web integration.

  • OfficeNativeClient: activates all tests necessary for Office for iOS integration.

WOPI_SOURCE

This placeholder must be replaced by a WopiSrc value.

Important

Unlike other placeholders, replacing this placeholder is required.

New in version 2018.12.15: Prior to this version, hosts were required to add the WopiSrc to the action URL for most (but not all) actions. This placeholder enables hosts to handle the WopiSrc in the same way as other URL parameters.

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 for the web 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 for the web is used.