This is a Calltree based communication application to provide a quick and easy way to broadcast important
SMS messages and record stats such as when people have responded and how long it took them.
During a crisis – what do you need to do?
Inform your staff/volunteers/contacts – of what?
Account for your staff/volunteers/contacts – how are you going to find out if everyone is OK?
Respond to queries – how are you going to manage queries, what contact info will you give people?
With a manual based calling tree, you can pick up the phone and have a conversation with someone, but what happens if they haven’t got all of the information they need? You will need to call them back and the calls can become challenging and time consuming.
At what point do we say, we need a system in place?
Manual versus Automated
Take a simple scenario with an incident and informing employees not to come to the office.
You have to inform your employees. Have you got all of their phone numbers?
What happens if you have over 1000 employees – the process of contacting everyone will take even longer. Also the message may become lost in translation along the way.
Using an automated tool, you can reach a large amount of people within a short space of time, and you can send the message exactly when it is needed. Employees can be kept informed and updated of the situation as the incident plays out. You can also get a response from people to show they have recieved the message.
What we need to do is look at ways to communicate with people via a mass broadcast. In the first cycle of communications you want to try and reach everybody. Maybe you will get to 70 – 80% of people. The next step is to then focus on those people that didn’t respond the first time to check that everybody is OK. This focuses your attention on those people that might need help.
When trying to reach more than a handful of people, gathering a response and reporting back using a manual calling tree really is an old fashioned way of doing things. In this day and age with the technologies available, utilising a notification system really is the only practical way of staying in command and controlling any issue.
How it works
This application sends a broadcast message to a list of contacts, for example employees, to notify them quickly of critical business information.
With a few clicks the administrator (BCP Champion) can initiate a call tree and collect statistical information such as overall
response time between outbound and inbound sms, % of replies within X number of minutes and also detailed stats for each recipient.
There are four key roles in this Business Continuity Plan application: CHAMPION, MANAGER, LEADER, REPORTER.
When the CHAMPION triggers a new event, the application will send an SMS from the top-level of the tree to all the
levels below, as shown in the diagram below.
The event is then considered closed when everyone responds to their SMS message, or when the CHAMPION terminates it manually.
The system collects data throughout the active event(s) for statistical purposes. It is possible to have a general overview
of a particular event with the following information:
- response time average (in minutes) of all received SMS messages
- total number of outgoing SMS
- total number of incoming SMS
- percentage of replies within X minutes (defined by the CHAMPION)
- Backend in Java and Kotlin
- Spring Boot / Data JPA / WEB
- H2 enabled DB (also available for integration tests)
- PostgreSQL ready application for data persistence
- OpenAPI v3 (SpringDoc / Swagger) for full REST endpoint mapping – localhost:8080/swagger-ui.html
- Maven build tool
- Full suite of Automated tests and Integration tests
- CircleCI for continuous integration
- A Twilio account – sign up
- Java 11 or higher
- Kotlin 1.3.50 or higher
- Maven 3.5 or higher
- NPM, Node JS, Yarn to run the UI
How to use the app:
To test out events you are going to need a Twilio phone number setup – you can get one here. Afterwards the Twilio phone number can be added into the application later using the UI.
All the numbers in the applications must be in E.164 format
Setting up a new trial account
First create a new account and sign in, once you do you will be greeted with the following screen
Press the big red
Get a Trial Number button
Then either accept the offered number, or press
Search for a different number, to pick one in another country
Make sure the number you pick can send and receive SMS
Now you have a valid number to use during testing.
However if you are planning on running this application in Localhost, then in order to get full functionality you must enable a way for Twilio to contact your localhost endpoint.
Localhost Twilio config
First lets create and setup
Programmable Messaging from the menu, which can be accessed via the
Create Messaging Service
Add Senders and set sender type to
Select the trial number you just created, and press
save at the bottom of the screen
Now select the
Integration sub menu
Now you will need to download and run
ngrok or an alternative tunnelling software.
Download ngrok here and extract the .exe somewhere locally
In a command shell from the same directory as the .exe run
ngrok http 8080
Copy the https Forwarding parameter e.g. https://b6231be3.ngrok.io (this is mock data) and paste this into the request URL on Twilio. Then append
/api/v1/events/twilio to the end of the URL so Twilio can reach this endpoint locally to send stats when people reply to a message.
Make sure the behaviour is set to
Send a webhook
In order for the app to connect to Twilio you will need to set up your twilio account information as shown below
Change the default values in the file
calltree-coresrcmainresourcestwilio.properties to include your twilio account details
- Clone the repo:
git clone https://github.com/TeamWicket/Twilio-BCP-CallTree.git
- Prepare a java executable using Maven:
mvn clean installor using the wrapper
mvnw clean install
- From the command line, navigate to the .jar file at
calltree-coretargetand run it using:
java -jar calltree-core-0.0.1-SNAPSHOT.jar
- The backend will now be running as a standalone Spring Boot application
Front end setup
yarn is installed via
yarn -version, if it’s missing it can be installed via
npm install -g yarn.
On Windows you will also need to add it to PATH, it’s default installation is in
- Navigate to the
calltree-uirepo and use the commands:
- This will then load the front end up in your browser
Running application details
When you first load the application up you will get your high level dashboard that can display an overview of your application setup
Note: If you wish to switch to a cool
dark mode then click on the profile button in the top right and select configuration and change your theme.
You can also
log out of the app and it will return you to a login screen, this can be forked and your own auth implementation can be added in here, for the purposes of our demo its only there to show what can be done but you can
login again by typing in anything here and hitting enter. For your own implementation you will need to define your own authorisation using the Auth component.
If you then navigate to the
Contacts menu option this will give you the ability to add contacts, the first contact must be marked as the
Champion, you can then add more contacts. Please note whoever each persons
point of contact is will be the name and number they are instructed to contact in the event they have any questions once they reply to the initial BCP event message.
The following screen is where you can add your Twilio number that you assigned earlier, note you must have an active twilio number available in order to create an event.
You must setup your number as
Is available for it to be used as part of your event.
Finally when you are ready to send some messages you can go to the
events screen and create a new event
Enter the mesage you wish to be sent in the text field, Select which roles you wish to send this message to (note this is hierarchical so if you wish to send to EVERYONE then select
reporter as this will go up the chain. If you wish for
Leaders and everyone above then select this and so forth. The Champion will not recieve a message as they will kick off the event.
Finally click the start event button and this will send your messages.
If you wish to see the stats just now you can do so by using the Swagger endpoints for the Stats Controller or by looking in the database table for the call event information.
By default the application runs off an in memory H2 database, however it is compliant with an external PostgreSQL database to ensure persistance longer term and outside of a demo environment. This can be done by:
- Downloading a PostgreSQL Database here: https://www.postgresql.org/
- Modify the
- Set the following parameters:
spring.datasource.url: set it to the url of your PostgreSQL server e.g. jdbc:postgresql://localhost:5432/postgres
spring.datasource.username: set this to the PostgreSQL user. NOTE, the schema will be automatically created in this user’s database
spring.datasource.password: the user’s password
- Start the application with the extra parameter
-Dspring.profiles.active=liveso the full command would be:
java -jar calltree-core-0.0.1-SNAPSHOT.jar -Dspring.profiles.active=live
When starting, the application will check whether the schema and tables exist and if not automatically create these in the provided user’s database under the schema
This template is open source and welcomes contributions from the community. All contributions are subject to our Code of Conduct.
Visit the project on GitHub
React-Admin – https://github.com/marmelab/react-admin
The amazing work done by https://github.com/marmelab has allowed us to build a very nice functional front end.
No warranty expressed or implied. Software is as is.