Gérer les intégrations

Par intégration, on entend les interactions entre Mattermost et d’autres applications.

Deux fonctionnalités méconnues de Mattermost sont la création de hooks entrants et de commandes slash.

• Un hook entrant (abrévié hook par la suite) est une URL spéciale qui permet de poster un message sur un canal particulier lorsque l’URL est requêtée.
• Une commande slash (abrévié commande par la suite) est un mot clé précédé d’un symbole / qui déclenche l’appel à une URL externe et remplace le commande par la réponse de l’URL.

Les commandes sont à différencier des commandes de plugin (comme /spoiler), qui ne requêtent pas nécessairement une URL extérieure.

Pour résumer, les hooks permettent d’être informés d’un événement, les commandes permettent de déclencher un événement ou de générer des informations dynamiques.

Les hooks et les commandes sont circonscrits à une seule équipe. Une commande mise en place sur une équipe ne fonctionnera que sur cette équipe.

Les administrateurs d’équipes sont les seules personnes à pouvoir gérer les hooks et commandes. Ceci étant, c’est très pratique car il n’y a pas besoin d’un administrateur système pour créer ses propres commandes/hooks.

La personne qui crée une équipe en est automatiquement administrateur, et peut ensuite étendre ce rôle aux autres membres depuis la gestion des membres de l’équipe. La plupart des personnes ne sont pas au courant de ce rôle, il ne faut pas hésiter à leur signaler si ça peut être utile. :)

La gestion des intégrations se fait depuis l’URL suivante, construite à partir du nom de l’équipe :

https://team.picasoft.net/<equipe>/integrations

Depuis les intégrations, ajouter un nouveau hook entrant. Voici un exemple de paramétrage :

Avec cette configuration, quiconque possède le lien du hook pourra poster dans le canal Tests, avec le nom d’utilisateur webhook et la photo de profil accessible à l’URL donnée.

Une URL confidentielle est générée suite à l’enregistrement du hook.

Cette URL peut maintenant être utilisée par une application compatible Slack ou Mattermost. Mais elle peut aussi être utilisée “à la main” ou dans un script personnalisé.

Pour ce faire, il suffit d’effectuer une requête POST sur l’URL, avec pour corps de la requête un objet JSON contenant a minima un champ text dont la valeur est le corps du message à poster sur le canal.

En reprenant l’exemple précédent, la commande suivante postera un message sur le canal Tests :

snippet.bash

$ curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "## Message formaté !!\nAvec retour à la ligne et mention @quentinduchemin :relaxed:"}' https://team.picasoft.net/hooks/sxdkzr7gotystkj5gmdmqt9ofy

Le message est en effet reçu, le formatage Markdown est interprété et les mentions envoient des notifications aux personnes concernées.

Côté console, on reçoit un 200 OK pour indiquer que tout s’est bien passé.

L’idée est de montrer le fonctionnement basique d’une commande.

On se rend dans les intégrations, onglet commandes slash, et on crée une commande, par exemple :

Les paramètres sont similaires au webhook entrant. En revanche, deux choix sont importants :

• L’URL qui sera appelée lors du déclenchement de la commande,
• La méthode (GET ou POST).

Le reste est de la responsabilité du serveur, qui reçoit toutes les informations de la commande et formate une réponse.

Dans tous les cas, le serveur distant doit répondre avec un objet JSON qui contient au moins l’attribut text, valeur du message à écrire en réponse à la commande.

Voici un exemple simplissime qui répond à toutes les requêtes POST en ajoutant dans la réponse les paramètres passés à la commande :

snippet.python

from flask import Flask, request
 
app = Flask(__name__)
 
 
@app.route('/', methods=['POST'])
def result():
    return {
        "text": f"## Commande reçue!\nPayload : {request.form['text']}"
    }

Pour le tester, il suffit de l’enregistrer (par exemple simple_server.py), puis de lancer :

snippet.bash

$ pip install flask
$ FLASK_APP=simple_server.py flask run -h 0.0.0.0

L’application est accessible à l’URL de votre serveur sur le port 5000.

Pour tester, il suffit de déclencher la commande dans n’importe quel canal de l’équipe :

/test_commande Voici les paramètres!

La commande est envoyée, et Mattermost affiche en réponse :

Les commandes et les hooks sont très puissants. Dans leur forme basique, ils permettent de poster un message en réponse à un événement extérieur ou une commande depuis Mattermost.

En plus des exemples basiques vus ici (seul l’attribut text de la réponse est utilisé), il existe des options avancées de formatage, de redirection, de réponse délayée, de remplacement du nom d’utilisateur, etc.

Ces paramètres sont traités dans la documentation officielle.