Coordinated Entry Screening (CES)

The Coordinated Entry Screening tool helps people experiencing homelessness in Chicago and its surrounding suburbs. The tool guides users through a series of questions to determine eligibility for Coordinated Entry Access points and other resources. Users can complete the survey via text-message or on a web interface.

Built in collaboration with the Corporation for Supportive Housing.

Setup

Dependencies

The Coordinated Entry Screening tool leverages the power of RapidSMS (a framework built on top of Django for creating mobile services), rapidsms-decisiontree-app (an app to support the creation of surveys), and the Twilio API for text messaging. DataMade forked, updated, and customized some of these dependencies. At the very least, clone the DataMade fork of rapidsms-decisiontree-app to your local machine.

DataMade forks

rapidsms - uses Django 1.11
rapidsms-decisiontree-app - uses Django 1.11 and Python 3, and customized to suit the needs of CES
rapidsms-twilio, an integration app – uses Twilio 6.16.2

Other dependencies

twilio-python
ngrok (for local development only)

Getting started

Step 1. Create a Twilio trial account and phone number

Note! You might not be developing the text-messaging aspect of this tool. If so, you can skip Step 1 and leave blank ACCOUNT_SID, AUTH_TOKEN, and TWILIO_NUMBER in the settings file (Step 3).*

Visit twilio.com, and follow the steps to signup for a new account. Please note! Trial accounts do not expire, but they can reach a limit on the number of messages sent.

Use the Twilio dashboard to add a phone number. Then, add your personal cell phone as a verified caller, since trial accounts only communicate with verified numbers.

Step 2. Setup a virtualenv, clone the CES repo, and install dependencies.

We recommend using virtualenv and virtualenvwrapper for working in a virtualized development environment. Read how to set up virtualenv.

Once you have virtualenvwrapper set up, do the following:

git clone git@github.com:datamade/coordinated-entry-screening.git
cd coordinated-entry-screening
mkvirtualenv coordinated-entry-screening
pip install -r requirements.txt

Afterwards, whenever you want to use this virtual environment, run workon coordinated-entry-screening.

Step 3. Create a settings file

cp coordinated-entry-screening/settings_deployment.py.example coordinated-entry-screening/settings_deployment.py

Update your secret key, and assign values to the Twilio-specific variables (found in your Twilio dashboard).

SECRET_KEY = 'super secret key of your choosing'

# Look for these on https://www.twilio.com/console
ACCOUNT_SID = '*******************************'
AUTH_TOKEN = '*******************************'

# The number you created above!
TWILIO_NUMBER = '(312) 624-6268'

Step 4. Setup the database

rapidsms-decision-tree app requires a database for storing information about messages, answers, and tree states.

The data directory has a dump of the database used at the time of launching. It is in custom archive format: you can restore it locally by running the following. (Read more about dumping and restoring databases.)

pg_restore -C -j4 --no-owner data/ces_launch.dump | psql

Create an admin user. Set a username and password when prompted.

python manage.py createsuperuser

Note! To restore the database on the server, do the following.

ssh ubuntu@connectmenow.org

# drop and create a fresh database
dropdb -U postgres coordinated-entry-screening
createdb -U postgres coordinated-entry-screening

# retore the database
pg_restore -U postgres -C -j4 --no-owner --role=datamade /home/datamade/coordinated-entry-screening-d-<deployment-id>/data/ces_launch.dump | psql -U postgres

# change its owner
psql -U postgres
ALTER DATABASE "coordinated-entry-screening" OWNER TO datamade;

If you need to restore the database on the server, after the time of launch, then be sure to preserve the user data in the relevant tables. See the dashboard view for more info.

Run the tool

Text-messaging

Phew! Congrats on surviving a massive setup. You are nearly ready to run the tool locally. But first, Twilio needs to know about your local version of the CES tool. To make your app reachable, use Ngrok as advised by the Twilio docs. As the docs describe, you will need two terminal windows: one with Ngrok running, the other with CES.

# in one window
./ngrok http 8000

# in another
python manage.py runserver

Now, visit Twilio and find the details about your newly created phone number. Under "Messaging," add http://******.ngrok.io/backend/twilio/ as a webhook. The exact URL should correspond with whatever Ngrok spits out in your local terminal.

The big moment! Send a message to the phone number. The CES trigger word depends on the details of your survey, but for testing purposes, just try "ping." Did the app "pong"?

Web interface

This should be a breeze. Just run, and visit the URL provided in your terminal:

python manage.py runserver

Data

The survey

DataMade and the Corporation for Supportive Housing devised question logic to guide users to resources. The basic survey includes these questions:

Where are you located?
What is your age?
Where did you sleep last night?
Do you have a child or children?
Do you have an income, but require short term financial support to help with housing costs, e.g. rent, electric or heating bills, etc.? (ONLY for 2019)
If you slept in the home of a friend or family member or your own home, is it a stable safe place to stay for the forseeable future?
If you slept in the home of a friend or family member or your own home, are you attempting to flee because it is an unsafe setting?

Decision trees located in the data/survey_diagrams folder visualize how users move from question-to-resource-to-question. We created these using (a free trial of) LucidChart.

Trigger codes

The database has three basic versions of the survey:

a survey for people in the city or suburbs (accessed with the keyword "connect"),
a survey for people in the city (accessed with a code, e.g., by texting "0006"),
a survey for people in the suburbs (currently, not in use, but may be in the future).

We populated the database with location-specific trigger codes using an very simple ETL process. CSH provided us with an Excel document with 90+ city codes, and our Makefile ported these codes to the database. This process does not need to be repeated, but it can be, if CSH provides a different spreadsheet in the future.

See the data directory for relevant files.

Team

Errors and bugs

Is something not behaving intuitively? Report it by creating an issue.

Use Mozilla's guidelines for reporting bugs to precisely and concisely describe your issue.

Patches and pull requests

We welcome your patches! Our suggested workflow:

Fork the project.
Make your feature addition or bug fix.
Send us a pull request with a description of your work.