This repository has been deprecated. VoteAmerica staff, see the internal documentation that covers the new setup.

Architectural Decision Record

Aidan Feldman, 3/10/22

Context

VoteAmerica is looking to get more young folks registered to vote, first with FutureVoter, then integrating with schools to "meet students where they're at." We established partnerships with Blackboard and Instructure (Canvas), and will start conversations with school administrators at the NASPA 2022 conference.

The minimum viable product (MVP) was to get the VoteAmerica registration form to show up in the Blackboard and Canvas learning management systems (LMSes). It turns out that most major LMSes implement a standard called LTI 1.3, which gives a consistent(ish) way to do integrations of third-party tools. This meant that the VoteAmerica tool could be built once, then theoretically be compatible with all LMS platforms. The MVP was implemented in this repository as a Flask app, and it worked.

While looking to get it working with Canvas, I came across a reference to LTI As A Service (LTIAAS). After a bit of testing, it was clear that LTIAAS could be used in place of the custom application. We made the switch and are deprecating this app.

Decision

We switched to using LTIAAS for our LTI tool offering.

Consequences

• LTIAAS supports displaying of a page in an iframe with zero custom code.
  • The pricing of LTIAAS seems very reasonable, especially compared to maintenance burden and direct cost of running a custom app.
  • LTI platforms pass the user's first name, last name, and email to the tool. The custom server used that to pre-populate the form. Getting rid of the LTI-specific backend/page means that the form is no longer being pre-populated. This seemed like a worthwhile tradeoff.
    • If we feel strongly about doing the pre-populating, we can always implement that behind LTIAAS and retrieve the user information from there.
• Good LTI support
  • LTIAAS specializes in LTI tools, meaning:
    • It should work well
    • The product, documentation, etc. should improve over time without us having to do anything
    • They are a great resource for troubleshooting
    • They (presumably) have relationships with the LMS vendors that could be leveraged
  • The LTIAAS team has been very responsive and helpful from the beginning, with a couple examples of making changes to their documentation and product immediately after issues were raised.
• The LTIAAS team is small (two people?). One the one hand, this means they are very invested in keeping clients. On the other, it's unclear how stable the business will be long term.
• We were able to set up a custom domain for our LTIAAS endpoint, meaning the service is effectively white-labeled.
  • This should avoid vendor lock-in, in that we could move off of LTIAAS without schools needing to change their configuration of URLs. (This is hypothetical; there may stored tokens or something else behind the scenes that would require migration.)

---

VoteAmerica LMS Plugin

This is a plugin to show the VoteAmerica voter registration form in learning management systems (LMSes). It uses the LTI 1.3 standard and is derived from this Flask example.

Local setup

While the app isn't super useful to run locally (an LMS provider needs to be able to access it), you can do so with the following steps:

1. Install Docker.

2. Make a file for environment variables.

   cp .env.sample .env

3. Generate a key.

4. In the .env file, put the contents of the jwtRS256.key.pub into PUBLIC_KEY and jwtRS256.key into PRIVATE_KEY.

5. Start the server.

   docker compose up --build

6. To get a publicly-accessible URL for hosted LMSes (not running on your machine) to interact with, try using Localtunnel.

   • You may want to pick a stable subdomain (with --subdomain) so that you don't have to modify your registrations each time.
   • Use this hostname instead of the Heroku ones below.

LMS setup

Blackboard

The Tool is centrally registered as a System placement. To register with a Blackboard Learn instance, use the Application ID as the Client ID.

Canvas

To add to Canvas:

1. Configure an LTI key
   1. For Key Name, enter VoteAmerica
   2. Under Method, select Enter URL
   3. Fill JSON URL with https://va-pylti.herokuapp.com/config/canvas.json
   4. Click Save
   5. Turn State to ON
   6. Under Details, copy the Client ID
2. Add the External App

Running tests

docker compose run -w /app app pytest