Source de données : Slack

1Présentation

Slack est un service de communication collaborative, qui permet d'échanger entre utilisateurs, soit au travers de communications ad-hoc, soit au sein de canaux de communication.

Il est possible d'envoyer des messages dans un canal de communication, pour notifier les utilisateurs de manière automatisée.

Si vous avez correctement configuré les paramètres de connexion au service Slack, Temma crée automatiquement un objet de type \Temma\Datasources\Slack, avec lequel vous pourrez envoyer des notifications. Par convention, nous partirons du principe que vous avez nommé cette connexion slack dans le fichier etc/temma.php (voir la documentation de la configuration).

Dans les contrôleurs, la connexion à Slack est alors disponible en écrivant : 

$this->slack

Dans les autres objets gérés par le le composant d'injection de dépendances, la connexion à Slack est accessible en écrivant : 

$this->_loader->dataSources['slack']

2Configuration

Pour envoyer des notifications sur Slack, vous devez d'abord installer dans votre organisation Slack l'application Incoming Webhook (application officielle conçue par Slack), puis récupérer l'URL Incoming Webhook fournie.

Dans le fichier etc/temma.php (voir la documentation de la configuration), vous pourrez alors déclarer le DSN (Data Source Name) qui permet de se connecter à Slack.

Le DSN de connexion à Slack peut s'écrire de plusieurs formes :

  • slack://WEBHOOK
  • slack://AUTEUR@WEBHOOK
  • slack://AUTEUR:ICONE@WEBHOOK

Avec :

  • WEBHOOK la valeur de l'URL Incoming Webhook récupérée, sans le préfixe https://.
    Exemple : hooks.slack.com/services/TXXXXXXXX/BYYYYYYYY/ZZZZZZZZZZZZZZZZZZZZZZZZ
  • AUTEUR le nom à afficher comme expéditeur de la notification.
  • ICONE l'URL vers l'image à utiliser comme avatar par l'expéditeur de la notification.
    Exemple : https%3A%2F%2Fsite.com%2Fchemin%2Fvers%2Ficone.png

3Contenu des notifications

Les notifications peuvent contenir du texte, qui accepte un dérivé de la syntaxe Markdown.

Les notifications peuvent aussi accueillir des "pièces-jointes", c'est-à-dire des blocs qui peuvent eux-mêmes contenir du texte, une image, un texte de "pied-de-page", un texte qui se positionne au-dessus du bloc, ainsi qu'un nom d'auteur, qui peut être un lien cliquable et/ou comporter une image d'avatar.

4Appels unifiés

4.1Accès de type tableau

// envoie une notification simple
$this->slack['CHANNEL'] = "Message à envoyer";
// avec CHANNEL qui correspond au nom du canal vers lequel
// envoyer le message (avec le dièse au début)

// envoie une notification formatée
$this->slack['CHANNEL'] = [
    'text'        => 'Texte de la notification, avec <https://temma.net|un lien>',
    'attachments' => [
        [
            'pretext' => 'Texte au-dessus du bloc',
            'author'  => "Nom de l'auteur du bloc",
            'icon'    => "URL de l'icone de l'auteur du bloc",
            'link'    => "URL du lien sur le nom de l'auteur",
            'text'    => '*gras* _italique_ ~barré~ `code`',
            'image'   => 'https://site.com/chemin/vers/image.jpg',
            'footer'  => 'Texte de pied de page du bloc',
        ],
        'Bloc textuel',
        'Un autre bloc uniquement textuel',
        [
            'image' => 'https://site.com/chemin/vers/image2.jpg',
        ],
    ],
];

4.2Méthode avancée

// envoie une notification simple
$this->slack->set('CHANNEL', "Message à envoyer");

// envoie une notifications formatée
$this->slack->set('CHANNEL', [
    'text'        => 'Texte principal',
    'attachments' => [
        'Premier bloc',
        'Deuxième bloc',
    ],
]);

// envoie une notification, en spécifiant le nom de l'auteur et son icone
$this->slack->set('CHANNEL', "Message", [
    'author' => "Nom de l'auteur",
    'icon'   => "https://site.com/chemin/vers/icon.png",
]);

5Appels spécifiques

5.1setAuthor()

// définition du nom de l'auteur et de son icone,
// qui seront utilisés pour tous les envois ultérieurs
$this->slack->setAuthor("Nom de l'auteur", 'https://site.com/chemin/vers/icone.png');