Implementing WOPI Protocol For Office Integration

WOPI (Web Application Open Platform Interface) is a RESTful API protocol first released by Microsoft. It is now widely used to integrate online office suites with various cloud applications.

In this article, we will explain how to enable WOPI for ONLYOFFICE editors and how this kind of integration works.

Enabling WOPI for ONLYOFFICE Docs

Previously, the integration of ONLYOFFICE Docs into sync and share solutions, DMS, CMS, and other cloud platforms has been described using its own API. Starting from version 6.4.0, the suite also supports WOPI.

In ONLYOFFICE Docs, WOPI is not activated by default. To enable WOPI, find (or create) the Document Server configuration file at the following path: /etc/onlyoffice/documentserver/local.json, and set the wopi.enable parameter to true.

{
  "wopi": {
    "enable": true
    }
}

ONLYOFFICE Docs can handle WOPI requests received from the trusted integrator only. The IP address of such an integrator must be included in the WOPI domain allow list. Upon that, access for all other integrators must be denied. As given, all the IP addresses are regarded as trusted, which is why you need to configure the Document Server IP filter.

Open the /etc/onlyoffice/documentserver/local.json file with any text editor and change the default settings:

"ipfilter": {
    "rules": [
    {
        "address": "ip_address",
        "allowed": true
    },
    {
        "address": "*",
        "allowed": false
    }
    ],
    "useforrequest": true,
    "errorcode": 403
}

Enter your ip_address  that can contain:

• IP in the X.X.X.X format for ipv4,
• IP in the xxxx.xxxx.xxxx.xxxx.xxxx.xxxx.xxxx.xxxx format for ipv6,
• dns-name, 
• *wildcard to replace any symbol(s).

Change the allowed parameter that can be true or false. Then, restart the services for the config changes to take effect:

supervisorctl restart all

How It Works:  WOPI Basics

WOPI defines a set of methods and operations that allow interactions between a document storage and an online editor. WOPI specification follows a certain terminology.

• WOPI server (host): A document management system that implements REST API.
• WOPI client: Online editor, in this article we use ONLYOFFICE Docs as an example.
• WOPI discovery: http(s)://<online-editor-address>/hosting/discovery

An example of the discovery data request to initialize the editor is available on the Node.js test application page. The response to the discovery request returns in XML format and contains information about ONLYOFFICE editors, supported formats, and actions (e.g. view, edit, edit new, etc.).

Example of the discovery response for ONLYOFFICE Docs:

<wopi-discovery>
 <net-zone name="external-http">
  <app name="Word" favIconUrl="https://<editor_address>/webapps/apps/documenteditor/main/resources/img/favicon.ico">
  <action name="edit" ext="docx" default="true" requires="locks,update" urlsrc="https://<editor_address>/hosting/wopi?documentType=word&mode=edit&<rs=DC_LLCC&><dchat=DISABLE_CHAT&><e=EMBEDDED&><fs=FULLSCREEN&><hid=HOST_SESSION_ID&><rec=RECORDING&><sc=SESSION_CONTEXT&><thm=THEME_ID&><ui=UI_LLCC&><wopisrc=WOPI_SOURCE&>&"/>
  <action name="view" ext="docx" urlsrc="https://<editor_address/hosting/wopi?documentType=word&mode=view&<rs=DC_LLCC&><dchat=DISABLE_CHAT&><e=EMBEDDED&><fs=FULLSCREEN&><hid=HOST_SESSION_ID&><rec=RECORDING&><sc=SESSION_CONTEXT&><thm=THEME_ID&><ui=UI_LLCC&><wopisrc=WOPI_SOURCE&>&"/>
  </app>
 </net-zone>
 <proof-key oldvalue="BgIA..." oldmodulus="qnro3n..." oldexponent="AQAB" value="BgIA..." modulus="qnro3n..." exponent="AQAB"/>
</wopi-discovery>

The used attributes include:

• <action> – action supported by ONLYOFFICE editor for a certain file format
• <ext> – file format extension
• <requires> – methods required in the REST API implementation to perform the action
• <urlsrc> – address where the action on the file is initialized

How It Works: Editor Page

To create an instance of ONLYOFFICE editor, the WOPI host creates a page with the <form> and <ifraime> elements.

We use an example page from the onlyoffice-owncloud-wopi repository:

<form id="office_form" name="office_form" target="office_frame" action="<?php p($_["actionUrl"]) ?>" method="post">
    <input name="access_token" value="<?php p($_["token"]) ?>" type="hidden" />
    <input name="access_token_ttl" value="<?php p($_["tokenttl"]) ?>" type="hidden" />
</form>

<iframe name="office_frame" id="office_frame" title="Office Frame" allowfullscreen="true"></iframe>

 <script>
        document.getElementById("office_form").submit();
</script>

 <style>
        .....
</style>

In this case, the form submission goes to the actionUrl. It is generated from urlsrc provided by discovery and includes parameters for initialization of some settings: file format, editor mode, interface language, etc.

Here is an example of actionUrl:

https://<editor_address>/hosting/wopi?documentType=word&mode=edit&wopisrc=https://<host_address>/wopi/files/1&lang=en

The wopisrc parameter points to the REST API of the host for performing operations. 

The access_token and access_token_ttl form fields are further used to access the REST API.

How It Works: Description of REST API

Each of the actions in the REST API corresponds to a different request type and url generated from wopisrc, where {fileid} is the file identifier.

The access_token parameter is added to the url to control access to the REST API.

General status codes for the response include:

• 200 OK – successful
• 401 Unauthorized – invalid token
• 404 Not Found – the fileid resource is not found

CheckFileInfo: GET /wopi/files/{fileid}

CheckFileInfo: GET /wopi/files/{fileid} is the operation performed for all actions to provide ONLYOFFICE editors with information about the file and the access rights of the current user.

The response includes a set of properties in JSON format with the following mandatory fields:

• BaseFileName – file name 
• OwnerId – ID of the file owner 
• Size – file size 
• UserId – ID of the current user 
• Version – Version of the file as a string. For each file version, this value is unique.

GetFile: GET /wopi/files/{fileid}/content

GetFile: GET /wopi/files/{fileid}/content is the operation of downloading file content from host.

The request header includes X-WOPI-MaxExpectedSize that specifies the maximum file size that the ONLYOFFICE editor can process. If the size of the requested file is larger, the host should reply with 412 Precondition failed.

The response header includes X-WOPI-ItemVersion that indicates the version of the downloaded file that must match the Version value from CheckFileInfo.

PutFile: POST /wopi/files/{fileid}/content

PutFile: POST /wopi/files/{fileid}/contentis the operation of saving the modified file.

The request headers include the following parameters:

• X-WOPI-Override – a mandatory PUT string
• X-WOPI-Lock – a mandatory lock identifier string
• X-WOPI-Editors – a string which contains ID of users who made changes to the file

The response includes the following parameters:

• X-WOPI-Lock – lock identifier string. It is set if the response is 409, and it is not set if the response is 200.
• X-WOPI-ItemVersion – version of the modified file that must match the Version value from CheckFileInfo.

When the file is being modified, the ID of the current lock and the lock from the X-WOPI-Lock header are checked. If the lock is valid, the file is being overwritten and the 200 OK response is generated. Otherwise, the response is 409 Conflict.

If the host has a file size limit and the modified file exceeds it, the response is 413 Request Entity Too Large.

Lock: POST /wopi/files/{fileid}

Lock: POST /wopi/files/{fileid} is the operation of file locking on the host. The file must not be modified by third-party applications during the editing session.

The request headers include the following parameters:

• X-WOPI-Override – a mandatory LOCK string
• X-WOPI-Lock – a mandatory lock identifier string

The response headers include the following parameters:

• X-WOPI-Lock – a mandatory lock identifier string. It is mandatory if the response is 409 Conflict, and it is optional if the response is 200 OK.
• X-WOPI-LockFailureReason is set when there is a locking error and the response is 409 Conflict.
• X-WOPI-ItemVersion – a file version that must match the Version value from CheckFileInfo.

After the file is uploaded, the ONLYOFFICE editor makes a request to lock the file. If the file has not been locked, locking is performed with the 200 OK response.

If the file is already locked, it is checked against the ID of the current lock and the lock from the X-WOPI-Lock header. If these locks match RefreshLock is performed to update the timer with the 200 OK response. Otherwise, the response is 409 Conflict.

RefreshLock: POST /wopi/files/{fileid}

RefreshLock: POST /wopi/files/{fileid} is the operation of updating the lock timer.

The request headers include the following parameters:

• X-WOPI-Override – a mandatory REFRESH_LOCK string
• X-WOPI-Lock – a mandatory lock identifier string

The response headers include the following parameters:

• X-WOPI-Lock – a mandatory lock identifier string. It is mandatory if the response is 409 Conflict, and it is optional if the response is 200 OK.
• X-WOPI-LockFailureReason is set when there is a locking error and the response is 409 Conflict.

The default locking period is 30 minutes. If the editing session lasts longer, the file is unlocked. To avoid this, the ONLYOFFICE editor repeatedly updates the lock timer again for 30 minutes.

Unlock: POST /wopi/files/{fileid}

Unlock: POST /wopi/files/{fileid} — operation of file unlocking.

The request headers include the following parameters:

• X-WOPI-Override – a mandatory UNLOCK string,
• X-WOPI-Lock – a mandatory lock identifier string.

The response headers include the following parameters:

• X-WOPI-Lock – current lock identifier string. It is mandatory if the response is 409 Conflict, and it is optional if the response is 200 OK. 
• X-WOPI-LockFailureReason is set when there is a locking error and the response is 409 Conflict.

How It Works: Customization

We can customize the interface in two ways:

1.  Dropping customization parameters into JSON at CheckFileInfo. For example:

• CloseUrl activates the button to close the ONLYOFFICE editor. When clicking on it, you will be redirected to the passed URL.
• FileSharingUrl activates the sharing button in a document. When clicking on it, you will be redirected to the sharing page in a new tab. The passed URL must match the sharing page.
• PostMessageOrigin specifies the domain of the host page to perform PostMessage.
• FileVersionPostMessage indicates support of PostMessage for the request for the previous file version.

2.  PostMessage functionality:  PostMessage allows exchanging messages in the browser between the iframe storage and ONLYOFFICE Docs. It allows the online office frame to communicate with its parent host page.

The host page provides a configured message handler. Depending on the type of the message from the editor, ONLYOFFICE performs certain operations:

window.addEventListener(‘message’, function(event) {
var msg = JSON.parse(event.data);
}, false)

Message examples include:

• UI_Close
• UI_Edit
• UI_FileVersions 
• UI_Sharing

To activate a particular type of message, we pass a certain parameter to CheckFileInfo. For example, to view the file version history, we set the FileVersionPostMessage parameter in CheckFileInfo to true.

Conclusion

These are the most important aspects of using WOPI in ONLYOFFICE Docs. Some of the basics are also available in the API documentation.

For now, the ONLYOFFICE developers are working on further enhancements for this type of integration, including work of the editors via WOPI since not all methods of this standard have been implemented, as well as interface customization.

Among the ready-to-use WOPI integrations is SharePoint which has a built-in WOPI functionality. This way the editors can be easily connected to SharePoint through its Management Shell Console. Besides, some of the integrators such as FileCloud and OpenKM have already embedded ONLYOFFICE editors via WOPI.