OnlyOffice Integration Module

This Share plugin enables users to edit and preview Office documents within ONLYOFFICE from Alfresco Share. This will create a new Edit in ONLYOFFICE action within the document library for Office documents. This allows multiple users to collaborate in real time and to save back those changes to Alfresco.

example_lock

Features

  • Creates a new Edit in OnlyOffice Action within the document library for office documents.
  • Allows multiple users to collaborate in real time and save back changes to Alfresco.
  • Web Preview for Excel, Powerpoint and Word documents replacing the default PDF view.
  • Transformation of Excel, Powerpoint and Word documents to PDF using OnlyOffice.

Changelog

The change log for OnlyOffice can be found here

Installation

Alfresco

OnlyOffice comes with both a Share and Repo AMP. Please follow our Installation guide on how to install this module. You will also need to add the correct onlyoffice.url to global properties, please see configuration below.

ONLYOFFICE

You will need an instance of ONLYOFFICE that is resolvable and connectable both from alfresco and any end clients. ONLYOFFICE must also be able to POST to alfresco directly.

The easiest way to start an instance of ONLYOFFICE is to use Docker: https://github.com/ONLYOFFICE/Docker-DocumentServer

Usage

Realtime Collaboration

  • Navigate to an Office Document such as a word document within Alfresco Share.
  • Select the Edit in Onlyoffice action:

editinonlyoffice

  • This will lock the document in Alfresco until you are finished, but leaving the Edit in OnlyOffice action available for other users:

example_lock

  • If a Document is being edited by someone else, you can join them by clicking on the banner above the document, or by clicking the Edit in OnlyOffice action:

lock_banner

Web Preview

Web preview of documents replaces the default pdfjs viewer in Alfresco. This is a much more usable experience for documents such as excel spreadsheets and powerpoint presentations.

This is an automatic feature, and will display the preview for the following document types by extension:

  • Word: docx, docm, dotx, dotm, doc
  • Excel: xlsx, xlsm, xlt, xls
  • Powerpoint: pptx, pptm, potx, potm, ppt

Transformation

Transformation is also automatic, and will replace the default transformer for the following file type combinations:

  • docx to pdf
  • doc to pdf
  • pptx to pdf
  • ppt to pdf
  • xlsx to pdf
  • xls to pdf

Configuration

The OnlyOffice integration has a number of configuration options:

  • The onlyoffice URL needs to be known and accessible. You can let Alfresco know where to find onlyoffice by adding the onlyoffice.url property to alfresco-global.properties:
onlyoffice.url=https://documentserver/
  • OnlyOffice will make the connection to Alfresco on behalf of the client, so OnlyOffice needs to be able to talk to Alfresco. In order for OnlyOffice to do this, Alfresco needs to generate what it thinks the external URL is. Make sure that the following properties are set correctly in alfresco-global.properties
alfresco.protocol=http
alfresco.host=alfresco.yourcompany.local
alfresco.port=8080
alfresco.context=alfresco
  • The integration uses a HMAC-SHA256 token based system to communicate to Alfresco from OnlyOffice. This connection used to use the user's alf_ticket value, but was found to be unreliable, and would reset if the sessions are flushed. The secret token is generated based upon the hostname of the server, but can be explicitly set in the global properties:
onlyoffice.token=<Secret Token here>
  • (Optional) set the default language that the editor will use. By default the document editor should pick up the language of the browser, so it doesn't always need to be set.
onlyoffice.lang=en
  • (Optional) set another URL to use for PDF transformations. By default when converting files to PDF it will use the onlyoffice.url:
onlyoffice.transform.url=http://documentserver/
  • (Optional) if the office documents in your environment are very large, some browsers can struggle to render them with the web preview. Document sizes and content values can be thresholded, so the preview will not appear above the threshold. This feature is not turned on by default. You can adjust the thresholds of various documents by editing the following values:
onlyoffice.preview.document.size.threshold=10485760
onlyoffice.preview.docx.threshold=8000
onlyoffice.preview.doc.threshold=8000
onlyoffice.preview.xlsx.threshold=10000
onlyoffice.preview.xls.threshold=10000
onlyoffice.preview.pptx.threshold=1000
onlyoffice.preview.ppt.threshold=1000

How it works

The Onlyoffice integration follows the API documented here https://api.onlyoffice.com/editors/basic:

  • User navigates to a document within Alfresco Share and selects the Edit in ONLYOFFICE action.
  • Alfresco Share makes a request to the repo end (URL of the form: /parashift/onlyoffice/prepare?nodeRef={nodeRef}).
  • Alfresco Repo end prepares a JSON object for Share with the following properties:
    • docUrl: the URL that ONLYOFFICE uses to download the document (includes the alf_ticket of the current user),
    • callbackUrl: the URL that ONLYOFFICE informs about status of the document editing. This uses the username + secret token HMAC-SHA256 checksum, rather than normal authentication.
    • onlyofficeUrl: the URL that the client needs to talk to ONLYOFFICE (given by the onlyoffice.url property),
    • key: the UUID+Modified Timestamp to instruct ONLYOFFICE whether to download the document again or not,
    • docTitle: the Title (name) of the document.
  • Alfresco Share takes this object and constructs a page from a freemarker template, filling in all of those values so that the client browser can load up the editor.
  • The client browser makes a request for the javascript library from ONLYOFFICE and sends ONLYOFFICE the docEditor configuration with the properties as above.
  • ONLYOFFICE then downloads the document from alfresco and the user begins editing.
  • ONLYOFFICE sends a POST request to the callback URL to inform Alfresco that a user is editing the document.
  • Alfresco locks the document, but still allows other users with write access the ability to collaborate in real time with ONLYOFFICE by leaving the Action present.
  • When all users and client browsers are finished, they close the editing window.
  • After 10 seconds of inactivity, ONLYOFFICE sends a POST to the callback URL letting Alfresco know that the clients have finished.
  • Alfresco downloads the new version of the document, replacing the old one.