Setting Up Enterprise SMS for Incident Messaging
The tutorial describes the approach for Incident SMS messaging through ServiceNow Vancouver Platform and how you can set up the Retarus Enterprise SMS REST API.
Prerequisites
Retarus Enterprise SMS Account and Credentials
Retarus Enterprise SMS documentation
Retarus provides assistance in challenges relating to the REST API Integration in ServiceNow. What Trigger Events and Business Rules lead to a call of the Retarus SMS API is to be defined/set up by the ServiceNow customer integrator. Retarus does not modify customers' ServiceNow environments.
Approach
An example ServiceNow incidents page listing previously reported incidents is shown below:
A new incident can be specified. Parameters like incident number are created by the ServiceNow system itself, other parameters like Caller, Urgency, or Short Description are typically modified by the reporting staff.
The business rule defines what shall happen in case an incident is created. As shown below, in this case the SMS event shall be triggered in case a new incident is created (see picture below: When to run: "Insert" checkbox). Additionally, the rule has to be set active and advanced rules is allowed.
Advanced rules are necessary for allowing an extended set up commands in the business rule like code-based calls to external APIs with message personalization as shown in this tutorial.
Checkbox Tab: “When to run”
In this tutorial, the sn_ws-RESTMessageV2 ServiceNow library is used to set up the REST call to the Retarus REST API SMS environment. Below code calls a HTTP POST 'RESTSMS'→'RESTSMSPOST' defined in ServiceNow→ System Web Services→ Outbound → RestMessages (Step 3: Connect Retarus SMS through REST API Integration)
In this code snippet, in addition to the HTTP Post structure to select, the following parameterizations shall be enabled:
Personalization of the SMS with the Incident Number
Personalization of the SMS with the Priority/Urgency of the request
Personalization of the SMS with a short description of the ToDos for the recipient
Error/Status handling variables ("response.getBody", "response.getStatusCode", "response.getErrormessage")
The status can be used to e.g. set up a monitoring page within ServiceNow as Retarus provides the jobID for every SMS job sent back to ServiceNow.
The REST Service can be set up in ServiceNow→ System Web Services→ Outbound → RestMessages.
As shown in the screenshot below, for the setup of the integration the following points should be considered:
Retarus SMS endpoint to contact for the REST API SMS calls
Authorization data provided by Retarus in the HTTP Headers settings
Structure of the HTTP Query including the personalization parameters defined via ${...} syntax in the ServiceNow environment (read the Retarus REST API Manual or contact your Retarus technical consultant for defining your suitable parameterization/needs)
