Skip to main content
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:
  1. Publish creates a new immutable version. Existing assignments remain unchanged.
  2. Rollout advances an explicit set of active assignments to that version using their current live state.
Do not stop after publishing and report that assigned learners cannot receive the update. Do not cancel and recreate their Project To-dos. Use rollout Preview and Apply.

​
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.
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:
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:
  1. opentrain_lms_publish_course
  2. opentrain_lms_rollout_preview
  3. opentrain_lms_rollout_course_version
  4. 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: 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.