Slack Integration

The Slack App allows you to integrate Matrix with Slack in a simple, easy way.

Installation

Once the Slack App 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 permissions the Slack integration requires.

In addition to installing the Slack app 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 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 Slack 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 Slack App 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. This runs in two modes: With Project ID, called refer, and without, called mention. For the latter you will have to explicitly specify the project to use when subscribing to it.

Detecting links requires the Matrix Slack App 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 Slack App with a limited set of read permissions.

For example if you set up the Slack App 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 Slack user, go into the Administration and assign this user as the Impersonation User in the Slack App settings. Once set every link expansion or notification will only work on items that the Slack user can actually see. Notifications for items that are not readable for the Slack user will be ignored and links will not be expanded in the Slack channels.