Plone

Requirements

• ONLYOFFICE Document Server v6.1 (server or cloud version) or later

  You need an instance of ONLYOFFICE Docs that is resolvable and connectable both from Plone and any end clients. It must be able to POST to Plone directly.

  Please refer to the official documentation page to learn more about installing ONLYOFFICE Docs.
• Python 3.4 and later
• ONLYOFFICE integration plugin 3.0.1 or later for Plone

Installing the ONLYOFFICE integration plugin for Plone

Configuring the ONLYOFFICE integration plugin for Plone

To configure plugin:

1. Go to Site Setup.
2. Scroll down to the Add-ons Configuration section.
3. Press the ONLYOFFICE Configuration button.
4. In the Document Editing service field, specify the URL address where the ONLYOFFICE Docs is located.
   The address of must be accessible from Plone, as well as the address of Plone must be accessible from ONLYOFFICE Docs.
5. In the Secret key field, specify the secret used to sign the data.
   Starting from ONLYOFFICE Docs v7.2, JWT is enabled by default and the secret key is generated automatically. You need to enable it on the Plone side as well: find your secret key in the ONLYOFFICE Docs configuration file, then specify the same secret key in the connector settings. For more details, see the Enabling JWT for the ONLYOFFICE and Plone integration section of this article.
6. In the Server address for internal requests from the Document Editing Service field, specify the address that is used to access Plone from Document Editing Service.
7. In the Document Editing Service address for internal requests from the server field, specify the address that is used to access Document Editing Service from Plone.

Developing Plone ONLYOFFICE plugin

1. Clone repository and change directory:

   git clone --branch deploy git@github.com:ONLYOFFICE/onlyoffice-plone.git cd onlyoffice-plone

2. Create a virtualenv in the package.
3. Install requirements with pip.
4. Run buildout:

   virtualenv . ./bin/pip install -r requirements.txt ./bin/buildout

5. Start Plone in foreground:

   ./bin/instance fg

If you have a working Plone instance, you can install the plugin by adding the project files to the scr directory:

1. In the scr directory, create the onlyoffice.plone directory.
2. Put your project files received by Git into the onlyoffice.plone directory.
3. Edit the buildout.cfg file:

   [buildout] ... eggs = onlyoffice.plone develop = src/onlyoffice.plone

4. Rerun buildout for the changes to take effect:

   .bin/buildout

5. Then start or restart your Plone instance.

Plone is based on Zope server and will not run as root user. If you intend to run it as root user, you must supply an effective-user directive. In order to do so, add effective-user

< username >

Upgrade Plone ONLYOFFICE integration plugin

1. If you specified a concrete plugin version in your buildout.cfg file (so-called pinning, and a recommended practice), like onlyoffice.plone = 1.0.0, update this reference to lead to the newer version. If the plugin version is not specified, then the latest version will be automatically loaded:

   [versions] ... onlyoffice.plone = 1.0.1

2. Run bin/buildout. Wait until a new version is downloaded and installed.
3. Your site may appear distorted or even become inaccessible until you complete the next step.
4. Navigate to the Add-on screen (add /prefs_install_products_form to your site URL) and in the Upgrades list select onlyoffice.plone and click Upgrade onlyoffice.plone.

How it works

The ONLYOFFICE integration follows the API documented here.

1. User navigates to a document within Plone and selects the ONLYOFFICE Edit action.
2. Plone prepares a JSON object for the Document Server with the following properties:
   • url: the URL that ONLYOFFICE Docs uses to download the document;
   • callbackUrl: the URL that ONLYOFFICE Docs informs about status of the document editing;
   • key: the UUID+Modified Timestamp to instruct ONLYOFFICE Docs whether to download the document again or not;
   • title: the document title (name).
3. Plone constructs a page from the .pt template, filling in all of those values so that the client browser can load up the editor.
4. The client browser makes a request to the JavaScript library from ONLYOFFICE Docs and sends ONLYOFFICE Docs the DocEditor configuration with the above properties.
5. Then ONLYOFFICE Docs downloads the document from Plone and the user begins editing.
6. ONLYOFFICE Docs sends a POST request to callbackUrl to inform Plone that a user is editing the document.
7. When all users and client browsers are done with editing, they close the editing window.
8. After 10 seconds of inactivity, ONLYOFFICE Docs sends a POST to callbackUrl letting Plone know that the clients have finished editing the document and closed it.
9. Plone downloads a new version of the document, replacing the old one.

Enabling JWT for the ONLYOFFICE and Plone integration

To protect documents from unauthorized access, ONLYOFFICE editors use the JSON Web Token (JWT). The token is added in the configuration when the Document Editor is initialized and during the exchange of commands between inner ONLYOFFICE Docs services. The secret key is used to sign the JSON web token and validate the token upon the request to ONLYOFFICE Docs.

Starting from ONLYOFFICE Docs v7.2, JWT is enabled by default and the secret key is generated automatically. You need to find your secret key in the ONLYOFFICE Docs configuration file, then specify the same secret key in the connector settings.

Step 1: Find your secret key in the ONLYOFFICE Docs configuration file

1. Open the local.json file with any available text editor.
   • For Linux - /etc/onlyoffice/documentserver/local.json
   • For Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json
   • For Docker – enter the ONLYOFFICE Docs container using the docker exec -it <containerID> bash command and open /etc/onlyoffice/documentserver/local.json

     Alternatively, you can use the following command to find the default secret key without opening local.json:

     sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

   The local.json file should look like this:

   {"services": {"CoAuthoring": {"token": {"enable": {"request": {"inbox": true,"outbox": true},"browser": true}},"secret": {"inbox": {"string": "yoursecret"},"outbox": {"string": "yoursecret"},"session": {"string": "yoursecret"}}}}}

2. The true value is specified in three sections. It means that token validation is enabled.
   • services.CoAuthoring.token.enable.browser
   • services.CoAuthoring.token.enable.request.inbox
   • services.CoAuthoring.token.enable.request.outbox
3. The automatically generated secret key is specified in three sections. You can replace the default secret value with your own secret key. The secret key must be the same in three sections.
   • services.CoAuthoring.secret.inbox.string
   • services.CoAuthoring.secret.outbox.string
   • services.CoAuthoring.secret.session.string
4. If you make changes, save them and restart the services for the config changes to take effect.

   supervisorctl restart all

Step 2: Specify the same secret key in the connector settings

In the connector settings, specify the same secret in the Secret key field and save the settings.

Connecting to the demo ONLYOFFICE Docs

Starting from ONLYOFFICE connector version 3.0.0, you can try the ONLYOFFICE online editors within Plone without installing ONLYOFFICE Docs.

To turn the connection on, click the Connect to demo ONLYOFFICE Document Server checkbox and click the Save button.