DEVELOPER DOCUMENTATION

Update an assigned LMS course

Publish a corrected immutable LMS version, preview its live impact, and roll it out to existing learners without duplicate To-dos or unrelated progress loss.

OpenTrain keeps published course versions immutable for auditability. That does not mean active learners must remain permanently on the first version they received.

The lifecycle has two explicit steps:

Publish creates a new immutable version. Existing assignments remain unchanged.
Rollout advances an explicit set of active assignments to that version using their current live state.

What rollout preserves

At apply time, OpenTrain re-reads and independently classifies every selected assignment:

safe assignments advance immediately with compatible lesson progress carried forward;
a learner actively answering an assessment is queued until the next safe boundary;
submitted attempts remain pinned to the form and scoring rules under which they were submitted;
already-current and terminal assignments are skipped idempotently;
incompatible assignments are reported individually instead of resetting the whole audience;
no learner assignment or Project To-do is canceled or recreated.

Preview uses the same classifier but is informational. Learners may continue working after Preview; Apply reclassifies them from current state instead of requiring the preview snapshot to remain frozen.

CLI workflow

The publish JSON response includes version.id, version.contentHash, existingAssignments.updated: false, and a machine-readable nextAction that identifies rollout Preview and Apply.

opentrain lms publish \
  --course <course-id> \
  --expected-revision <draft-revision> \
  --confirm-publish \
  --key <publish-idempotency-key> \
  --json

opentrain lms rollout preview \
  --course <course-id> \
  --course-version <new-version-id> \
  --expected-hash <new-content-hash> \
  --job <job-id> \
  --json

opentrain lms rollout \
  --course <course-id> \
  --course-version <new-version-id> \
  --expected-hash <new-content-hash> \
  --job <job-id> \
  --confirm-apply \
  --key <rollout-idempotency-key> \
  --json

Use --assignments <id,id> instead of or together with --job when the employer approves only specific assignments. An organization-wide implicit audience is not allowed.

Read the durable outcome:

opentrain lms rollout status \
  --course <course-id> \
  --course-version <new-version-id> \
  --job <job-id> \
  --json

opentrain lms rollout receipt \
  --course <course-id> \
  --op-key <rollout-idempotency-key> \
  --json

The receipt reports updatedNow, queued, alreadyCurrent, skippedTerminal, blocked, and failed, plus assignment-level reasons. Reusing the same idempotency key with the same request replays the original receipt. Use a fresh key only when intentionally retrying isolated failed assignments after correcting their cause.

MCP workflow

Use the same lifecycle through MCP:

opentrain_lms_publish_course
opentrain_lms_rollout_preview
opentrain_lms_rollout_course_version
opentrain_lms_rollout_status or opentrain_lms_rollout_receipt

Every tool returns the canonical API result in structured content. Branch on typed outcome fields rather than parsing the human summary.

REST workflow

The canonical endpoints are:

Method	Endpoint	Purpose
`POST`	`/api/public/v1/lms/courses/{courseId}/publish`	Create the immutable version and return its rollout next action.
`POST`	`/api/public/v1/lms/courses/{courseId}/rollout-preview`	Read-only, live informational impact.
`POST`	`/api/public/v1/lms/courses/{courseId}/rollout`	Confirm and apply to an explicit audience.
`GET`	`/api/public/v1/lms/courses/{courseId}/rollout`	Read latest status without remembering the key.
`GET`	`/api/public/v1/lms/courses/{courseId}/rollout/{operationKey}`	Read one durable receipt and its live queued count.

See the course rollout API reference for request shapes.

Completion checklist

Before reporting that the update reached learners:

confirm the target immutable version ID and content hash;
review the exact job or assignment audience;
inspect blocked and failed assignment-level reasons;
confirm eligible learners moved to the new effective release;
monitor queued learners until they cross a safe boundary;
verify no submitted attempt was regraded and no duplicate Project To-do appeared.