Outbound SMS (Short Message Service) Transport

Owned by Ryan Clifton
Last updated: Apr 06, 2023
4 min read

Summary

The SMS transport is used for notifying users of JIRA events through SMS.

The current supported SMS gateway providers are:

For each provider the requirement parameters are different.  Below is a table of the supported providers and the required parameters for successful configuration.  More information on these parameters can be found in the respective providers documentation.

SMS Provider

Required Parameters

Documentation Reference

SMS Provider

Required Parameters

Documentation Reference

Twilio

  • to

  • from

  • accountsid

  • authToken

https://www.twilio.com/docs/api/rest/sending-messages

BulkSMS

  • username

  • password

  • msisdn

http://developer.bulksms.com/eapi/submission/send_sms/

Nexmo

  • api_key

  • api_secret

  • from

  • to

https://docs.nexmo.com/messaging/sms-api/api-reference

Clockwork

  • key

  • to

Each provider charge differently, please refer to their FAQ and pricing policies.

Configuring the SMS transport

In order to send SMS notifications from Issue and Post function events, you need to set up a SMS transport first. The transport is the connection that knows how to send SMS messages through a SMS provider.

To create a SMS transport:

  1. Create an account in one of the providers. The provider will give you the access token and credentials necessary JEMHCloud will require to send messages

  2. Go to JEMH Cloud > SMS Transports > Create

  3. Enter a name, the provider and the required fields according to the provider. This example uses Twilio. (Twilio requires a registered From Phone Number you can select in JEMHC after it has been created in the Twilio console)

  4. When submit, JEMHC tests the configuration by sending a SMS test message to Test To Phone Number

  5. The new SMS Transport on the screen.

     

Send SMS notifications from issue events

Like Email Notification Mappings, the SMS notification mapping is in charge of sending SMS messages from Issue events through the SMS Transport. For more info about SMS notification mappings see:

Creating an SMS Notification Mapping:

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

  2. Complete the form, select the nominated projects, select the SMS transport you want to use and the phone numbers (CSV) that will receive SMS message. Enter a velocity script if you want to modify the notification behaviour at runtime (more below).

  3. On Submit, you should see the new SMS 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 event has been processed, the configured phone numbers in the mapping should have received an SMS message.

  6. The report of the event should confirm the message sent 

  7. In Auditing → Outbound Messages, the table should show the SMS messages sent and the cog icon should show their contents.

     

 

Send SMS Notifications from Post Functions

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

Adding the SMS 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 SMS Notification by JEMHCloud and click Add

  4. Set the SMS Transport, to phone numbers (CSV) and Velocity script if necessary. Press Add

  5. Move the Post Function to last position and publish the workflow draft.

  6. Remember to publish the workflow change draft! 

  7. To test the post function, go to an issue and perform the transition.

  8. Post function event should appear in JEMH Cloud > Auditing > Events.

  9. The event report:

Example Velocity Scripts

SMS notification behaviour can be changed at runtime with a user-defined Velocity Script. The script can use the event data or be time based to change how notifications are performed.

Reset/Add Phone Numbers

Change to phone number when Critical

#if ($context.issue.fields.priority.name.textValue() != 'Critical') ## if issue priority is critical   $smsNotificationUtils.resetToPhoneNumbers() ## remove existing phone numbers for current notification   $smsNotificationUtils.addToPhoneNumber("+1234567") ## add phone number to current notification #end

Restrict notifications to specific time ranges

Notify only after hours

#if (!$dateTimeUtils.betweenHours("18:00", "06:00")) ## during specific hours    $smsNotificationUtils.inhibitNotification() ## prevent current SMS notification #end

Restrict by priority

#if ($context.issue.fields.priority.name.textValue() != 'Blocker') ## if issue priority is not a blocker $smsNotificationUtils.inhibitNotification() ## prevent current SMS notification #end

Velocity Script cannot be validated at configuration time (for example the dynamic phone numbers). You should test the script by re-executing events in Auditing > Events