Interactive SMS

Overview

This document describes a new process for delivering Short Message Service (SMS) data from SBN to a 3^rd party, allowing confirmations of sent SMS back into SBN, and disposing of an incident via SMS.

General Process:

1. Records are added to the SMS queue table fe_sms either via Algen or explicitly by an operator via the SBN Dispatch screen.
2. 3rd party (provided by the client) uses API3 calls to process the records. The API3 call process includes:

a.   Get pending records from the table.

b.   Indicate that an SMS was sent.

c.   Dispose of an incident.

Note:  A third-party SMS provider is required to the deliver the SMS to the endpoint.

Note: SBN provides all of the necessary data elements (first name, phone, etc.) and a message type indicator (integer) but does not build the text message.  A third-party SMS provider is required to build the message according to the message type.

Options

This feature requires SBN option fe046 to be on. The option is off by default. When turned on, any file referencing this option must be recompiled. Turning this option on allows SBN records to be added to the SMS queue. When the option is turned off SMS records will never be added to the SMS queue.

GUI Messages

Several IBS and GUI messages are required for this feature. Clients must ensure that the UNIX command ‘install_msg’ was executed after this patch was delivered.

Interactive SMS Message Definitions (2510)

Interactive SMS currently works with 11 messages (numbered 0-10).  Every message number serves one explicit purpose.  The number and purpose of each message did not change from the original implementation.  Each suite of messages is for one Dealer and Zone Type.  If you want to support another Dealer and Zone Type combination you need another set of 11 messages.

In the above image you see two sets of messages; One for Dealer 0000, Zone Type AL, and the other for Dealer 0000, Zone Type CLO.

To facilitate keeping a complete message suite (all 11 messages):

• New – You pick the Dealer and Zone Type you want to create and all 11 messages are created for you.
• Change – You may only change the message.
• Delete – Deletes the entire message suite for a Dealer and Zone Type.
• Copy  – Copies all messages (including data in the Zoom tabs) from one Dealer and Zone Type to another Dealer and Zone Type.

Note the common thread in all of this..the 11 messages all stay together, as a unit, for every Dealer and Zone Type combination.

Why is CLO red in the above screenshot? 

Both Zone Types and Dealer Id programs have a checkbox “Allow SMS”.  If you define a suite of messages against a Dealer, or a Zone Type, with the Allow SMS checkbox unchecked then that suite of messages will appear red. This is easily identify messages that will not be processed.

Note: This only covers Dealers and Zone Types.  There are other qualifications related to the actual Installation/Incident to consider. Additional criteria is covered in section Find SMS Recipients.

Search Button

This refreshes the grid and filters by the Dealer and Zone Type fields at the top of form.

Test Button

This allows you to enter some values to see which message the system will use.  It had more use in my first itteration of the form.  It does not have much use now.

Building Messages

Messages (the box boxes) in 2510 accept variables (aka: placeholders).  This is the same concept used by MONPAG and many other enhancements.

Any result set column returned by API3 proc g_sms is valid.

Use APIEngine to execute g_sms and view the resultset.

Here is an example:

Using result set column alid as an example the message variable placeholder would look like this:

The variable must start with {$ and end with }.

Zoom Tab

Translations

This translates the top-level messages.  All records here are detail (aka: linked) to whatever is selected the top-level message.

Operator SMS

These messages are tied to the selected top-level (top grid) Dealer.  These are used in Dispatch and covered more in section Dispatch Operator SMS.

Multi-Lines

Messages can be a maximum of 500 characters and can span multiple lines.  Use Ctrl-Enter to move to the next line.  If you just use Enter the record will be saved.

Find SMS Recipients

This section explains how SBN determines which contacts should receive an SMS, and how this data translates into outbound SMS records.

This decision making happens when an alarm is generated through Algen (SBN’s Alarm Generation process). 

The following conditions must be met in order to create an Outbound SMS record:

1. Signal Zone Type must Allow SMS
2. Monitoring Dealer must Allow SMS
3. Subscriber Type must Allow SMS
4. Installation must not OPT OUT
5. Installation Action Plan Contact(s) must have a phone number with the “correct” phone type.

Zone Types (1733)

The Zone Type associated with the Incident must be specified to be included in the SMS process. 

SBN allow the user to check the Allow SMS checkbox for each individual Zone Type. If the box is checked, when a signal is received SBN will search for a qualifying match. The default for this new field is Off/Unchecked meaning that every Zone Type is not enrolled in SMS.

Dealer Profiles (1537)

The Monitoring Dealer associated with the Installation must be specified to be included in the SMS process. A new checkbox (Allow SMS) was added in SBN’s Program# 1537. 

The default for this new field is Off/Unchecked meaning that every Monitoring Delaer is not enrolled in SMS. SBN allow the user to check the Allow SMS checkbox for each individual dealer. If the box is checked, when a signal is received SBN will search for a qualifying match.

Subscriber Types (1534)

The Subscriber Type associated with the Installation must be specified to be included in the SMS process. A new checkbox (Allow SMS) was added in SBN’s Program# 1534.

The default for this new field is Off/Unchecked meaning that every Subscriber Type is not enrolled in SMS. SBN allow the user to check the Allow SMS checkbox for each individual subscriber. If the box is checked, when a signal is received SBN will search for a qualifying match.

Installation (559) 

A checkbox has been added in SBN’s Program# 559 in the CS Basics tab. The default for this new field is Off/Unchecked meaning that every installation is automatically enrolled in SMS. The user must check the box to Opt-Out of the SMS process.

Action Plan Contacts (559)

The Action Plan Contacts associated with the Incident must have contacts, and those contacts must have a phone number in any of slots Phone1, Phone2, or Phone3 (or any combination of these three slots). Each phone number that meets the following conditions will result in an SMS record to be processed. 

Note: SBN allows for phone numbers to be stored in various places depending on the customer’s setup. For this integration phone numbers and phone types are located in table contper.

1.1   Phone number(s), with all formatting removed, must not meet any formatting exclusions.

1.2   The phone number must have an associated Phone Type. (On the Call List zoom into the Contact screen to see the Phone Type.)

1.3   The Phone Type as entered in 1840 must match the value in option fe052.

Meeting all conditions results in a new record inserted in a SMS queue table. The data in this table is read during the Deliver Payload process.

Algen & Dispatch

In addition to the regular signal process done by SBN’s Algen, it will also execute the conditions listed in section “Find SMS Recipients”. Records created in this process will have no terminal ID, no message type, and no message.

Dispatch Operator SMS

The following graphic shows the Dispatch tab with alarm information displayed.

A new button “Operator SMS” was added in SBN Program# 537 Dispatch (new action will be created for this button) to “Send SMS”. This allows an Operator to initiate SMS messages to Contacts. This button will only work if the operator has an unresolved incident loaded in the Dispatch tab of 559.

Clicking the button will open a new screen and offer a list of “canned” messages. 

In Dispatch, an Operator will have the pre-defined list of “canned messages” defined in program 2510 available.

Selecting the message in the picklist will show the message description in the lower box.  Pressing Save adds the message to the queuing table.

Section “Find SMS Recipients” describes all conditions used to identify which Contacts receive the SMS. Records created in this process.  Operator SMS messages will have the Operator’s Terminal ID and the message type selected.

The SMS Queue

When getting started with Interactive SMS you may want to view the underlying table to verify data.

Use the following SQL query (where security and permissions permits) to view the SMS queue table:

select * from sbnmaster..fe_sms

Records are inserted into this table from two areas. 

First is via Algen, when a record is processed from the immediate queue. 

Second is initiated via SBN.exe by an operator when working on an incident.

Both processes use the same conditions to find and inject records into the table. 

APIEngine / API3

Getting Records from the SMS Queue (g_sms)

g_sms retrieves records from the SMS queue. Use the APIEngine API3 portal to become familiar with the stored procedure parameters.

This stored procedure call creates an Alarm Log entry to indicate that message(s) have been successfully delivered from the SBN table to whomever called the procedure.  This is not meant to indicate that the message was relayed to the final destination.

Note: Calling this procedure also delete records from fe_sms sent over 7 days ago. In other words, records will remain in this queue (by design…for debugging purposes) 7 days after they are processed.

Creating an Alarm Log “SMS Sent” Entry (c_sms_sent)

c_sms_sent creates an Alarm Log entry to indicate that message(s) have been successfully delivered the SMS to the final destination (i.e., a mobile phone). Use the APIEngine API3 portal to become familiar with the stored procedure parameters.

Disposing of an Incident (c_sms_dispose)

c_sms_dispose attempts to dispose of an incident. Use the APIEngine API3 portal to become familiar with the stored procedure parameters.

If successfully disposed an Alarm Log entry is created to indicate that the incident was successfully disposed.  If not successful, one of the base messasges (0-10) is used to relay to the customer that disposition failed.

SMS Front-End

If you do not want to write your own front-end to process Interative SMS Messages you can use APIEngine. For this purpose APIEngine is enhanced and uses Twilio.

The Twilio phone number defined in SBN option twi_phn1 is used.  This is the same phone number used for Care Button (aka: Home Health).  The reuse is possible because this uses the SMS feature and Care Button uses the Voice feature.

You will need to configure the SMS feature in Twilio for the selected phone number.  If this is not configured then SMS replies from the customer will fail.

Note: You will want to use the URL(s) for your company.

APIMapper Service

Lastly, use the SBN Windows service API Mapper to process SMS records. 

This is the same service and feature used for the Care Button (aka: Home Health).

All you should need to do is add the Additional Call (shown above).

Alterntaively, you can create your own process that periodically make the following call:

GET: <url>/v1/Twilio/SMS/Interactive

Button Functions

The following table displays the new button, describes the shortcut keys, actions, and functionality.

Button	Name	Shortcut Key	Action	Description
	Operator SMS	N/A	537/151	Allows an operator to initiate SMS message to contacts.

Modifications and Updates to Dispatch

The following table lists modifications and updates to the Dispatch document.

Mod Number	Date	Description
08.85.10732 07.85.24994	10/04/16	Process for delivering SMS data from SBN to a 3rd party, allowing confirmations of sent SMS back into SBN, and disposing of an incident via SMS.