Short Message Service (SMS) Transport

Owned by Fernando Boucquez (PPL) (Deactivated)
Last updated: Apr 05, 2023 by Ryan Clifton
7 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

https://www.clockworksms.com/doc/easy-stuff/http-interface/send-sms/

 

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.

Once you have the transport created, you can set SMS Notification Mappings to send SMS notifications from Issue Created/Updated/Deleted events or SMS Post Functions to send SMS notifications from transition events.

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.

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 wan to to modify the notification behavior 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/Update

  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 → Notifications → Events.

  9. The event report:

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

     

Scripting

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

Issue Updated SMS notifications

SMS messages are limited (in size and pricing) so JEMHC may not notify issue updates out of the box. Also you wouldn't want to spam your SMS users for every change in an issue. You can confirm that an issue updated event has been ignored (no SMS) if you see the line SMS message to phone numbers '+555123456' has not been sent as no useful information was displayed in the events report (Auditing → Events → Cog Icon → Report).

In order to send SMS messages from issue update, you would need to create a custom template containing the logic around which fields and in which conditions the SMS message must be sent. An example:

Send SMS notifications if the issue priority has been changed to Blocker.

In this example, the interested field is Priority and the condition is new value=Blocker. These are the steps to create and set an SMS Issue Updated template:

  1. Create a new Template by going to Notifications → Templates → Create 

  2. Set the name (Priority Update Template), select SMS theme, Issue Updated Template Type and copy from System Default Issue Updated Template

  3. In the edit screen enter the script you can find below

  4.  

    Priority Update SMS template

     

  5. Go to Notifications → Notification Mappings → SMS → Edit → and change the Issue Updated template for the new template (Priority Update SMS template) and save. 

  6. If you change an issue priority of one of your issue to Blocker, the new template will print the priority in the message and notify JEMHC that the message has valid information (via the $jemhUtils.setFieldRendered() command).  JEMHC will now send the SMS to the handler's phone number. 

  7. You can confirm that the SMS has been sent by going to Auditing → Events→ Cog→ View Report




You can add more fields and values by updating the template. For example the script:

Will send an SMS if the issue priority has been changed to 'Blocker' or 'Highest' or if the issue status has also been changed.

Please note that the new lines are missing in the script so the SMS message doesn't have them.

 

Related articles