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.
Manual
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.
Automated
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.
Conclusion
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.
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
- Modern Frontend in React (JavaScript / TypeScript)
- 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 - #
- Java 11 or higher
- Kotlin 1.3.50 or higher
- Maven 3.5 or higher
- NPM, Node JS, Yarn to run the UI
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
First create a new account and #, 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.
First lets create and setup Programmable Messaging
Select Programmable Messaging from the menu, which can be accessed via the ... icon
Then pressing Create Messaging Service
Then pressing Add Senders and set sender type to Phone Number
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-core\src\main\resources\twilio.properties to include your twilio account details
| Config Value | Description |
|---|---|
| Account Sid | Your primary Twilio account identifier - find this in the Console. |
| Auth Token | Used to authenticate - just like the above, you'll find this here. |
- Clone the repo:
git clone https://github.com/TeamWicket/Twilio-BCP-CallTree.git - Prepare a java executable using Maven:
mvn clean installor using the wrappermvnw clean install - From the command line, navigate to the .jar file at
calltree-core\targetand run it using:java -jar calltree-core-0.0.1-SNAPSHOT.jar - The backend will now be running as a standalone Spring Boot application
Make sure 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 C:\Users\<user>\AppData\Roaming\npm.
- Navigate to the
calltree-uirepo and use the commands:
yarn installyarn start
- This will then load the front end up in your browser
| Service | Address |
|---|---|
| Backend | http://localhost:8080 |
| Frontend | http://localhost:3000 |
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
application-live.propertiesin thecalltree-core/src/main/resources/folder - Set the following parameters:
spring.datasource.url: set it to the url of your PostgreSQL server e.g. jdbc:postgresql://localhost:5432/postgresspring.datasource.username: set this to the PostgreSQL user. NOTE, the schema will be automatically created in this user's databasespring.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 call_tree.
This template is open source and welcomes contributions from the community. All contributions are subject to our Code of Conduct.
- Alessandro Arosio: Github - LinkedIn
- John Hanna: Github - LinkedIn
- Malcolm Watt: Github
- Alistair McKellar: 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.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
