Interfaces for classroom groups

Create a suite of interfaces for supporting the creation and management of a TPEN group that represents a classroom group.

Accommodations

The core User Roles of Owner, Leader, and Contributor need to be extended to include Instructor, Student, and Assistant at a minimum. There may be a case for student groups or other types of subdivisions.
The core Permissions may need to be extended to accommodate unique combinations for texts.
The Project may need to include references to the annotations that are part of a "submitted assignment" versus in-progress.
An additional interface to the generic "new group member" interface will be needed to apply these new roles and perhaps visualize the group members differently depending on the viewing User's Role.
A replacement of the default Project creation interface to establish default line identification, default group type, transcription interfaces, etc.
A replacement of the default transcription interface that shows contributions based on User Role. An Instructor would be able to see anything and create/edit an "answer key" while a Student would be able to see the shared lines boundaries, but no one else's contributions.
Consider interfaces for managing metadata for the group: recording scores, generating assignments, listing tasks.

Membership

Owner is the User who creates this Project and may not be the person "in charge". By default, the Owner is the Leader upon creation, but this can be changed.
Leader is a default Role so it should be preserved, even if assumed by another role like Instructor.
Contributor is a default Role, but it may allow too much interaction for Students and might be taken off of these Users.
Instructor can manipulate the Project, pages, scores, membership, etc. and view everything.
Assistant may classify a TA or other User who may have a set of moderated abilities based on the Instructor's needs. For example, a TA may be able to comment on transcription assignments but not enter grades, create new line boundaries but not answer key content, and may see assignments without student identifiers included on screen.
Student are contributing Users who may not be allowed to change page order, edit or remove line boundaries, but can add content. The Students probably cannot see other contributions (unless there is some "Reading Group" established) and do not directly access the "answer key" transcribed by a TA or Professor. Students' access may be time-limited, for example, or a Student may want to create a private copy of a Project to preserve.

Permissions and Roles

The "Roles" for a member of a Project match those listed above, but mean nothing without the Permissions applied. The Permissions are what is checked by the Interface to allow access to the various resources or determine what visualizations might be needed. A newly created Project (if otherwise unconfigured) has an OWNER/LEADER by default, though only the OWNER is required and will always be applied to a Project. OWNER is a superadmin and can do anything at all, including reassigning the OWNER. LEADER is a very generous default and allows for managing all Project resources, configuration, and membership.

Roles and Permissions, however, are scoped to the Project and can be set to anything at all. There is a still undefined set of shared permissions that will allow interfaces to understand each other's restrictions, but customization is always allowed.

User Stories

Arthur is teaching a graduate group of paleographers and would like to setup three different manuscripts for their study.
1. He will bound the lines, trim the documents down to a few pages, and add a transcription;
2. He will invite paleographers to contribute by annotating, but not allow them to change line boundaries;
3. Each paleographer will commit their attempt at transcription to him for evaluation and comment.
Beula is setting up a course for high school students who are transcribing personal correspondence during the American Civil War.
1. She would like a set of about a dozen short letters for study, allowing access only after the assignment is active;
2. She wants students to contribute only transcription text, without changing bounding boxes;
3. Students can only see their own work, and have access to a progress report for all the assignments;
4. She would like an automatic response were available for the students, telling them which transcribed words match the answer key.
Corven is a member of a reading group for Old Irish Texts and is inviting others to join.
1. They own the Project, but would like others to be able to add interesting pages or short texts to the collection;
2. Anyone in the group can modify the content, including removing pages, modifying line boundaries, etc.;
3. It might be possible to look at others' attempts, but there is no "answer key" and they each should only see their own work at first.

Lacunae (fancy manuscript word for things we know are missing)

Invite to group is not possible right now but that is a goal for August that we are confident we will meet.

Project-for-Interface Data Model is not defined yet. There are some documents describing expectations, but as very few Interfaces exist yet, this will evolve. An example of this is in https://github.com/CenterForDigitalHumanities/TPEN-services/issues/114 where a Project will be created with a manifest (which may be a Manifest or Collection), tools, options, and contributors with all the members and permissions.

Entity Classes and methods for Interfaces are a utility that is partially designed but does not exist. Their use is not required, but it will help in the future to be able to Project.inviteUser( id, role ) or Line.getText( { creator: me } ) or User.assignRole("LEADER"). For now, the TPEN-Services API is the closest we get.

Permissions and Roles are not defined, but also not authoritative. On the server, the practice will be to assume Roles are not hierarchical and to seek what is allowed. That means "MODIFY_LINES_ALL" and "MODIFY_LINES_TEXT" are redundant, rather than limiting the User to only change text content and not boundaries. A Permission like "VIEW_ALL" without others is more correct than "READONLY". The expected pattern at the moment is ACTION_ENTITY_SCOPE but it may change. Custom interfaces can attach whatever custom Permissions needed, but the server will have a limited vocabulary to verify access when an update is posted.

Assignments and Committed Work is listed as a Nice-to-Have but not specified by the main grant, so there is flexibility in how this is approached, if at all. I would expect that the flexibility of the Project data model can be used to park a subdocument within a custom property like

{ "assignments" : [
    { "label"     : "Week 1 Reading",
      "range"     : "AnnotationPageID",
      "available" : "startDate"
    } ]
}

with whatever instructions or description makes sense for the special Interface to know about. Similarly, when a User commits/submits an assignment (marks a task complete or whatever) it doesn't really belong in RERUM as Linked Open Data, but its unique ID at the time can be stored in a custom field on the Project:

{ "submissions" : [
    { "memberID" : { "assignment" : { 
        "date"  : "NOW", // This may be enough with a complex query
        "uri"   : "AnnotationPageID",
        "score" : "4/6"
    } } } ]
}

Scheduled Access is problematic. Everything created in TPEN is Open by default and certainly a group member can see the resources, so if there are pages in a Project that should not be accessed, it will have to rely on some amount of trust. A Student may have no Permissions granted from the common vocabulary, so they could not see anything in the generic TPEN interfaces, but perhaps the classroom interface can honor custom timecodes. This may cause issues with updates, however. The best solution perhaps, would be to contain the students in a set of predefined interfaces that do not link out to generic TPEN until the work is completed. Maybe there is a suggestion here for a "hidden" tag or visibility property that keeps Projects out of a main page list for Users or something.

Generic Interfaces largely haven't been made yet, so there is not something to work straight off of or draw from. Some of the User stories may be fulfilled by a generic interface and not require specific work. I suggest planning to work on things that are most self-contained earlier in the year.

CenterForDigitalHumanities / TPEN-interfaces