Integration for Slack
The application for Slack allows you to integrate Matrix with Slack in a simple, easy way.
Installation
Once the application for Slack is enabled in the Extension settings you can press the "Add to Slack" button. This will walk you through the OAuth windows of Slack where you can select the Slack instance to connect to (if you have multiple) and confirm the required permissions for the integration for Slack.
In addition to installing the application for Slack you also have to choose the impersonation user. For more details see below.
With the App installed in Slack you can now get notifications from Matrix inside the application for Slack. There are two functions you can use:
- Change notifications
- Link detection (unfurling)
Change notifications
Matrix provides notifications on different change events on the server, for example when items are edited, created or when signatures are requested. Each channel in Slack can have a different set of subscriptions so that you can set up dedicated channels for specific Matrix projects.
To subscribe to a notification, enter the channel in Slack and run the subscription command. For example to subscribe to any change on Procedure items in the QMS project:
/matrix subscribe item_edited QMS PROC
This will now post a message in the channel every time a Procedure in the QMS project is edited.
To get a list of all Matrix commands simply run:
/matrix help
Link Detection
The application for Slack can recognize references to Matrix items in your conversations and respond with basic information about them and a clickable link to take you directly to the item. You can set this up in two ways:
/matrix subscribe refer
In this mode Matrix will look for combinations of project ID and item ID. For example:
- "Look at QMS/PROC-2" - in this case it will link to PROC-2 in the QMS projects
- "Look at PROC-3" - in this case it will not link because it is missing the leading project ID
/matrix subscribe mention QMS
With the "mention" subscription, Matrix will remember the project (QMS in this case) and assume that any ID without a project prefix is part of the selected project:
- "Look at PROC-2" - it will link to PROC-2 in the QMS project
- "Look at QMS/PROC-3" - this will be ignored by the "mention" subscription, but if you have a "refer" subscription then it will be handled by that.
Detecting links requires the Matrix application for Slack to "read" all of the messages in the channel. Since you might not want this on all channels you will have to invite the Matrix Bot to join the channel before this will work. You can do this by typing:
/invite @matrix
Once invited the Matrix Bot will also automatically enable the refer subscription, so IDs in the form QMS/PROC-1 will already work. Just like notifications you can enable or disable them using the subscription and list commands.
User Impersonation
User Impersonation is the mechanism by which MatrixALM decides what users on Slack should be able to see. Since Channels on Slack are shared between multiple users and Matrix does not know which users will see the information about items linked to or displayed in Slack you need to make sure that you run the application for Slack with a limited set of read permissions.
For example if you set up the application for Slack to receive notifications for all changes on items in a project there might be a certain set of items that you do not want all users to see. In this case you can create a special user called "Slack" with limited visibility on the project. Once configured you can log into the project with this user to make sure he has the visibility that works for your project structure. As a general rule start with the most restrictive visibility and extend as needed.
Once you're satisfied with the visibility of the user in Slack, go into the Administration and assign this user as the Impersonation User in the application for Slack settings. Once set every link expansion or notification will only work on items that the user in Slack can actually see. Notifications for items that are not readable for the user in Slack will be ignored and links will not be expanded in the channels for Slack.