How to integrate

Server for hosting Collabora Online

Although it is possible to host Collabora Online on the same server where you run your web services, we strongly recommend a dedicated VM or server for that. Such a server has to be accessible from the Internet, and has to be able to connect to the server running your document storage.

Website that presents the editing capabilities

We assume that you want to integrate the editing capabilities into your existing website. On the website, you need to present an iframe where the editing UI and the document itself will be present.

To set up the iframe, the WOPI host (your application) needs to read a discovery XML from a defined location on the WOPI client (the Collabora Online server). The discovery is available at:

https://<WOPI client URL>:<port>/hosting/discovery

The reply is discovery.xml that contains urlsrc for various file formats. The urlsrc specifies the address that you need to use for the iframe that you create for the document editing, and is set as an attribute of the HTML and or tag of the document.

You also need to pass the authentication token to Collabora Online via a form post, and the actual URL that your file storage can accept. The URL should look like:

https://<WOPI host URL>/<...>/wopi/files/<id>

Here /wopi/ can actually be any string that starts with wopi, like /wopifiles/ or /wopi_implementation/, but for simplicity, we will be using only /wopi/ in the following text.

<id> should be URL-safe base64 (base64url) encoded, ie. only contain letters (A-Z, a-z), numerals (0-9), and - and _ symbols.

Authentication

To be able to access files securely, your application has to pass an authentication token to Collabora Online access_token. From the Collabora Online point of view, it can be any random number / string, that will be passed as part of the URL when accessing the document storage.

The only requirements are that it has to be unique for the user, that the file storage denies access with wrong authentication token, and that it can be passed in an URL (ie. contains just characters / numbers / underlines).

You can also pass access_token_ttl during the iframe creation to specify when the token expires. The value is a UNIX timestamp, the number of milliseconds since the UNIX epoch, i.e. January 1st 1970. This TTL indicate when Collabora Online should notify the users, 15 minutes prior, that the session will expire. You pass it at the same time as the access_token for the iframe creation.

Currently this is the only supported way of authentication (access_header has been deprecated).

Connection to the file storage

As the WOPI host, your existing solution has to implement few entry points for Collabora Online (the WOPI client), so that Collabora Online can download files that the user wants to edit, and upload back the updates.

The WOPI client (Collabora Online) invokes the WOPI url created above to download the file:

GET https://<WOPI host URL>/<...>/wopi/files/<id>/contents?access_token=<token>

And to upload a file:

POST https://<WOPI host URL>/<...>/wopi/files/<id>/contents?access_token=<token>

Currently, Collabora Online only depends on WOPI File Operation functions (GetFile/PutFile/CheckFileInfo). As a bare minimum, your application has to support the following four functions:

  1. A function that generates a token for a given file and user (probably you want to store that in a DB, optionally with expiration).

  2. GetFile that sends back the content of the file when the

    https://<WOPI host URL>/<...>/wopi/files/<id>/contents?access_token=<token>

  3. PutFile that replaces the file with the body of the POST verb when invoked with the

    https://<WOPI host URL>/<...>/wopi/files/<id>/contents?access_token=<token>

    URL.

    • An optional LastModifiedTime field, containing the ISO8601 round-trip time format indicating the new/updated file’s modified time in storage after successful save, can be added to the JSON response. See Further differences to WOPI for more details.

  4. PutRelativeFile that creates a new file with the body of the POST verb for the needs of the Save As operation when invoked with

    https://<WOPI host URL>/<...>/wopi/files/<id>?access_token=<token>

    URL. If you do not want to support the Save As operation, please add UserCanNotWriteRelative with value true to your CheckFileInfo answer. It is request header X-WOPI-SuggestedTarget that is supported.

  5. CheckFileInfo that returns (at least) the BaseFileName and Size of the file as json when the

    https://<WOPI host URL>/<...>/wopi/files/<id>?access_token=<token>

    URL is invoked. Collabora Online takes the following required CheckFileInfo properties:

    • BaseFileName – The string name of the file without a path. Used for display in user interface (UI), and determining the extension of the file.

    • OwnerId – A string that uniquely identifies the owner of the file.

    • Size – The size of the file in bytes, expressed as a long, a 64-bit signed integer.

    • UserId – A string value uniquely identifying the user currently accessing the file.

    Collabora Online takes the following optional CheckFileInfo properties:

    • UserFriendlyName – The name of the user, suitable for displaying on the UI.

    • UserCanWrite – It has to be set to true if the file is opened for editing.

    • PostMessageOrigin – It is used by PostMessage API.

    • HidePrintOption – Hides print button from UI but accessible using PostMessage API so hosts can implement their own UI for this.

    • DisablePrint – Disables printing of documents. Additionally, hides print option from UI.

    • HideSaveOption – Hides save button from UI. Manual save can still triggered using PostMessage API. Does not affect automatic save.

    • HideExportOption – Hides ‘Download as’ button/menubar item from UI. Can still be triggered using PostMessage API.

    • HideRepairOption - hide the repair button.

    • DisableExport – Disable export of the document in any format. Additionally, hides the ‘Download as’ button from the UI.

    • DisableCopy – Disable copying from the document.

    • EnableOwnerTermination – This gives document owners the ability to terminate all sessions currently having that document opened.

    • LastModifiedTime – ISO8601 round-trip time format for file’s last modified time in storage.

    • IsUserLocked – Lock the user from using certain feature(s) which can be later be unlock by user.

    • IsUserRestricted – Disable feature(s) for the user.

    • SupportsRename - Set to false to disable file renaming.

Re-using our development / demo-servers

One easy way to test your WOPI integration without even needing to setup Collabora Online for both development, and your users is to target one of our demo servers read how to do that properly you can provide users’ a list of servers from this end-point however please bear in mind these factors:

  • you must have a publicly routable and resolvable WOPI server. If you pass our demo servers a WOPI URL to 192.168.1.5 we will not be able to get to the document data (obviously) to load, save and render it. Of course, it can be rather easier to trace protocol problems in the logs of your own server too.

  • it is vitally important to let the user know that their data will be shared with others and that they should not include personally identifying information into their test documents.

  • it is worth reminding users that the performance of such a shared test server can be extremely variable and is not representative of a properly setup on-premise installation.

Further differences to WOPI

In addition to the basics of WOPI as described in WOPI specifications, Collabora Online implements various extensions, in addition to those outlined above primarily associated with CheckFileInfo, to support some features that you may find useful.

  1. Custom Button API: It is possible to add your own custom buttons to the editor’s UI. For more information, you can check insert_button and clicked_button API PostMessage API.

  2. Detecting external document change: In some cases, when the document is updated in your storage while being edited in Collabora Online and there are unsaved changes, we detect it as soon as possible and ask the user if he/she would like to overwrite the changes or reload the new document from the storage.

    In case there are no unsaved changes, we reload the new document without asking the user.

    To be able to support this feature, you need to specify LastModifiedTime field in both CheckFileInfo and PutFile calls as described above in its documentation.

    Additionally, WOPI hosts must check for a header in PutFile response – X-COOL-WOPI-Timestamp. This header contains the ISO8601 round-trip formatted time of file’s last modified time in storage, as known by Collabora Online. In case, this header is present and its value doesn’t match with the file’s modified time in storage, it indicates that document being edited is not the one that is present in the storage. WOPI hosts should not save the file to storage in such cases and respond with HTTP 409 along with Collabora Online specific status code for this purpose in JSON response against the field COOLStatusCode. The COOLStatusCode for this purpose is 1010. So, the desired response should be:

    HTTP 409 with JSON
    1{
2    'COOLStatusCode': 1010
3}