Matrix Requirements has long provided a Slack integration which allows for notifications on changes and link expansion. While the functionality is great it requires manual setup work. To make the setup procedure simpler we now provide a Slack App in the Slack Marketplace which will become available with the next release of Matrix Requirements.
Once installed, log in as an administrator in the Administration Client. Navigate to the Extensions section and activate the Slack App Plugin. Make sure you have selected the correct impersonation user (see below) and then press the Add to Slack button. This will take you to the Slack OAuth webpages where you have to select the Slack Team to link to (if you have multiple) and the default channel for the App to post to.
Approve the App permissions and you will be taken back to your Matrix instance. The button should now be replaced with an "Uninstall Slack App" button. You can always disable the integration by pressing this button.
With the App installed in Slack you can now get notifications from Matrix inside Slack. There are two functions you can use:
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 is edited.
To get a list of all matrix commands simply run:
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:
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 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.