Cohorts

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.

Features

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.

Setup

Cohorts is a Ruby on Rails app. The regular rules apply:

1. Locally or in a VM, install dependencies:
   • PostgreSQL - Ubuntu | Mac
   • Ruby 2.3.1 - Install using rbenv or rvm
   • Bundler - gem install bundler after installing Ruby
2. Clone this repo: git clone https://github.com/adhocteam/cohorts-open.git
3. In the project directory, run bundle install
4. 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
   • \q
   • Set password as PG_PASS environment variable in your .bashrc/.bash_profile or in .env
5. Setup the database by running bundle exec rake db:setup
6. Run the app with rails s

Environment Variables

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

If you are hosting the app on AWS Elastic Beanstalk or Heroku, you can also manage the environment using their built-in interfaces.

External Services

Wufoo

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.
• • It is only necessary to add mappings for fields which are necessary for the creation of the user.
• • Run rake add_mappings_to_forms:update which will then run your rake mapping and add it to the DB.

Twilio

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:

• /twilio/receive

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:

• MAILCHIMP_API_KEY
• MAILCHIMP_LIST_ID
• MANDRILL_USERNAME
• MANDRILL_API_KEY

Tests

To run all tests and Rubocop:

bundle exec rake

Contributors

CUTGroup:

• Chris Gansen ([email protected])
• Dan O'Neil ([email protected])
• Bill Cromie ([email protected])
• Josh Kalov ([email protected])

Ad Hoc:

• Dan O'Neil ([email protected])
• Nick Clyde ([email protected])
• Danny Chapman ([email protected])
• Scott Robbin ([email protected])
• Oren Fromberg ([email protected])
• Jesse Skeets ([email protected])
• Brooks Johnson ([email protected])

License

The application code is released under the MIT License. See LICENSE for terms.