I. Introduction▲
Nous continuons la série de tutoriels qui apprennent à intégrer la suite bureautique en ligne ONLYOFFICE Docs avec des services web tiers dont par exemple Nextcloud ou une application GED en Python. Parmi les intégrations disponibles figurent notamment ownCloud, SharePoint, Seafile, Liferay, Plone, Nuxeo, Chamilo, Jalios, eXo Platform, GoFast et bien d’autres applications web reliées avec ONLYOFFICE Docs via les connecteurs prêts à l’emploi fournis par ONLYOFFICE ou résultant de partenariats technologiques.
Quel est l’objectif principal de ces intégrations ? Le but est de compléter l’éventail de leurs outils existants avec des éditeurs en ligne assurant la mise en forme des documents texte, des classeurs et des présentations (DOCX, XLSX, PPTX) de toute complexité et leur rédaction collaborative en temps réel directement dans l’interface de ces plateformes. Pour en savoir davantage sur les capacités fonctionnelles de ONLYOFFICE Docs, consultez cet article.
Dans ce tutoriel, nous allons vous montrer comment créer une application d’intégration qui va servir de pont reliant les instances ONLYOFFICE Docs et Confluence, la solution de travail collaboratif se focalisant sur la gestion et le partage des contenus.
 |
II. Prérequis▲
Avant tout, il est indispensable d’installer des éléments nécessaires à l’intégration.
- ONLYOFFICE Docs
Vous pouvez déployer ONLYOFFICE Document Server en utilisant les paquets DEB ou RPM, l’image Docker, le paquet Snap, la machine virtuelle Univention, Amazon, l’environnement Cloudron, les conteneurs Kubernets qui sont disponibles sur le site officiel.
- Environnement Confluence
Avant tout, vous avez besoin d’installer le SDK Atlassian qui encapsule le binaire Maven permettant de créer les extensions et les tester au sein d’une application Atlassian lancée.
Pour l’installer, suivez ces consignes pour Windows, Linux ou Mac.
Ensuite, créez le fichier de base pour l’extension Confluence. Ouvrez la ligne de commande et lancez la commande suivante : atlas-create-confluence-plugin. L’outil va vous demander quelques détails pour la création d’une extension simple.
Vous pouvez paramétrer l’ouverture de l’extension dans votre environnement de développement intégré. Pour cela, il vous faudra définir quelques paramètres supplémentaires.
Il n’y a pas de consignes spéciales sur la configuration de l’éditeur VSCode, vous pouvez le paramétrer en utilisant Maven qui vient ensemble avec le SDK. Créez le fichier de configuration settings.json dans le dossier .vscode en y plaçant ce code :
2.
3.
4.
5.
6.
7.
{
"maven.executable.path": "C:\\Applications\\Atlassian\\atlassian-plugin-sdk-8.0.16\\apache-maven-3.5.4\\bin\\mvn",
"java.configuration.maven.userSettings": "C:\\Applications\\Atlassian\\atlassian-plugin-sdk-8.0.16\\apache-maven-3.5.4\\conf\\settings.xml"
}
Veuillez noter que le chemin peut varier selon l’emplacement de l’installation du SDK.
III. Ajouter les boutons à l’interface▲
Nous avons besoin d’ajouter le bouton « Éditer » à l’interface et la page avec les éditeurs.
Pour l’ajout du bouton, vous n’avez même pas à développer le code. Les applications Atlassian utilisent le fichier XML qui sert à spécifier les composants que l’extension comprend. Ce fichier est disponible à : src\main\resources\atlassian-plugin.xml. Il permet également de définir les classes Java que l’application va instancier.
(Veuillez noter qu’il vous faudra supprimer toutes les lignes import de votre code pour gagner de la place.)
Pour créer le bouton, il vous suffit d’ajouter les lignes suivantes :
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
<web-item key="onlyoffice-doceditor" name="Link for the attachment editing" section="system.attachment" weight="9">
<condition class="onlyoffice.IsOfficeFileAttachment">
<param name="forEdit">true</param>
</condition>
<description>The link and the text for it to open the document which is available for editing.</description>
<label key="onlyoffice.connector.editlink"/>
<link><![CDATA[/plugins/servlet/onlyoffice/doceditor?attachmentId=$attachment.id]]></link>
<styleClass>onlyoffice-doceditor</styleClass>
</web-item>
Pour de plus amples informations sur les paramètres qui figurent dans les lignes au-dessus, lisez cet article.
La plupart des paramètres sont évidents. L’attribut section sert à définir l’emplacement des liens. L’élément <condition> spécifie la classe Java qui va être utilisée pour filtrer les pièces jointes sur lesquelles nos liens seront affichés. Parmi les conditions figurent notamment l’accès des utilisateurs, la taille du fichier, l’extension du fichier. Pour mieux comprendre comment cela fonctionne, consultez le code sur GitHub.
En ce qui concerne d’autres boutons pour afficher et convertir les documents, leur création est similaire à celle du bouton « Éditer ».
Voyons de plus près l’élément <link>. Vous le reliez directement avec la servlet contenant le paramètre ID de la pièce jointe (le lien va se composer comme suit confluence/servlet/attachment_Id). La servlet elle-même va traiter les demandes des utilisateurs et ouvrir la page pour charger l’interface des éditeurs.
La servlet est la classe Java qui étend javax.servlet.http.HttpServlet et surcharge sa méthode doGet.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
public class OnlyOfficeEditorServlet extends HttpServlet {
private static final Logger log = LogManager.getLogger("onlyoffice.OnlyOfficeEditorServlet");
@Override
public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
return VelocityUtils.getRenderedTemplate("templates/editor.vm", defaults);
}
}
Vous pouvez aussi ajouter le Velocity Template : src\main\resources\templates\editor.vm.
 |
À l’intérieur de ce template, il y a le code JavaScript qui va charger la page avec les éditeurs. Pour rendre la servlet opérationnelle, il est indispensable de faire quelques ajustements dans l’application Atlassian en modifiant le fichier atlassian-plugin.xml.
 |
IV. Configuration des servlets et de l’extension▲
À cette étape, nous sommes presque prêts à ouvrir le document pour la lecture. Nous avons besoin de fournir les variables à notre page template. L’une des variables inclut l’URL qui mène vers notre Document Server, et nous ne souhaitons pas le code en dur. Heureusement, nous sommes en mesure de travailler sur les paramètres de l’extension directement dans l’interface, y compris la conception UI.
Maintenant il nous est indispensable de créer une autre servlet pour notre configuration (n’oubliez pas de l’ajouter au fichier atlassian-plugin.xml).
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
public class OnlyOfficeConfServlet extends HttpServlet {
@ComponentImport
private final UserManager userManager;
@ComponentImport
private final PluginSettingsFactory pluginSettingsFactory;
@Inject
public OnlyOfficeConfServlet(UserManager userManager, PluginSettingsFactory pluginSettingsFactory) {
this.userManager = userManager;
this.pluginSettingsFactory = pluginSettingsFactory;
}
private static final Logger log = LogManager.getLogger("onlyoffice.OnlyOfficeConfServlet");
private static final long serialVersionUID = 1L;
private String AppendSlash(String str) {
if (str == null || str.isEmpty() || str.endsWith("/"))
return str;
return str + "/";
}
private String getBody(InputStream stream) {
Scanner scanner = null;
Scanner scannerUseDelimiter = null;
try {
scanner = new Scanner(stream);
scannerUseDelimiter = scanner.useDelimiter("\\A");
return scanner.hasNext() ? scanner.next() : "";
} finally {
scannerUseDelimiter.close();
scanner.close();
}
}
}
Il y a deux méthodes utilitaires qui sont explicites. Nous avons besoin d’en ajouter encore deux.
La première est doGet. Nous prenons nos paramètres existants et les ajoutons à notre template.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
@Override
public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
String username = userManager.getRemoteUsername(request);
if (username == null || !userManager.isSystemAdmin(username)) {
SettingsManager settingsManager = (SettingsManager) ContainerManager.getComponent("settingsManager");
String baseUrl = settingsManager.getGlobalSettings().getBaseUrl();
response.sendRedirect(baseUrl);
return;
}
PluginSettings pluginSettings = pluginSettingsFactory.createGlobalSettings();
String apiUrl = (String) pluginSettings.get("onlyoffice.apiUrl");
response.setContentType("text/html;charset=UTF-8");
PrintWriter writer = response.getWriter();
Map<String, Object> contextMap = MacroUtils.defaultVelocityContext();
contextMap.put("docserviceApiUrl", apiUrl);
writer.write(getTemplate(contextMap));
}
private String getTemplate(Map<String, Object> map) throws UnsupportedEncodingException {
return VelocityUtils.getRenderedTemplate("templates/configure.vm", map);
}
La seconde méthode est doPost. Celle-l va prendre l’objet JSON, l’analyser et annuler les paramètres existants.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
@Override
public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
String username = userManager.getRemoteUsername(request);
if (username == null || !userManager.isSystemAdmin(username)) {
response.setStatus(HttpServletResponse.SC_FORBIDDEN);
return;
}
String body = getBody(request.getInputStream());
if (body.isEmpty()) {
response.setStatus(HttpServletResponse.SC_BAD_REQUEST);
return;
}
String apiUrl;
try {
JSONObject jsonObj = new JSONObject(body);
apiUrl = AppendSlash(jsonObj.getString("apiUrl"));
} catch (Exception ex) {
StringWriter sw = new StringWriter();
PrintWriter pw = new PrintWriter(sw);
ex.printStackTrace(pw);
String error = ex.toString() + "\n" + sw.toString();
log.error(error);
response.setStatus(HttpServletResponse.SC_BAD_REQUEST);
response.getWriter().write("{\"success\": false, \"message\": \"jsonparse\"}");
return;
}
PluginSettings pluginSettings = pluginSettingsFactory.createGlobalSettings();
pluginSettings.put("onlyoffice.apiUrl", apiUrl);
response.getWriter().write("{\"success\": true}");
}
Dans les deux cas, nous allons vérifier si l’utilisateur possède un accès à ces paramètres. En réalité, nous allons aussi vérifier la connexion au Document Server et dans le sens inverse pour que nous puissions identifier les problèmes qui peuvent se produire à cette étape. Le code complet est disponible ici.
Nous pouvons également ajouter les boutons « Configurer » sur la page de gestion du plugin Atlassian. Pour le faire, il suffit d’ajouter cette ligne à l’élément <plugin-info> dans le fichier atlassian-plugin.xml.
<param name="configure.url">/plugins/servlet/onlyoffice/configure</param>
N’oubliez surtout pas le Velocity template.
 |
Revenons à la servlet de l’éditeur pour la modifier.
Cela créera un objet JSON qui est indispensable pour ouvrir la page des éditeurs. Veuillez noter que nous plaçons notre objet JSON dans la variable qui se termine par AsHtml. De cette manière, le codage HTML automatique sera désactivé pour que nous le mettions dans le tag <script> au sein de notre template :
var json = '${jsonAsHtml}';
Juste pour votre information, nous avons utilisé trois classes utilitaires dont AttachmentUtil, UrlManager et DocumentManager.
Enfin et surtout, il nous reste à paramétrer la livraison des documents vers Document Server.
À cet effet, il nous faut créer encore une servlet. La seule méthode ici va assurer la disponibilité du fichier.
V. Lancement et tests▲
Cette étape consiste à nous assurer que tout fonctionne correctement et nous sommes capables d’ouvrir les documents pour la lecture.
Lancez la commande atlas-run pour créer l’extension et lancer Confluence.
Un autre moyen consiste à lancer atlas-package pour créer .jar.
Quelle que soit l’option que vous choisissiez, passez aux Paramètres -> Gérer les apps, ensuite chargez l’extension et cliquez « Configurer ». Veillez à spécifier l’adresse URL du Document Server et testez l’extension.
VI. Édition et coédition▲
Pour pouvoir ouvrir le document pour l’édition, il faut apporter quelques modifications supplémentaires.
Le paramètre callbackUrl doit s’adresser à la servlet qui va obtenir les données décrivant le statut de l’édition du document de la part du Document Server. Quand l’utilisateur ferme le document, le serveur enverra la notification que l’édition a été terminée, aussi bien que l’URL vers le document mis à jour que nous allons télécharger.
Si vous vous questionnez comment la rédaction collaborative fonctionne, suivez les consignes ci-dessous.
Les utilisateurs vont éditer le seul document tant que le paramètre clé est le même. Il y a deux aspects importants à prendre en considération lors de la génération de la clé pour un fichier :
- La clé doit être unique pour chaque document ;
- La clé doit être modifiée lorsque le document est modifié.
D’habitude, la paire ID + ModifiedDate fonctionne très bien. Cependant il y a un scénario qui n’est pas compatible avec cette combinaison. Si vous envisagez de mettre en place un enregistrement obligatoire, il vous est indispensable de générer la clé qui demeurera exactement la même durant toute la session d’édition.
La génération de la clé se fait dans AttachmentUtil et DocumentManager.
Ajoutez cette ligne dans la servlet de notre éditeur juste après la ligne
fileUrl = urlManager.GetFileUri(attachmentId); :
2.
3.
4.
5.
if (AttachmentUtil.checkAccess(attachmentId, user, true)) {
callbackUrl = urlManager.getCallbackUrl(attachmentId);
}
Passez-la à notre fonction getTemplate :
writer.write(getTemplate(apiUrl, callbackUrl, fileUrl, key, fileName, user, errorMessage));Utilisez la clé ici :
permObject.put("edit", callbackUrl != null && !callbackUrl.isEmpty());
...
editorConfigObject.put("callbackUrl", callbackUrl);Maintenant, il vous faut créer une fonction de rappel. Pour le faire, modifiez OnlyOfficeSaveFileServlet que nous avons utilisé pour livrer le document. Cela se fait facilement : nous analysons un objet JSON entrant, vérifions son statut et enregistrons le document si nécessaire. La documentation détaillée est disponible ici.
Au stade final, recompilez le projet et testez-le.
VII. Configuration des services de sécurité▲
Comment vous assurer que JSON qui a été attribué à notre servlet via la méthode POST provient de notre Document Server ? La réponse est simple : le serveur des documents utilise la méthode JWT pour accomplir cette tâche.
Nous utilisons la classe JwtManager. JWT est une méthode JSON hachée basée sur la clé secrète.
Premièrement, ajoutez les nouveaux paramètres pour notre clé secrète. Vous trouverez le code ici : configure.vm template, configuration servlet.
Ensuite, ajoutez JwtManager à la servlet de l’éditeur et placez-le avant la ligne config.put("jsonAsHtml", responseJson.toString()); :
2.
3.
4.
5.
if (jwtManager.jwtEnabled()) {
responseJson.put("token", jwtManager.createToken(responseJson));
}
Dès maintenant Document Server va considérer le service comme fiable.
Pour vous assurer de la fiabilité du Document Server, veuillez utiliser JWT lors du traitement de la fonction de rappel.
En fonction de la configuration, Document Server possède deux moyens pour passer JWT: au sein de l’en-tête HTTP ou au sein de JSON. Nous allons les examiner tous les deux.
Modifiez la servlet de la fonction de rappel en ajoutant JwtManager et placez-la juste après la ligne JSONObject jsonObj = new JSONObject(body); :
Vous avez dorénavant à votre disposition les outils de lecture et d’édition des documents protégés par la méthode JWT contre un accès indésirable et la configuration facile.
VIII. Utiliser ONLYOFFICE Docs au sein de l’environnement Confluence▲
Une fois installée et correctement paramétrée, l’application d’intégration va ajouter une nouvelle option « Éditer avec ONLYOFFICE » au menu du document pour tous les fichiers.
 |
Dès maintenant vos êtes en mesure de :
- créer de nouveaux fichiers bureautiques ou modifier des documents DOCX, XLSX, PPTX existants ;
- convertir les documents ODT, DOC, ODP, PPT, ODS, XLS aux formats Office Open XML correspondants ;
- collaborer sur les documents en temps réel en activant le mode de coédition qui vous convient le mieux (affichage des modifications en temps réel ou verrouillage d’un extrait en cours d’édition), le suivi des modifications, les commentaires, la messagerie instantanée, la comparaison des documents et l’historique des versions.
 |
Si vous souhaitez aller encore plus loin en étendant les fonctionnalités de la suite ONLYOFFICE Docs, consultez cet article pour apprendre à installer et utiliser les modules complémentaires ONLYOFFICE.
IX. Remerciements Developpez.com▲
Nous tenons à remercier Malick pour la mise au gabarit et Claude Leloup pour la relecture orthographique.