Outbound SMS

Initial scope of the outbound SMS feature as documented by Gurpreet Luthra in email on April 27, 2013

Target release	Unscheduled
Theme	Mobile Integration
Document status	DRAFT
Document owner	Gurpreet Luthra (Unlicensed)
Designer
Developers
QA

Goals

The main idea of the Outbound SMS feature is to provide MifosX the ability to send SMS to clients, loan officers and others for various events and announcements -- like pending disbursement, pending payments, task list, monthly cash summary, etc.
Currently Mifos and the client and portfolio data it contains is only accessed by the staff of the MFI. However, the majority of clients served by MFIs own mobile phones. A simple yet powerful way for them to interact with the data in Mifos is via SMS. MFIs have requested the ability for both inbound and outbound SMS communication to send notifications to their clients and to enable clients to retrieve information about their accounts. When living on less than $2/day, this simple yet timely interaction with their financial accounts is extremely important.

Background and strategic fit

Apart from the client need for this accessible and affordable stream of data, there are many technology companies and mifos integrators who are seeking to integrate SMS modules to send data outbound from their applications or services.

Assumptions

Plugin Based Implementation: A plugin design where one can plugin an SMS gateway service to MifosX which takes input as a phone number and a message, and sends out an SMS.
SMS Gateway Plugins: Implementation for maybe 2 SMS providers as plugins: Twilio, Nexmo, or Telerivet. (Gurpreet Luthra (Unlicensed) how about initially targeting FrontlineSMS, FLS for short, as this would easily give us several gateways "for free", see my thoughts in MIFOSX-771 - Getting issue details... STATUS , and then later extend that to other direct connectors, via MIFOSX-773 - Getting issue details... STATUS and more?)

Requirements

#	User Story Title	User Story Description	Priority	Notes
1	SMS Queue: MIFOSX-772 - Getting issue details... STATUS	A queuing mechanism, where SMS events to be posted are put on a queue, and then a queue reader picks each SMS up and posts it out through the configured SMS Gateway. This queue should be visible in UI (exposed through API), with a status of whether the SMS was sent successfully or not. Attributes: Target User, Phone Number, Message, Time, Success/Failed, Status Message (to indicate error message or success message), Triggered By (Username/System).	TBD	Q: Should this be implemented using a persistent JMS queue, or a similar queue library? - A: No! Just DB. Q: How does this look for multi-tenant systems. One common queue or a queue-per-tenant? I guess a queue-per-tenant.
2	Provide a Simple SMS sending capability for a Client: MIFOSX-775 - Getting issue details... STATUS	Provide the ability to send any text sms via a simple dialog box in Client screen. This is more for show casing that a loan officer can maybe send some message to the client via the system. Some questions here:	TBD	Q: How do we ensure each client has given us a phone number? A: We shouldn't - you just cannot SMS a client without a number. Q: If many people share a common phone number (in a group for instance), then maybe sending the "name" of the person in SMS is important. A: For automated SMS, this would just be in the template. For manual SMS, it's just "up to the user"? Or have a hint on the UI?) Q: Do we need some country specific validation in phone number entry for a client? A: Some thoughts in MIFOSX-779 - Getting issue details... STATUS . Q: Do we need some flag indicating that a user has not configured a valid phone number and hence we won't be able to send any sms notification.
3	Identify Automatic System Notification SMS Events	We need to identify some system events and scenarios which we would like to have integrated via SMS notification. Can you give some suggestions on what these could be? As I understand, there would be 3 types of SMS notifications: Manual - triggered by someone from within MifosX. Like sending an SMS to a client with some message. Event based - triggered by system whenever certain events occur. Like a loan is approved or rejected, etc. Schedule based - triggered periodically, running as a batch job.. maybe integrated with the Spring Scheduler framework. For instance of checking on disbursements to be done today, and send sms in morning to all loan officers. I need examples or what events we would like to support to begin with. Some that come to my mind are (based on my super limited domain knowledge): Inform a client when her loan is approved - "Your loan of amount X has been approved". Inform a client when her loan is disbursed - "Your loan for amount X has been disbursed on <date>". Inform a client when her next repayment is due (n days earlier) - "For loan payment for Rs 300 is due in 3 days on the 21-April-2013". I need more suggestions on this.	TBD	This contains a LOT - we should split this up more fine grained.. the schedule based part of this, with templates, would be MIFOSX-778 - Getting issue details... STATUS
4	SMS Notification Configuration Screen	Need to create a configuration screen where all SMS based notification configurations can be done. This will contain the following: SMS Gateway Plugin choice + Gateway Plugin configurations/credentials Which system events should be enabled for auto-send (from list 5 above) What would be the template message for each type of system event (or maybe for now, we hardcode this in code, and expose templates later when the need arises) The problem around hardcoding the SMS message for system events is that we need to send messages in different languages to different roles. Like Loan Officer may want SMS in English, while Clients may want it in Swahili, or Hindi, etc. So - it would just make sense to give the ability to enter the SMS template message right now. Ability to see the SMS notification queue.	TBD	Templates should be defined quite separately and outside of the respective SMS Gateway configuration.

User interaction and design

Questions

Below is a list of questions to be addressed as a result of this requirements document:

Question	Outcome
Q: How do we ensure each client has given us a phone number? -	A: Don't; it will simply fail.
Q: If many people share a common phone number (in a group for instance), then maybe sending the "name" of the person in SMS is important.	A: Giving the SMS gateway service API the name as an input as well is probably not a good idea in general. (With FrontlineSMS, you could then imaging to automatically create Contacts in FrontlineSMS.)
Q: Do we need some country specific validation in phone number entry for a client?	A: that will probably quickly get complicated; KISS, and forget it for now.
Q: Do we need some flag indicating that a user has not configured a valid phone number and hence we won't be able to send any sms notification.	A: Just grey out the "Send SMSthat will probably quickly get complicated" button/icon? With a tooltip "Cannot send SMS as no phone number."

Mifos X