Outbound Mattermost Connection

Summary

Mattermost is an open source messaging platform that enables secure team collaboration. It competes with Slack but allows different hosting options, including self-hosting. 

JEMHCloud supports Mattermost notifications from Issue Events and Post Functions. You will be able to notify your Mattermost Channels when JEMHC detects an issue change.

Configuring the Mattermost Connection

In order to send Mattermost notifications from Issue and Post function events, you need to set up an Incoming Webhook URL in Mattermost. Once you have the Incoming Webhook URL, JEMHCloud's Matttermost connection will use that URL to send messages to the selected channel.

Configuring Mattermost's Incoming Webhook URL

For this step, we are assuming that you have a mattermost server already configured. To install Mattermost, follow Mattermost's gettings starting guide.

  1. Log into your Mattermost instance. 

  2. Click on Integrations > Incoming Webhook

  3. Create a new Incoming Webhook and select the channel target of JEMHCloud Mattermost notifications.

  4. Copy the URL. You will use this URL when creating the a Mattermost Connection

Note: The author of the message will the user that created the Incoming Webhook. If you want a different more generic name, you would need to create the incoming webhook when logged in as a different bot user (for example Jira or JEMHC)

Creating JEMHCloud’s Mattermost Connection

  1. Go to JEMHCloud > Messages > Mattermost Connections

  2. Click on Create button.

  3. Once in the Mattermost Connection form, enter a name and paste the Incoming Webhook URL copied from Mattermost's Integrations page.

  4. Submit. If the configuration is ok, you should see a test message in Mattermost's channel

     

Send Mattermost notifications from issue events

Like Email Notification Mappings, the Mattermost Notification Mapping is in charge of sending Mattermost messages from Issue events through the Mattermost Connection. This will allow you to select the Projects, templates and the Mattermost connection to use.

Like Email and SMS Notification Mapping, Mattermost Notification Mapping is in charge of sending Mattermost messages from Issue events through the Mattermost Connection.

Creating a Mattermost Notification Mapping:

  1. Go to JEMH Cloud > Notifications > Mattermost > Create

  2. Complete the form, select the nominated projects and select the Mattermost Connection. Enter a velocity script if you want to modify the notification behaviour at runtime (more below).

  3. On Submit, you should see the new Mattermost mapping

  4. To test the mapping, create an issue in the nominated project and go to Auditing > Events

  5. You should see the issue created event in the queue. When the event has been processed, the configured channel in the mapping should have received a Mattermost message.

Sending Mattermost Notifications from Post Functions

JEMHCloud allows you to send Mattermost notifications when Issue transitions are performed through JIRA Post Functions.

Adding the Mattermost Notification Post Function to workflow transition:

  1. Go to right corner Cog > JIRA Administration > Issue > Workflows. Edit the workflow of the project you want to add the Post Function

  2. Click on the transition you want to change and select the Post Functions tab. Click on Add post function

  3. Select Send Mattermost Notification by JEMHCloud and click Add

  4. Select the Mattermost Connection, template set and add a Velocity script if necessary. Press Add

  5. Once the Post Function is in the right position, publish the workflow draft.

  6. To test the post function, go to an issue of the given workflow and perform the transition that will fire the post function.

  7. The Post function event should appear in JEMH Cloud > Notifications > Events.

 

Example Filter Scripts

Both Mattermost Notification Mapping and Mattermost Post Function behavior can be changed at runtime with a Velocity Script. The script can use the event data or be time-based to change how notifications are performed.

Change Channel

Change channel when Critical

#if ($context.issue.fields.priority.name.textValue() != 'Critical') $mattermostNotificationUtils.setIncomingWebhookUrl('https://mattermost-thepluginpeople.ngrok.io/hooks/someOtherURL') ## JEMHC to send the message to a incoming webhook / channel defined at runtime #end

Restrict notifications to specific time ranges

Notify only after hours

#if (!$dateTimeUtils.betweenHours("18:00", "06:00")) $mattermostNotificationUtils.inhibitNotification() ## mattermost messages are not sent during business hours ** #end

Restrict by priority

#if ($context.issue.fields.priority.name.textValue() != 'Blocker') $mattermostNotificationUtils.inhibitNotification() #end

 

Velocity Script cannot be validated at configuration time (for example the dynamic incoming webhook URL). You should test the script by re-executing events in Auditing → Events

Related Articles