ClassLink rostering spec#73879
Draft
nicklathe wants to merge 1 commit into
Draft
Conversation
- Add openspec artifacts for ClassLink roster support Signed-off-by: Nick Lathe <nick.lathe@code.org>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an OpenSpec-generated specification package describing the planned implementation of ClassLink OneRoster-based rostering plus a phased migration of ClassLink authentication_id from legacy UserId to <TenantId>|<SourceId>.
Changes:
- Documented phased migration plan (login-time migration + optional bulk script) and cleanup steps.
- Defined functional requirements and scenarios for ClassLink class listing, import/sync, co-teacher verification, and 401 token refresh behavior.
- Captured proposed architecture decisions (ID formats, section code format, cache-aside district credential lookup).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| openspec/changes/classlink-roster-support/proposal.md | High-level motivation, scope, and impacted areas for ClassLink rostering + ID migration. |
| openspec/changes/classlink-roster-support/design.md | Detailed design decisions (IDs, section codes, caching + 401 recovery) and rollout/risks. |
| openspec/changes/classlink-roster-support/tasks.md | Implementation task breakdown by phase (migration, client, model, endpoints, frontend, testing). |
| openspec/changes/classlink-roster-support/specs/classlink-rostering/spec.md | Requirements/scenarios for rostering flows: list classes, import/sync, co-teacher checks, caching behavior. |
| openspec/changes/classlink-roster-support/specs/classlink-id-migration/spec.md | Requirements/scenarios for new ID format, dual-match login window, login-time migration, cleanup. |
| openspec/changes/classlink-roster-support/.openspec.yaml | OpenSpec metadata for the change package. |
|
|
||
| - `<TenantId>-<SourceId>`: Fragile if sourceIds are UUIDs or contain dashes. Rejected. | ||
| - Store in `data` JSON column: Would require extra parsing logic everywhere; the uniqueness constraint lives on `authentication_id`. Rejected. | ||
| - New `ClasslinkUserIdentity` model (like `LtiUserIdentity`): Extra schema complexity not warranted here; the uniqeness constraint is still relevant. Rejected. |
| - Store in `data` JSON column: Would require extra parsing logic everywhere; the uniqueness constraint lives on `authentication_id`. Rejected. | ||
| - New `ClasslinkUserIdentity` model (like `LtiUserIdentity`): Extra schema complexity not warranted here; the uniqeness constraint is still relevant. Rejected. | ||
|
|
||
| ### 2. `Section.code` format: `CL-<oneroster_application_id>|<sourceId>` |
| - New `Clients::ClasslinkOneRoster` REST client for the One Roster proxy API | ||
| - New backend endpoints for listing available ClassLink classes and importing/syncing a class as a section | ||
| - Updated OmniAuth callback to format `AuthenticationOption.authentication_id` as `<TenantId>|<SourceId>` (currently stores only `UserId`) | ||
| - Batch migration of all 14,392 existing ClassLink `AuthenticationOption` records to the new ID format |
| - **THEN** the system resolves the district bearer token via the cache-aside lookup, calls `/classes/<classSourceId>/students`, filters for users with `role == "student"`, creates or finds each student's account using `<TenantId>|<studentSourceId>` as the authentication_id, creates a `ClasslinkSection` with `code = CL-<oneroster_application_id>|<classSourceId>`, and enrolls all rostered students | ||
|
|
||
| #### Scenario: Student already has a code.org account via ClassLink SSO | ||
| - **WHEN** a student being imported already has a `AuthenticationOption` with `authentication_id = <TenantId>|<studentSourceId>` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR is for spec review only and not meant to be merged.
This spec was generated using Openspec. It contains the following:
When reviewing, the
proposal.mdanddesign.mdare helpful with the big picture of what will (and won't) be built. The specs define requirements and scenarios that implement the design.Links
Testing story
Deployment notes
Privacy and security