This is the software that was used to manage Cohorts, a service of Ad Hoc that allowed us to conduct incisive research with groups of relevant people to make government digital services work better for all. It was heavily based on kimball, originally developed for the Civic User Testing Group by the Smart Chicago Collaborative. See also the launch blog post for Cohorts and The CUTGroup Book.
The tool was decomissioned in early 2019 and the code open sourced. This repo is archived because the tool is no longer used or supported.
Cohorts was a tool to recruit, manage, and communicate with a large pool of people to test the products we build. Cohorts stored information about people that have signed up to participate in Ad Hoc user research. It did so by integrating with three external services:
- Wufoo was used to create web forms that can be sent out to participants to collect more information about them.
- Twilio was used to communicate with participants via SMS.
- Mailchimp and Mandrill were used to communicate with participants via email.
Cohorts is a Ruby on Rails app. The regular rules apply:
- Locally or in a VM, install dependencies:
- Clone this repo:
git clone https://github.com/adhocteam/cohorts-open.git
- In the project directory, run
- Create a PostgreSQL superuser with your computer's username (replace [myuser]):
sudo -u postgres createuser -s [myuser]
sudo -u postgres psql
\password [myuser]and enter password
- Set password as
PG_PASSenvironment variable in your
- Setup the database by running
bundle exec rake db:setup
- Run the app with
Environment variables are loaded from the
.env file in the root directory using the dotenv gem. This file should not be committed to git. To get started locally, you can run the following command:
cp sample.env .env
Wufoo hosts all forms used for Cohorts. There are 4 environment variables that need to be defined for Wufoo:
WUFOO_ACCOUNT- your account identifier
WUFOO_API- your API key
WUFOO_HANDSHAKE_KEY- a handshake key prefix that must be defined on each Wufoo form's Webhook
WUFOO_DEFAULT_FORM- the hash ID for the default signup form
Webhooks are used on Wufoo to send data back to Cohorts. Currently there are 2 webhooks in use:
admin/people- This endpoint is used for new signups via any signup/registration Wufoo form.
admin/submissions- This endpoint is for all other Wufoo forms (call out, availability, tests). It saves the results in the submissions model.
If a new signup form is added to Wufoo the form must be mapped so that the users can be added to the database.
- Manually import the form from Wufoo into cohorts by going to the forms page and clicking on plus sign button on the upper right to pull updates from Wufoo. The form now exist in the rails application but does not have any mappings.
- Add the mappings for your new form to
add_mappings_to_forms.rake. The Field numbers can be found on wufoo under Form -> More -> API Information.
- Add the mappings for your new form to
- It is only necessary to add mappings for fields which are necessary for the creation of the user.
rake add_mappings_to_forms:updatewhich will then run your rake mapping and add it to the DB.
Twilio is used to send and receive text messages for sign up, notifications, and surveys. It is also used to schedule interviews and calls. There are 3 environment variables that need to be defined for Twilio:
TWILIO_ACCOUNT_SID- your account identifier
TWILIO_AUTH_TOKEN- your API key
TWILIO_NUMBER- the phone number that will be used to send messages
Webhooks are used on Twilio to send messages to Cohorts. Set the following webhook on your Twilio phone number:
Mailchimp & Mandrill
Mailchimp is used to create email campaigns and send email to segmented groups of people. Mandrill an SMTP service used to send one-off emails from the application. There are 4 environment variables that need to be defined for Mailchimp and Mandrill:
To run all tests and Rubocop:
bundle exec rake
- Chris Gansen (firstname.lastname@example.org)
- Dan O'Neil (email@example.com)
- Bill Cromie (firstname.lastname@example.org)
- Josh Kalov (email@example.com)
- Dan O'Neil (firstname.lastname@example.org)
- Nick Clyde (email@example.com)
- Danny Chapman (firstname.lastname@example.org)
- Scott Robbin (email@example.com)
- Oren Fromberg (firstname.lastname@example.org)
- Jesse Skeets (email@example.com)
- Brooks Johnson (firstname.lastname@example.org)
The application code is released under the MIT License. See LICENSE for terms.