NEW!!! Flexibility & configurability to the next level with the latest version of Matrix. Learn more!

What you can do with our new integration for Slack!

Matrix Requirements has long provided a manual integration for Slack which offers notifications on changes and link expansion. To make the setup procedure simpler we now provide an integration for Slack in the Marketplace which will be available with the next release of Matrix Requirements.

To use, log in as an administrator in the Administration Client. Navigate to the Extensions section and activate the plugin for Slack. 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 web pages where you have to select the Team in Slack 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 of the application for Slack. There are two functions you can use:

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 the application for 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 the application for 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:

/matrix help

Link detection

The application 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 integration 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 in the application should be able to see. Since channels are shared between multiple users Matrix does not know which users will see the information about items linked to or displayed in the application. 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 it 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 settings for Slack. Once set every link expansion or notification will only work on items that the 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 channels

About the Author
Adam Newman
Head of Marketing