We work with educators to make open, secure, student-centered data systems. Say hello@studentinsights.org!
Clone or download
kevinrobinson Merge pull request #2361 from studentinsights/feature/mtss-import
MTSS: Add minimal semi-automated importer for MTSS referral form
Latest commit c850894 Jan 18, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Simplify pull request template Oct 11, 2018
app Merge pull request #2361 from studentinsights/feature/mtss-import Jan 18, 2019
bin remove DelayedJob Sep 14, 2018
config Merge pull request #2361 from studentinsights/feature/mtss-import Jan 18, 2019
db Starting to work on tests Jan 16, 2019
docs Add back stub MixpanelUtils that does nothing Nov 21, 2018
lib 504: Add SQL and initial importer for Somerville, minimal UI for dat… Dec 8, 2018
public And update robots.txt Dec 3, 2018
scripts Update rebuild demo script again Dec 19, 2018
spec Merge pull request #2361 from studentinsights/feature/mtss-import Jan 18, 2019
ui Add a round of tests and stories to smaller components Jan 18, 2019
vendor/dante Removing more application.js dependencies Oct 23, 2017
x2_export Update to work after test Dec 8, 2018
.babelrc Add Webpack and move JS out of Rails Oct 21, 2017
.dir-locals.el Add editing environment for Emacs Jun 15, 2016
.eslintignore Add Webpack and move JS out of Rails Oct 21, 2017
.eslintrc Change use of global to window Jun 4, 2018
.gitallowed Add whitelist for git secrets Nov 21, 2018
.gitignore Add folders for GitHub pages to gitignore" Nov 8, 2018
.mention-bot Add CoverageChecker Nov 27, 2018
.pairs Continue the refactor with STAR and ACCESS Nov 25, 2015
.rspec Migrate and seed working, sign_in working, still no passing tests Feb 12, 2017
.rubocop.yml Fix Rubocop warning, and spaces Oct 20, 2018
.ruby-version Update Ruby 2.5.3 Nov 22, 2018
.travis.yml Add CoverageChecker Nov 27, 2018
CONTRIBUTING.md Add note about studentinsights-bot in CONTRIBUTING Sep 16, 2017
DRAFT-SECURITY-AND-PRIVACY-POLICY.md Remove references to Scout Sep 11, 2018
Gemfile Multifactor: Add private methods for provisioning manually Dec 13, 2018
Gemfile.lock Multifactor: Add private methods for provisioning manually Dec 13, 2018
LICENSE Add MIT License Feb 10, 2015
Procfile Fix Quotaguard conditional in Procfile Aug 1, 2017
QUOTAGUARD-LICENSE.txt Add QuotaGuard Static socksify Jan 9, 2016
README.md nah no bikes for you Nov 21, 2018
Rakefile Remove Capistrano; not our current deploy strategy Feb 5, 2016
app.json Try setting env Nov 21, 2018
config.ru Init Rails app Jan 14, 2015
jest.json Limit jest test fn filters, remove old it.only Jun 4, 2018
onboarding.md Update onboarding.md May 11, 2016
package.json Merge pull request #2242 from edavidsonsawyer/discipline_heatmap Dec 12, 2018
studentinsights.sublime-project Undo f1b534c May 9, 2016
yarn.lock Merge pull request #2242 from edavidsonsawyer/discipline_heatmap Dec 12, 2018


Student Insights

Student Insights gives educators an overview of student progress at their school, classroom-level rosters and individual student profiles. It also allows them to capture interventions and notes during weekly or bi-weekly student support meetings.

Check out the demo site with different roles:

  • District admin: uri@demo.studentinsights.org
  • K8 principal: laura@demo.studentinsights.org
  • Kindergarten teacher: vivian@demo.studentinsights.org
  • HS physics teacher: hugo@demo.studentinsights.org
  • 9th grade counselor: sofia@demo.studentinsights.org

All accounts use the password: demo-password.

Our presentation at Code for Boston demo night in May 2016 also has a good product overview.

Table of Contents

User personas: Who we're serving

There are three main user personas we're serving. Principals, Interventionists and Classroom Teachers. Right now we're focused primarily on serving principals, and the rough progression will likely be to Interventionists next. Early adopter Classroom Teachers are great, but focused on scaling adoption across all classroom teachers isn't a priority yet.

Principals are responsible for a school, from ensuring all students are progressing academically to making hiring and staffing decisions for teachers.

Interventionists are typically folks who provide some kind of specialized service to students, like counseling, behavioral services or specialized reading instruction. They have caseloads of 20-70 students and are often involved in interdisciplinary teams focused on supporting students who are most at-risk.

Classroom Teachers are responsible for teaching all subjects in an elementary level, and at the middle school level typically teach two subjects, with a few periods of each subject.

Product overview: How we're helping

School overview

Principals and intervention specialists can get an overview of all students at school, updated automatically as new data comes in. This includes demographic information (left), academic progress indicators (center), and educational interventions (right).


Educators answer specific questions like "how are 3rd grade students doing on reading assessments?" and "are students on free lunch programs equitably distributed between 5th grade classrooms?" This is useful for understanding progress for groups of students, and also for identifying particular students in need of targeted interventions.


Data can be exported as a CSV for more sophisticated analysis.

Classroom rosters

Classroom teachers can see rosters of all students in their classroom, calling out high-need students and letting them jump into the student's case history and record of previous assessments and interventions.


Student profiles

Individual student profiles show how students are progressing on core academic skills, as measured summatively by MCAS or on more frequent formative measures like STAR assessments.


Student profiles also contain the full case history of demographic information, attendance and behavioral support.


Capturing meeting notes and interventions

It's one thing to have data, but acting on it to improve student outcomes is what really matters. Schools with regular student support meetings for at-risk students can track interventions like additional tutoring hours, attendance contracts or social skills groups. This is a building block to close the loop and monitor how effectively these interventions are serving students.


It also allows capturing meeting notes as part of the student's record, which is particularly important on interdisciplinary teams.


We'd love your help! Take a look at CONTRIBUTING.md for more information on ways educators, developers and others can get involved and contribute directly to the project. You can also learn how to join our online chat channel and submit pull requests and join us in person at our weekly hack night with Code for America, in Kendall Square, Cambridge.

How it works

The project is a Rails app with a Postgres database. There are background tasks that replicate data from the Aspen SIS system and STAR assessment system into the Postgres database. This enables rapid iteration and experimentation on new product features with minimal risk to these existing production systems. The Postgres database is the system of record for unique data captured by the Student Insights product (eg., notes from clinical meetings and information about targeted interventions that students are receiving). Authentication is handled by the district's LDAP service.

how it works

Admin dashboard

This project includes an admin dashboard built with thoughtbot/administrate.

The admin dashboard has one function: Allow admins (principals, assistant principals, district admins) to set user roles and permissions for other staff, in particular staff who are not classroom-based teachers.

The admin dashboard is available at /admin for educators whose admin attribute is true.

Development Environment

This is a Ruby on Rails app that uses a PostgreSQL database, and relies on React for much of the UI code.

1. Install dependencies

You'll need Ruby, Postgres and yarn. See our local installation on OSX or Linux guide.

One you have those set up, you can install the Ruby and JavaScript dependencies with:

$ bundle install
$ yarn install

2. Create database tables and seed them with demo data

bundle exec rake db:create db:migrate db:seed

This will create demo students with fake student information. See the demo site above for the set of educators you can use (or look at test_pals.rb).

If you are willing to run a longer (~10 minute) task that will generate ~600 students to more closely approximate one of our pilot schools, set ENV["MORE_DEMO_STUDENTS"] = 'true' before running the seed task.

3. Start the app

Once you've created the data, start the app by running yarn start from the root of your project. This runs two processes in parallel: the Rails server and a Webpack process that watches and rebuilds JavaScript files. When the local server is up and running, visit http://localhost:3000/ and log in with your demo login information. You should see the roster view for your data. You can stop both processes with command+c like normal, and look at package.json if you want to run them in individual terminals.

4. Run the tests

This app uses Rspec for Ruby tests and Jest for JavaScript tests.

For Ruby code, to lint and run the tests do:


For Jest, run the tests continually in watch mode with:

yarn test

There's also rubocop and eslint for linting. Run them at the command line like this:

yarn lint

Or add them into Sublime with SublimeLinter-eslint and SublimeLinter-rubocop.

If you miss something, tests will run on any pull request you submit, and after merging to master as well.

5. Write code!

This project is a Rails app and has a typical Rails project structure. If you'd like to get up to speed on Rails, we recommend checking out their great documentation. The only difference is that JavaScript code is not managed by the Rails asset pipeline, and is built separately by Webpack.

It also uses React for much the user interface code. If you'd like to get up to speed on React, we recommend their great documentation, and the Tutorial and Thinking in React pages in particular.

JavaScript code is written in ES6 syntax and JSX. The build process uses the the react-app Babel preset (the same as create-react-app).

If you use Sublime Text Editor, we include the studentinsights.sublime-project file to standardize minor things like tabs vs. spaces, indentation, and generally make it easier to work with our folder structure. Go to Project --> Open Project and select that file to load it. Sublime remembers which project you were last in, so you only need to do this once. (Here's some background info on how projects work in Sublime).

We also recommend Sublime Package Control and these packages Babel, Sublime Linter and SublimeLinter-contrib-eslint. These will give you nice syntax highlighting and show you linter errors right in Sublime!

6. Use the product locally

Users use IE11, so if you're trying to manually test locally or the production site, you should too! If you have a Mac or Linux box, you can use free VMs designed for just this purpose and run them on VirtualBox: https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/.

Useful tidbits:

  • Visit get.adobe.com/reader in the VM to install a PDF reader
  • These virtual machines expire after 90 days, so take a snapshot right away and rollback when it expires (make sure to log out of Insights before taking a Snapshot, and that no student report PDFs are lying around in the VM's downloads)
  • Enable "Shared Clipboard" in the Devices menu
  • Disable the "Host Capture" key
  • Point to to access the host instance of Student Insights
  1. Use Storybook Running yarn storybook will start a storybook server on port 6006. You can use this to create "stories" iterate on UI features or components in particular states, separate from how they exist within the product. To add new stories, write a new .story.js file and update ui/config/.storybook/config.js.

Browser/OS Targeting

Category Target Comment
Browser IE 11 "Should be all IE 11 by now."
– John Breslin, Technology Department, Somerville Public Schools
OS Windows 7 and 8.1 "Maybe some Win10 next year."
– John Breslin, Technology Department, Somerville Public Schools


Deploying new code to Insights

See our guide:

Merging and deploying new code to Heroku.

Creating a new Insights instance

Creating a new Insights instance.

Heroku notes

Quotaguard Static, a Heroku add-on, provides the static IP addresses needed to connect with district LDAP servers which are firewalled. The QUOTAGUARDSTATIC_MASK environment variable is a subnet mask for routing only certain outbound requests through the static IPs. Read Quotaguard Static's documentation for more information.

Data differences between districts

District Data Source Data Import Notes
Somerville Aspen SIS Somerville IT runs the SQL scripts in the x2_export folder every night to create CSVs and dump them to an SFTP site. We import the CSVs to Insights nightly.
Somerville STAR (assessment vendor) STAR IT team runs a job when Somerville STAR assessment results come in that dumps fresh CSV data to an SFTP site. We import the CSVs to Insights nightly.
Somerville EasyIEP EasyIEP runs "change export" of IEP PDFs that have changed and sends them to an SFTP nightly. Somerville IT runs a job to copy those files into Aspen and another job to copy those files to an Insights SFTP site. We import the PDFs to Insights nightly.

Feature differences between districts

District Feature Area Feature Notes
Somerville School Overview Page Somerville High School Housemasters are requesting a feature that will let them sort students by House. (More info on houses here.)


Here are some notes on maintaining, troubleshooting and performance.

Response latency

Look in the Heroku metrics panel.


You can use heroku-pg-extras to get helpful diagnostic information about slow queries, index usage, and table scans.

More information