Skip to main content

Key concepts

Learn the following concepts that are vital to understand the requirements for integrating with WOPI clients. More information can be found here.

File ID​

A file ID is a string that represents a file or folder being operated on using WOPI operations. A host must issue a unique ID for any file used by a WOPI client. The client will include the file ID when making requests to the WOPI host. So, a host must be able to use the file ID to locate a particular file.

A file ID must:

  • represent a single file;
  • be a URL-safe string, because IDs are passed in URLs, principally via the WOPISrc parameter;
  • remain the same when the file is edited;
  • remain the same when the file is moved or renamed;
  • remain the same when any ancestor container, including the parent container, is renamed;
  • in the case of shared files, the ID for a given file must be the same for every user that accesses the file.

Access token​

An access token is a string used by the host to determine the identity and permissions of the issuer of a WOPI request.

The WOPI host that stores the file has the information about user permissions. For this reason, the WOPI host must provide an access token that the client then passes back to it on subsequent WOPI requests. When the WOPI host receives the token, it either validates it, or responds with an appropriate HTTP status code if the token is invalid or unauthorized.

In the online office, an access token is generated by the host and passed to the client using the access_token parameter before the first WOPI request.

WOPI access tokens must adhere to the guidelines described here.

The access_token_ttl property​

The access_token_ttl property tells a WOPI client when an access token expires, represented as the number of milliseconds since January 1, 1970 UTC (the date epoch in JavaScript). Despite its misleading name, it doesn't represent a time duration for which the access token is valid. The access_token_ttl is never used by itself; it's always attached to a specific access token.

We recommend using an access_token_ttl value that makes the access token valid for 10 hours. Hosts can also set the access_token_ttl value to 0. This effectively tells the client that the token expiry is either infinite or unknown. In this case, clients might disable any UI prompting users to refresh their sessions. This can lead to unexpected data loss due to access token expiry. So, we strongly recommend specifying a value for access_token_ttl.

Lock​

A lock is a conceptual construct that's associated with a file. Locks serve two purposes in WOPI:

  • A lock prevents anyone that doesn't have a valid lock ID from making changes to a file. A WOPI client locks files prior to editing them to prevent other entities from changing the file while the client is also editing them.
  • A lock is also used to store a small bit of temporary data associated with a file. This metadata is called the lock ID and is a string with a maximum length of 1024 ASCII characters.

Therefore, WOPI locks must:

  • be associated with a single file;
  • contain a lock ID of maximum length 1024 ASCII characters;
  • prevent all changes to that file unless a proper lock ID is provided;
  • expire after 30 minutes unless refreshed (RefreshLock);
  • not be associated with a particular user.

All WOPI operations that modify files, such as PutFile, include a lock ID as a parameter in their request. Usually the expected lock ID is passed in the X-WOPI-Lock request header.

WOPI requires that hosts compare the lock ID passed in a WOPI request with the lock ID currently on a file and respond appropriately when the lock IDs don't match. In particular, WOPI clients expect that when a lock ID does not match the current lock, the host sends back the current lock ID in the X-WOPI-Lock response header. This behavior is critical, because WOPI clients use the current lock ID in order to determine what further WOPI calls to make to the host.

WOPISrc​

The WOPISrc (WOPI Source) is the URL that runs WOPI operations on a file. It's a combination of the Files endpoint URL for the host, along with a particular file ID. The WOPISrc doesn't include an access token.

Starting from version 8.0, the WOPISrc query parameter is added to the requests from the browser to the server. This allows you to create several independent instances of ONLYOFFICE. Load balancing requests with WOPISrc ensure that collaborative editing works correctly: all users editing the same document are served by the same server.

For WOPI, the parameter sent by the integrator is used. For Docs API, the shardkey parameter is used.