Canvas users have to manually create and join Hypothesis groups

[seanh]

See also

• Canvas is an LMS (Learning Management System) used by schools to deliver courses. (Similar to Blackboard, Moodle, Sakai...)
• Canvas source code on GitHub
• The Hypothesis Canvas app:
  • Production deployment
  • Source code
  • Canvas app Google Docs from @judell:
  • Canvas Architecture Notes
  • Installing the App
  • Using the App
  • Student Guide
  • Screencasts from @jeremydean:
  • Student walkthrough screencast
  • Teacher walkthrough screencast
• Feb 2017 Canvas spike by Nick
• May 2017 Canvas Feature Spec Sheet (google doc)
• Canvas GitHub Issues label in the product-backlog repo, including:
  • Canvas app isn't production code quality https://github.com/hypothesis/product-backlog/issues/340
  • Canvas app isn't on production infrastructure https://github.com/hypothesis/product-backlog/issues/339
  • Canvas users have to manually create and activate Hypothesis accounts https://github.com/hypothesis/product-backlog/issues/342
• #feat-canvas Slack channel
• Canvas folder on Google Drive (we should move all Canvas-related Google Docs into this folder)
• Our Instructure-hosted Canvas instance, we can use this to try out Canvas

Problem

Teachers using the Canvas app commonly create a private Hypothesis group for each Canvas course (or for large courses, maybe one Hypothesis group for each section or group within the course - this isn't 100% clear to me yet). Currently the teacher needs to:

1. Create a Hypothesis private group, including creating a unique name for the group (Hypothesis group names don't strictly need to be unique but being a member of multiple groups with the same name would be confusing)
2. Invite all of the students to join the group, by sharing the group link with them
3. Make sure that all the students have successfully joined the group

Students can't begin a group-based Hypothesis annotation assignment in Canvas until they've joined the relevant Hypothesis group.

After successfully joining the Hypothesis group, on launching Hypothesis within the Canvas exercise, each student must select the correct group from the groups dropdown menu in Hypothesis before they begin annotating. Since you can't move annotations between groups in Hypothesis, if students create (possibly many) annotations in the wrong group they need to delete them and manually recreate them one by one. The Public group (or other most recently used group) will be the default selected group, not the one created for the course.

Dependencies

• This issue is blocked by https://github.com/hypothesis/product-backlog/issues/340 and https://github.com/hypothesis/product-backlog/issues/339 - we can't implement improvements to the Canvas app until we've at least made significant progress on bringing the Canvas app up to production quality, and we can't deploy improvements to the Canvas app until we've migrated it onto our production infrastructure.

• This issue may be blocked by https://github.com/hypothesis/product-backlog/issues/342. We probably need to be able to create third-party accounts for Canvas users and log them in, before we can create third-party Canvas groups. It's probably possible to make at least some progress on this groups issue without having sorted the accounts issue first, though.

Rejected solution: publisher group

One possible solution would be to use publisher groups, as we do for publisher sites such as eLife: there is one big publisher group for each publisher, and whenever Hypothesis is launched on a publisher's site it's locked to this publisher group.

Publisher groups don't seem appropriate for the Canvas use case because rather than one small private group for each course, you would get one big public group for all of Canvas.

For example if one class had annotated a document and then later another class (perhaps taking the same course in a later semester, or perhaps a class from a completely different school) tried to annotate the same document for their own assignment they would find the first class's annotations already on the document and viewable to them. Two classes simultaneously annotating the same document in different course or schools would see each other's annotations appearing in real time. All Canvas users would be in one big group.

If we implement a publisher group for Canvas and then later implement a better solution, e.g. per-course groups, then what would we do with the existing Canvas publisher group? It would contain students annotations, which they may still want access to.

There are variations on the publisher group approach that might be possible with more work, but these don't seem a great fit either. For example separate publisher groups for each Canvas instance, or each installation of our Canvas app.

Suggested solution

When Hypothesis is launched within Canvas:

1. The Canvas app should create a private group, within the Canvas authority, for the Canvas course that the Canvas app is currently being used in, if such a group doesn't already exist.

2. The Canvas user (student or teacher) who has launched the Canvas app should automatically be a member of the group.

3. The Hypothesis client should be locked to this "course group" in the groups dropdown menu.

Questions

• When the Canvas app is launched within an assignment within a course within Canvas, what information can we get from Canvas about that course?

• How can we generate a name for the course group?

• How can we uniquely and robustly link a Hypothesis group to a Canvas course? (Probably requires a new optional field on Hypothesis groups - the Canvas course ID. Or these course <-> group links could be tracked by the Canvas app in its own database.)

• How can we find the existing Hypothesis group for a Canvas course, if one already exists?

• How can we make all members of the Canvas course automatically be members of the Hypothesis group?

  For normal private Hypothesis groups we keep a list in the Hypothesis database of all the users who're members of the group. You have to manually join the group to get your name added to this list.

  For the Public group we don't keep any such list - everyone can read the Public group and anyone with a first-party account can write it.

  For publisher groups we don't keep a list of members in the db either - anyone can read the publisher group, and any user account with the same authority as the publisher group can write it. So only eLife third-party accounts can write the eLife publisher group.

  For Canvas we probably don't want to keep lists of members of groups in our database either - we'd have to get the list of all members of the course from Canvas, and keep it in sync whenever users join or leave the Canvas course. But the publisher groups solution - all Canvas users would be able to read and write all Canvas groups - doesn't seem right either. We probably want to piggy back on the fact that we know the Canvas user has access to the Canvas course because they've launched the Canvas app within the course, and maybe have the Canvas app pass something to the Hypothesis client (which passes it to the web service) that identifies the user's HTTP requests as having access to the group (but this has problems with direct links, see below).

• How can we make share / direct links work?

  With normal private groups, when a user clicks on a direct link, they either see a "You're not authorized to see that annotation" message in the client, or they see the annotation in context, depending on whether they're a member of the group. As mentioned above we may not want to keep a list of the members of a Canvas group in the DB, we may want to piggy back on the fact that we know the Canvas user has access to the Canvas course because they've launched the Canvas app within the course, but if we do that then how will we get direct links, which launch the client outside of Canvas, to work?

  Simply hiding the share buttons in the client when in Canvas is one solution, at least for v1.

[jeremydean]

I really like the suggested solution. Thanks for you thoughtful exploration here, @seanh.

[judell]

+1. A members-read-write group in an authority is what I was hoping for. We do know, on the LTI launch, the user's real name, with Canvas institution and user id as disambiguators.

[jeremydean]

@seanh looking back on this after what i've learned in the interim, i think this is still close to the right solution. wondering if this architecture is possible, though:

• each school's LMS is given its own instance (hypothesis.instructure.com, for example) is given its own namespace
• that instance/namespace/authority is associated with an overarching private group, unlike elife which is public
• private groups are generated for all courses within that broader private namespace

so, essentially, we have a private group with private groups within it.

[seanh]

@jeremydean This "group that contains other groups" is being called an "organization" in the code right now. And sure, I think the notion of a private organization containing all-private groups might be possible.

[judell]

About a year ago I stitched together the Canvas alpha and the publisher accounts prototype, just to get a feel for those pieces working together: http://jonudell.net/h/h_canvas_auth_01.mp4

If nobody gets there first, I might revisit that in light of the new groups machinery just to see what's involved.

[ajpeddakotla]

Closing this issue but tagging it for reference in 596 and 595.