Apprendre à intégrer ONLYOFFICE à la gestion électronique des documents créés sur Nextcloud

MariePa

ONLYOFFICE est une suite bureautique collaborative libre, trois-en-une, distribuée sous les termes de la licence de GNU AGPL v 3. Elle comporte un logiciel de traitement de texte, un tableur et un outil de présentation compatibles avec les formats OOXML (.docx, .xslx et .pptx), ainsi qu’avec d’autres formats courants. La suite en question peut être intégrée dans des sites ou des applications web tierces, afin d'être utilisée depuis leur interface.

Commentez

- Titre : Apprendre à intégrer ONLYOFFICE à la gestion électronique des documents créés sur Nextcloud

- Auteur : MariePa

- Parution : 27 février 2020

- Licence : Copyright ® 2019 MariePa. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

- II. Prérequis

- III. Comment créer l’application d’intégration

- III-A. Ajouter et exécuter le code

- III-B. Accéder aux fichiers

- III-C. Ajouter des boutons à l'interface utilisateur

- III-D. Ouvrir une page avec un éditeur

- III-E. Paramétrer l'application

- IV. Comment intégrer ONLYOFFICE à Nextcloud

I - Introduction

Le tutoriel publié précédemment, porte sur l’installation des éditeurs de documents en ligne ONLYOFFICE et de son intégration avec d’autres solutions WEB écrites en différents langages de programmation : .Net (C#), Node.js sur Windows et sur Linux. Dans cet article, notre objectif sera de voir de plus près l’intégration de ONLYOFFICE avec la Gestion Électronique des Documents (GED ou DMS en anglais pour Document Management System), en nous basant sur l’un des systèmes les plus populaires de synchronisation et de partage de fichiers, écrit en langage PHP, Nextcloud.

L’intégration s’effectue à travers la création de l’application d’intégration qui servira de pont reliant les éditeurs (ONLYOFFICE Document Server) à Nextcloud, rendant ainsi possible :

- l’édition et la révision de documents texte, de feuilles de calcul et de présentations ;

- la coédition de documents en temps réel.

II - Prérequis

Avant tout, vous devez installer des éléments nécessaires à l’intégration :

- Nextcloud v.11.0.2 ou une version plus récente ;

- ONLYOFFICE Document Server en pack snap.

ONLYOFFICE a récemment mis à disposition des utilisateurs le Document Server sous forme du pack snap. L’application est disponible au téléchargement sur Snapcraft Store et peut également être installée en une seule commande sur tous les dérivés du Linux :

snap install onlyoffice-ds

Vous pouvez aussi installer ONLYOFFICE Document Server en utilisant Docker ou les packs .deb ou .rpm selon l’environnement sur lequel vous êtes. Les consignes d’installation avec Docker, ainsi que les configurations de système requises sont présentées dans ce tutoriel.

III - Comment créer l’application d’intégration

Une fois Nextcloud et ONLYOFFICE correctement installés, l’étape suivante c’est de les relier à l’aide du connecteur. Pour créer le connecteur, il est indispensable de savoir : comment procéder à l’intégration, quelles autorisations doivent être accordées à ONLYOFFICE et comment les mettre en place. Voici les cinq étapes qui vont apporter les réponses à ces questions et permettront de créer le connecteur entre ONLYOFFICE et Nextcloud, qui pourra servir d’exemple de connecteur pour votre propre service.

Lors de la création et de la configuration de l’application d’intégration, vous devez tenir compte des autorisations sous-mentionnées qui doivent être accordées à ONLYOFFICE pour rendre l’intégration possible :

1. Ajouter et exécuter le code ;

2. Accéder aux fichiers sans demander aucune donnée d’utilisateur de la part du client ;

3. Ajouter des boutons à l’interface utilisateur ;

4. Ouvrir une page avec un éditeur ;

5. Paramétrer l’application.

Voyons de plus près chacune de ces étapes de la création du connecteur :

III-A - Ajouter et exécuter le code

ONLYOFFICE ne modifie pas le code source. En effet, le service doit permettre d’ajouter les modules utilisateur, les modules complémentaires, les packs ou les applications.

Nextcloud permet aux développeurs d'ajouter leurs propres applications pour améliorer le partage avec des fonctionnalités supplémentaires. Toutes ces applications sont disponibles dans l'App Store, y compris l’application d'intégration de ONLYOFFICE pour Nextcloud.

Le code source de l’application est également disponible sur GitHub. Vous pouvez l’y récupérer, le compiler et le déposer sur le serveur Nextcloud dans la catégorie des applications. Ce code peut ainsi servir d’exemple lors de la création de votre propre connecteur.

Après avoir compilé l’application, configurez-la en suivant les étapes ci-dessous.

Comme cité précédemment, Nextcloud et ses modules complémentaires sont écrits en langage PHP, c’est pourquoi tous les exemples de code dans cet article sont écrits en PHP.

III-B - Accéder aux fichiers

Pour accéder aux fichiers, il faut créer une fonction de rappel. Elle est conçue pour renvoyer les demandes de ONLYOFFICE Document Server vers la GED.

En fonction des paramètres de la demande, des actions correspondantes peuvent être exécutées sur la GED (par exemple, récupérer le contenu d'un fichier ou enregistrer un fichier). Il est essentiel d’avoir une interaction directe entre le Document Server et la GED qui assure un accès anonyme aux fichiers téléchargés ou enregistrés. Cela veut dire que l’interaction entre le Document Server et la GED s’effectue seulement du côté serveur, sans demander de données d'autorisation d'utilisateur de la part du client, données telles que les cookies du navigateur.

La sécurité y est assurée au moyen de la technologie JWT. Les données sont vérifiées à l'aide d'une signature numérique. Le Document Server ajoute JWT à la demande en utilisant le mot de passe de son fichier de configuration, et la GED le vérifie en utilisant, à son tour, le mot de passe de son fichier de configuration. La fonction de rappel exécute la demande seulement dans le cas où la signature est correctement validée.

Pour la GED, la fonction de rappel est sollicitée lorsque les demandes sont envoyées aux URL suivantes :

1. "routes" => [

2. ["name" => "callback#download", "url" => "/download", "verb" => "GET"],

3. ["name" => "callback#track", "url" => "/track", "verb" => "POST"],

4. ...

5. ]

La validation de la signature est exécutée pour les demandes entrantes :

1. try {

2. $decodedHeader = \Firebase\JWT\JWT::decode($header,

3. $this->config->GetDocumentServerSecret(), array("HS256"));

4. } catch (\UnexpectedValueException $e) {

5. return new JSONResponse(["message" => $this->trans->t("Access denied")],

6. Http::STATUS_FORBIDDEN);

7. }

Le Document Server demande le contenu du fichier à la GED :

1. class CallbackController extends Controller {

2. public function download($doc) {

3. $file = $this->getFile($doc);

4. return new DataDownloadResponse($file->getContent(), $file->getName(),

5. $file->getMimeType());

6. }

7. ...

8. }

Pour enregistrer le fichier dans la GED :

1. class CallbackController extends Controller {

2. public function track($doc, $status, $url) {

3. $error = 1;

4. switch ($status) {

5. case "MustSave":

6. $file = $this->getFile($doc);

7. if (($newData = $this->Request($url))) {

8. $file->putContent($newData);

9. $error = 0;

10. }

11. break;

12. case "Editing":

13. case "Closed":

14. $error = 0;

15. break;

16. }

17. return new JSONResponse(["error" => $error], Http::STATUS_OK);

18. }

19. ...

20. }

La réponse doit être la suivante :

{"error": 0}

III-C - Ajouter des boutons à l'interface utilisateur

Le travail avec ONLYOFFICE pour les utilisateurs définitifs commence par les boutons tels que « Ouvrir », « Modifier », « Créer nouveau » ou « Convertir ». Ces actions peuvent être associées aux types de fichiers correspondants :

- « Voir » : docx, xlsx, pptx, csv, txt, pdf ;

- « Modifier » : docx, xlsx, pptx, csv, txt ;

- « Créer nouveau » : docx, xlsx, pptx, txt ;

- « Convertir » : en Office Open XML formats (docx, xlsx, pptx): doc, docm, dot, dotx, epub, htm, html, odp, odt, pot, potm, potx, pps, ppsm, ppsx, ppt, pptm, rtf, xls, xlsm, xlsx, xlt, xltm, xltx.

(Il faut également tenir compte des types de droits d'accès qui sont réservés aux utilisateurs).

Nextcloud permet d’exécuter les scripts côté client et d’ajouter les boutons à leur menu contextuel. Le code ci-dessous permet de créer un bouton pour ouvrir un fichier docx :

1. fileList.fileActions.registerAction({

2. name: "onlyofficeOpen",

3. displayName: t(OCA.Onlyoffice.AppName, "Open in ONLYOFFICE"),

4. mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",

5. permissions: OC.PERMISSION_READ,

6. iconClass: "icon-onlyoffice-open",

7. actionHandler: function(fileName, context) {

8. window.open(OC.generateUrl("/apps/" + OCA.Onlyoffice.AppName +

9. "/" + context.fileInfoModel.id);

10. }

11. });

III-D - Ouvrir une page avec un éditeur

Lorsque l’utilisateur clique sur un bouton d'action, une nouvelle page avec les configurations d'initialisation est générée. À cette étape, ONLYOFFICE vérifie s’il est possible d'ouvrir le fichier et si l’utilisateur est doté de droits d'accès nécessaires.

En outre, des paramètres supplémentaires de l'éditeur, tels que les paramètres de l'interface, peuvent être configurés. Par exemple, document.permissions.download = false supprime le bouton de téléchargement du fichier de l'éditeur, et editorConfig.lang = "de-DE" change la langue de l'interface en allemand.

Dans Nextcloud, ce mécanisme est implanté en tant que gestionnaire de demandes, séparément :

1. class EditorController extends Controller {

2. public function config($fileId) {

3. $file = $this->getFile($fileId);

4. $fileName = $file->getName();

5. $ext = strtolower(pathinfo($fileName, PATHINFO_EXTENSION));

6. $formats = [

7. "docx" => [ "type" => "text" ],

8. "xlsx" => [ "type" => "spreadsheet" ],

9. "pptx" => [ "type" => "presentation" ]

10. ];

11. $params = [

12. "document" => [

13. "fileType" => $ext,

14. "key" =>  $this->getKey($file),

15. "title" => $fileName,

16. "url" => $this->getUrl($fileId),

17. ],

18. "documentType" => $format[$ext]["type"]

19. ];

20. if ($file->isUpdateable()) {

21. $params["editorConfig"]["callbackUrl"] = $this->urlGenerator->linkToRouteAbsolute(

22. $this->appName . ".callback.track", ["doc" => $fileId]);

23. } else {

24. $params["editorConfig"]["mode"] = "view";

25. }

26. return $params;

27. }

28. ...

29. }

À cette étape, les paramètres suivants du document sont définis :

- "fileType" : définit le type du fichier pour le document source que l’on ouvre pour la lecture ou l’édition ;

- "key" : définit l’unique identifiant du document pour qu’il soit reconnu par le service. Dans le cas où l’identifiant envoyé est reconnu par le service, le document sera récupéré du cache. À chaque fois que le document est modifié et enregistré, l’identifiant est généré à nouveau ;

- "title" : définit le nom que vous choisissez pour le document en cours de lecture ou de rédaction. Ce nom peut également être attribué au document lors de son téléchargement ;

- "url" : définit une adresse URL absolue où le document source en cours de lecture ou de rédaction est stocké.

Plusieurs utilisateurs peuvent modifier le même fichier au même moment. Dans ce cas, la modification est possible grâce à l'utilisation du même document.key pour le même fichier, ouvert simultanément par plusieurs utilisateurs :

1. private function getKey($file) {

2. $instanceId = $this->config->getSystemValue("instanceid");

3. $key = $instanceId . "_" . $file->getId() . "_" . $file->getMtime();

4. return $key;

5. }

Ajoutez la signature JWT pour protéger les configurations contre les changements indésirés :

1. if (!empty($this->config->GetDocumentServerSecret())) {

2. $token = \Firebase\JWT\JWT::encode($params, $this->config->GetDocumentServerSecret());

3. $params["token"] = $token;

4. }

III-E - Paramétrer l'application

L'application d'intégration possède des paramètres généraux, tels que l'adresse du Document Server, ainsi que des paramètres personnels d’utilisateur, tels que les préférences utilisateur. Vous pouvez configurer l'application en utilisant des fichiers de configuration côté serveur ou en créant une page web de paramètres. Dans l’application d’intégration de ONLYOFFICE pour Nextcloud, les paramètres de connexion sont disponibles sur la page Administrateur. La capture d’écran ci-dessous représente la page Administrateur de la dernière version de l’application. Comme vous le voyez, la page a été renouvelée avec la division des paramètres perso et administratifs en deux sections. En outre, l’interface de l’éditeur, dès maintenant, peut être personnalisée.

IV - Comment intégrer ONLYOFFICE à Nextcloud

Le connecteur est prêt à être utilisé. Pour intégrer ONLYOFFICE à Nextcloud, il suffit de placer le connecteur créé sur le serveur Nextcloud dans la catégorie des applications. L’intégration se fait en quelques étapes simples :

1. Ouvrez Nextcloud. Allez sur Apps >> Not Enabled >> ONLYOFFICE et cliquez sur le bouton « Enable » ;

2. Passez aux paramètres Administrateur sur Nextcloud, ouvrez la section de ONLYOFFICE et saisissez l’adresse de ONLYOFFICE Document Server installé. Il est également possible de spécifier les extensions des fichiers que les utilisateurs peuvent ouvrir avec l'éditeur en ligne.

Vous pouvez dès maintenant modifier seul ou en collaboration, les documents stockés sur Nextcloud en utilisant les éditeurs de documents ONLYOFFICE.

Pour créer un nouveau document, une feuille de calcul ou une présentation, utilisez le bouton « + ».

Pour modifier un fichier existant, choisissez dans le menu contextuel l’option « Open with ONLYOFFICE ».

En suivant les étapes de ce tutoriel, vous pouvez désormais créer votre propre application d'intégration.