Implement WOPI for File-Editing

1 Initial Problem

ILIAS has always offered the function to manage files and offers with its rights system a comprehensive possibility to make files available to certain users and to publish them.
Up to now ILIAS does not offer the possibility to edit files together. Especially for file formats like OASIS (Open Document Format for Office Applications) or files like Word and Powerpoint, one would like to be able to edit them from ILIAS.
To write an editor to edit such file types online would definitely overwrite the resources of the ILIAS community. Such editors already exist and are themselves very large projects that require maintenance.

To enable collaborative editing of files, one possibility would be to integrate such an editor into ILIAS. But by direct integration ILIAS would be dependent on this project. In addition, many institutions already have their own services that enable collaborative editing of files (e.g. Office365).

2 Conceptual Summary

Microsoft presented the first version of the so-called "Web Application Open Platform Interface" (WOPI) back in 2012. Microsoft has been using WOPI itself for many years to transfer files between Sharepoint, Exchange, etc. and Office Online. The specification of WOPI is currently available in version 14.0 from 16.11.2021. In addition to Microsoft, Google, ownCloud and nextcloud also use WOPI for communication between processing services and file storage.

In order to best equip ILIAS for the use of online editing tools, we propose to provide the WOPI interface in ILIAS.

2.1 The Web Application Open Platform Interface

The current specification of the WOPI can be found at: https://interoperability.blob.core.windows.net/files/MS-WOPI/%5bMS-WOPI%5d-211116.pdf, a copy can be downloaded here:

The specification defines how a WOPI endpoint must look like and which routes (REST) must be provided to work as a WOPI client.

2.2 Discovery URL and parsing

A WOPI client provides the information about which file types can be edited via the discovery URL and in each case with a URL for the editor, which can be included in ILIAS using iFrame.

In a first step we would suggest the use of a single disocvery URL. Theoretically, multiple URLs would be possible (e.g. from Colabora and Office365), but the users or the admins would have to decide which editor to use in case of duplicate file types.

For better performance the Discovery XML should be parsed locally in ILIAS and stored in the database. It should then be possible to update the information via the administration and/or as a cron job. There will bes stored:

• File-Extension (e.g. doc, docx, ...)
• action (e.g. view, edit)
• url (to the editor/view app)
• last update

Only default-actions/urls are stored and only one per file-extension.

2.3 Access-Token and Start Page

The First Request to a Editor-Action (URL provided by the Discovery-XML) contains an access token and a token TTL. The WOPI API will call all APIs with this token then. ILIAS can revalidate this token and decide to provide the called infos or not. The Token must be unique for the current User and Resource and should be invalidated after some time.

See https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/concepts#access-token

This fist Request to the Action URL must start with a POST request to the url given.  This means ILIAS must provide a Button and/or send the form immediately using JS when loading the Page (see User Interface Modifications below).

Minimal Host Page: https://github.com/Microsoft/Office-Online-Test-Tools-and-Documentation/blob/master/samples/SampleHostPage.html

2.4 Required API routes for ILIAS

The first step is the joint editing of documents. At least the following WOPI routes must be implemented:

• CheckFileInfo
• GetFile
• PutFile
• Lock
• Unlock

All API calls must be able to be placed under /wopi/... by definition. In ILIAS we can enable this via two variants:

• A) RewriteRules are defined in the .htaccess file that redirect requests to /wopi/... to any other location (e.g. to a new endpoint to be defined within /webservices. This variant does not require any additions to the ILIAS webroot (see variant B), but it only works under certain circumstances without further adjustments: 1. ILIAS is run with Apache. 2. Apache allows RewriteRules (activated and possible to add via .htaccess). In case of Nginx separate rules have to be included directly in the webserver configuration, otherwise WOPI would not work with ILIAS without them.
• B) A new directory in the ILIAS root, which then contains one or more dedicated endpoints for the API calls from the WOPI client and the WOPI host (ILIAS). Currently we have a policy that no new directories or files can be added to the webroot. However, this variant is available without customization regardless of the web server used (Apache/Nginx).

3 User Interface Modifications

3.1 List of Affected Views

• A new Menu-Item in Administration > Extending ILIAS called "WOPI"
• facs/file_objects/settings: New Settings for "Use WOPI for File-Editing of supported File-Types".  A checkbox to activate WOPI and a dependent Text-Input for the WOPI-Client-URL.
• Action-Menu of File-Objects in Repository: If their file-type has a supported WOPI-Edit-Action-URL in the Discovery.xml, e new Action-Menu-Item "Open in Editor" is provided (User needs write-Access to the object).
• An additional Button "Open in Editor" on the Info-Screen of a File-Object (User needs write-Access to the object).

3.2 User Interface Details

3.3 New User Interface Concepts

none

3.4 Accessibility Implications

The accessibility of the WOPI clients cannot be influenced. By the fact that these are called in an iFrame, additional complications could be added. The iFrame shoud have a title according to https://www.boia.org/wcag2/cp/4.1.2

4 Technical Information

Editing of an ILIAS resource from the Resource Storage Service should be available for all components that already use the IRSS and want to enable editing of the files. For this purpose, a specific WOPI client-consumer will be implemented. The Cosumer delivers a fitting Editor-URL if avaiable or null if there is no such Editor for the file-type or if the feature is not avaiable at all.

5 Privacy

ILIAS itself in this case only processes the user ID of a user who wants to edit a file via the WOPI interface. On the side of the WOPI clients (e.g. Office Online), ILIAS has no influence on ensuring privacy.

6 Security

A new endpoint (WOPI interface) generally creates a new attack vector. This should at least be ensured by using the client token procedure.

7 Contact

• Author of the Request: Schmid, Fabian [fschmid]
• Maintainer: Schmid, Fabian [fschmid]
• Implementation of the feature is done by: Schmid, Fabian [fschmid] / Fuhrer, Thibeau [tfuhrer]

8 Funding

If you are interest in funding this feature, please add your name and institution to this list.

• Technische Hochschule Ostwestfalen-Lippe
• ILIAS.nrw
• Kivinan BBS Zeven wolfgang.huebsch@kivinan.de

9 Discussion

Kergomard, Stephan [skergomard], 02 DEC 2022: Thank you very much Schmid, Fabian [fschmid] for this concept! I'm very much looking forward to having this option available!

Two remarks:

• I've a clear preference for option A (rewrite-rules) for the API endpoints. Adding folders would only feel right if we had some kind of clear structure for all APIs, otherwise it seems clunky and messy to me.
• I don't think frameing is the right option. There will be far to complex information on screen. For me this would be a classical case for a mode, i.e. "File-Editing-Mode". An implementation can be seen in nexcloud (print-screen below, I can provide access if necessary). The Editor takes over the whole screen and needs to be closed to get back out. This would also reduce issues happening on leaving the page through other means. Do you see a need to do this in page for ILIAS?
• Just an idea: We could potentially even allow for opening all files online and allow editing for some people with the corresponding rights through a second click (done ie. in the nexcloud-app on mobile). 

10 Implementation

The feature was implemented as described. Since in addition to this feature request, other ones have been implemented here for ILIAS 9 in connection with WOPI, the complete implementation is documented here. This also includes the following features:

• New Permission to Edit File using WOPI
• Use IRSS-Draft-Revisions for WOPI Edited Files

WOPI can be activated in the administration. A valid and accessible discovery URL must be entered:

Subsequently, files with file extensions for which the WOPI service offers an app can be edited directly via ILIAS. There are three places where the action can be started:

• Actions menu in the magazine
• Info Tab
• Versions Tabs

The Editor has been sligtly adopted after reports in:

• https://mantis.ilias.de/view.php?id=39341
• https://mantis.ilias.de/view.php?id=38625

Editing requires the "Edit File" permission, without this permission the button or action will not be displayed either. The right can be assigned regularly via the permissions tab. The permission is also assigned in an update step to all roles that also have the permission "Edit Settings".

When editing a file via WOPI, a new version is created in the File object with the status "Draft". Once such a version exists, no new version can be uploaded in ILIAS until the version is published via the "Publish Draft" button. As long as a "Draft" exists, the last "Pusblished" version is downloaded and displayed on the info page. Only after publishing the draft this version is accessible.

Test Cases

Test cases completed at 16/10/2023 by Schmid, Fabian [fschmid]

• C63534: WOPI-Endpoint konfigurieren
• C63535: Editierrecht vergeben (moved to RBAC suite where all permission related test cases are collected)
• C63536: Datei in externem Editor bearbeiten
• C63537: Entwurf veröffentlichen

Approval

Approved at 24.10.2023 by Fréquelin, Fabrice [frequelin], FernUniversität in Hagen
Approved at 24.10.2023 by Fischer, Yvonne [yvonne.fischer], TH OWL