HMS Hub manages the delivery and tracking of phone-based notifications to end recipients. It is particularly well suited for environments where recipient phones are frequently inaccessible; this may be due to limited signal range or access to power, common in some developing countries.
The hub supports SMS and IVR (voice message) delivery methods and comes
bundled with support for Nexmo (SMS) and
IntellIVR
(IVR). You can also develop and plug in additional delivery providers (see
app/models/delivery/provider for example implementations).
This software was developed to support objectives outlined in the CCPF program.
The VillageReach CCPF program, CHIPATALA CHA PA FONI, means "Health Center by Phone" in the Malawian language of Chichewa. The program is focused on maternal & child health improvement, through increased access to basic health information, and prompting towards earlier interaction with the health system. The program has two components: a toll-free hotline for pregnancy & infant health advice and referrals, and a health-tip messaging system, which pushes SMS and voice messages out to rural clients who have been enrolled in the tips system. The program enjoyed a successful pilot over 2 years, from 2011-2013, handling hundreds of callers per week, and is now in the process of expanding its reach.
The software used by the hotline workers to record caller interaction is mnch-hotline, developed by the Malawian health-software company Baobab Health Trust. The software to handle the tips-message distribution, HMS-Hub, and HMS-Notifier, were developed by VillageReach. All components are in active production use in Malawi.
The tips-messaging system is designed to operate robustly in a environment with intermittent connectivity, and multiple remote messaging sources. The Hub software is intended to be on a relatively better-connected server. It centralizes handling of all the message-delivery gateways (SMS, IVR, email, etc) and serves as a capable store-and-forward. Each authorized instance of the Notifier software connects to the Hub periodically to issue a new set of message requests, and receive data on message-attempt results. Both apps expect an unreliable Hub-Notifier connection, and to a lesser extent, an unreliable connection between the Hub and its messaging gateways. The Hub also handles its own retries of failed messages, for when the gateway does not.
In production practice, in Malawi, the Hub is in a telco server room, on the telco's network connection. The currently single Notifier instance on the hotline server, located in a rural district hospital, where the hotline workers have local oversight in the pilot program. The Notifier connects via a USB dongle, over a private APN on the telco's 2G network. The software handles regular downtime between those servers, and the Hub handles SMS and voice messages that often take multiple retries to reach customer phones, which are often out of range or powered down.
It is assumed that you have ruby version 1.9.3, are using bundler and have the necessary mysql headers to compile the mysql2 gem.
git clone git://github.com/dhedlund/hms-hub.git hms-hub
cd hms-hub
bundle install
bundle exec rake db:create db:schema:load db:seed
bundle exec rails s -blocalhost
Create a .foreman file inside the project directory:
### Options: ###
# color type: boolean Force color to be enabled
# env type: string Specify an environment file to load, defaults to .env
# formation type: string "alpha=5,bar=3"
# port: type: numeric Default: 5000
# procfile type: string Default: Procfile
# root type: string Default: Procfile directory (app root)
###
procfile: Procfile.development
formation: web=1,worker=1,spork=1
port: 3000Pry and IRB sessions do not play well with Foreman spawned daemons. While it is possible to drop into a pry session and interact, there is no readline support and you can not generally see what you type. A workaround is to use the pry-remote gem, already included with the application.
To use pry-remote, instead of using binding.pry you should use binding.pry_remote
class MyController < ActionController::Base
def my_action
@values = some_other_method()
binding.pry_remote
endWhen the pry_remote method is reached, it will start a DRB session and log the following message to indicate the process is waiting for a connection:
00:09:51 web.1 | [pry-remote] Waiting for client on druby://localhost:9876
You can then connect to the remote pry session in a separate terminal window:
bundle exec pry-remote
From: /path/to/rails_app/app/controllers/my_controller.rb @ line 2 MyController#my_action:
2: def my_action
3: @values = some_other_method()
=> 4: binding.pry_remote
4: end
[1] pry(#<MyController>)>bundle exec rake test # all tests
bundle exec rake test:units # unit tests
bundle exec rake test:functionals # functional/controller tests
TEST=test/unit/notification_test.rb bundle exec rake test # single test file
If you are running foreman with spork=1 in your .foreman file then spork should already be running. If you are using spork outside of foreman, you can start the spork server with:
bundle exec spork
To run tests using spork:
bundle exec testdrb # all tests
bundle exec testdrb test/unit # unit tests
bundle exec testdrb test/functional # functional/controller tests
bundle exec testdrb test/unit/notification_test.rb # single test file
bundle exec testdrb test/**/*_test.rb # all tests, example using wildcards