Overview

The slack integration consists of two things a Slack Bot which needs to be configured in Slack and Slack module in Matrix which handles our side of the communication.

Once the Slack bot has been created it needs to be linked to Matrix using the Matrix Administration client.

Once the two are connected, you can configure the messages exchanged between the two using Slack commands.

Enable Slack in Matrix

The first step is to enable slack in Matrix: this is done in the main Extensions menu of Matrix admin:

Then click on the extended plugin settings and enter this:

{"temp":"temp"}

Creating a Matrix Bot for Slack

Go to https://api.slack.com/
If needed login
In the top right: click "Your Apps"
Click "Create App", fill the form
Create a Bot (click Bots)
Add a Bot User
Fill the form
Click on OAuth and Permissions
Click Install App to Workspace
Authorize this ....
Scroll Down To Scopes
Add chat.write.bot
Add channels.write and click on Save Changes
Go to top and reinstall the App
Back to slack app configuration: Click left on "Event Subscriptions" and
Enable Events
and than set up the connection with matrix
Note: these settings define how text entered in slack is pushed to matrix to do clever stuff (like recognizing matrix item ids)
1. Add your webhook url
  the url is https://YOUR_MATRIX_DOMAIN.matrixreq.com/rest/1/all/webhook/501
  slack will check the URL and you should see a Verified behind Request URL
2. Add a Workspace Event: Select the message.channels event
3. save and reinstall the app as requested
Create new slash command called /matrix
1. as url use the same as above: https://YOUR_MATRIX_DOMAIN.matrixreq.com/rest/1/all/webhook/501
2. save and reinstall the app as requested

Linking the Slack Bot to Matrix

Copy the OAuth Access Token to Matrix
1. click on Copy behind the OAuth Access Token
In the Matrix administration client go to the Extension folder YOURDOMAIN.matrixreq.com/adminConfig/extensions
1. add https://slack.com/api as end point for slack
2. add the token to the matrix config page
3. create a read only Matrix user which has read access to all relevant projects, and add it under user impersonation. Make sure to activate the user through the email sent during creation.
  
  Note: this settings defines the push connection from Matrix to slack.

Improving security

To avoid some unwilling access to Matrix through the Slack plugin, we strongly suggest you add the following steps:

In Slack you take a copy of the Signing Secret below:

Then add this into the extended plugin settings:

As soon as you add this slackSigningSecret field in the extended settings json, all requests from Slack to Matrix will be verified against their signature through a HMAC-SHA256 keyed hash as explained here in the Slack documentation:

https://api.slack.com/docs/verifying-requests-from-slack

Configure what to listen to and how to respond

Invite MatrixBot / private Slack channels

In order for the MatrixBot to listen to messages in private channels, you need to explicitly invite the MatrixApp to these channels.

Note: this does not seem to work consistently on the slack side... so it's not recommended to use private slack channels

/invite MatrixApp

Configure Events and Messages

Note: here we define in which slack channels, matrix should listen in and what should be done if Matrix ids are recognized

select a slack channel you want to hook up to the matrix bot
type /matrix help
Note: this will print all commands understood by the matrix bot
to subscribe to messages use the following command
Subscribe Syntax
```
/matrix subscribe PROJECT CATEGORIES ACTION TEMPLATE(optional)
```
1. PROJECT is the id of a project
2. CATEGORIES can be * for all categories, to a comma separated list of categories, e.g. REQ,SPEC
3. ACTION is either
  1. refer: to indicate that if you type PROJECT/ITEM-ID the matrix bot should display a hperlink and the item's title (or whatever specified in the TEMPLATE parameter)
  2. mention: is the same as a refer, but the PROJECT is implicit, so it does not need to be typed. Note: there can only one mention per channel
  3. item_edited: to receive a message if the item (in the specified project/category) was changed in matrix
  4. item_created: item was created
  5. item_deleted: item was deleted
  6. sign_created: a SIGN item was created from a DOC
  7. sign_signed_partial: someone signed an item
  8. sign_signed_full: the last person signed an item
  9. publish: the QMS was published
4. TEMPLATE, is optional and defines what information is send to slack and how it is formatted. In these messages you can put in macros which will be replaced by the actual values. The following macros exist
  1. $link$: is replaced with a hyperlink to the project including and title e.g. MYPROJECT/REQ-12 requirement title
  2. $author$: is replaced with the last author
  3. $date$: the last modification date (in server timezone/setting)
  4. $creator$: is replaced with the person who created the item
  5. $comment$: with the last comment
  6. $changes$: a list of changed fields, needs the repeat flag (see below)
  7. $signatures$": a list of all signatures of a SIGN, needs the repeat flag (see below)
    
    The template can be a simple text, like {text:"$link$ $title$ by $author$"} or a it can be a slack message with attachments. Note: When part of an attachment it needs a repeat clause to be filled.
    See also syntax documented by slack for information on how to format these messages.

Examples

HOOK_ITEM_EDITED: 
	{text:"Item edited: $link$ $title$", attachments:[ {text:"Changes by $author$","repeat":"author"},{text:"$changes$","repeat":"changes"}]}
HOOK_ITEM_DELETED:
	{text:"Item deleted: $link$"}
HOOK_SIGN_CREATED:
	{text:"Sign item created: $link$ $title$", attachments:[ {text:"Created by $creator$",repeat:\"creator\"},{text:"$signatures$",repeat:"signatures"}]}
HOOK_SIGN_SIGNED_PARTIAL:
	{text:"Partial signature: $link$ $title$", attachments:[ {text:"Created by $creator$",repeat:\"creator\"},{text:"$signatures$",repeat:"signatures"}]}
HOOK_SIGN_SIGNED_FULL:
	{text:"Completed signature: $link$ $title$", attachments:[ {text:"Created by $creator$",repeat:\"creator\"},{text:"$signatures$",repeat:"signatures"}]}

Automation - Slack Integration