Scenario - Cancel an enrolment

Note: jurisdiction has now been added to transaction batch route.

This scenario explains how a student management system (SMS) cancels a program enrolment or subject enrolment by updating the enrolment lifecycle state to Cancelled.

It demonstrates how lifecycle changes are applied by re‑uploading enrolment resources using the previously submitted resource unique identifiers (UIDs).

Each upload must include the complete top-level resource and all current child objects. For example, the cancelled enrolment lifecycle state cannot be uploaded on it's own.

Key points

  • explains the process for cancelling an enrolment

  • cancellation applies only to the enrolment being updated and does not affect related enrolments.

    • for example, if a program enrolment is cancelled, associated subject enrolments remain active.

  • a subject enrolment may exist without a program enrolment; however, a program enrolment must have at least one subject enrolment.

  • reuses the previously submitted resource identifier.

  • Create a new transaction batch or re-use an existing transaction batch with a status of NotSubmitted.

  • describes the recommended validation integration approach:

    • request asynchronous validation once data entry is complete.

    • resolve any validation issues before re‑validating and submitting the transaction batch.

Sequence overview

An SMS creates a transaction batch, updates the enrolment status to cancelled, supplies a valid cancellation studentStatusReason (for example, Formal_withdrawal or Informal_withdrawal), completes validation, and submits the batch once validation is successful.

Sequence diagram

Note: Security and authentication flows are not shown.

Step‑by‑step flow

Step 1: Create transaction batch

Create a new transaction batch or re use an existing transaction batch with a status of NotSubmitted.

  • SMS action:
    POST /vet-provider/v1/{jurisdiction}/transaction-batch
    (or re‑use an existing open batch)

  • STARS response:
    201 Created with transactionBatchToken

Step 2: Upload enrolment to be cancelled

The SMS re‑uploads the enrolment being cancelled using the same resource UID that was previously submitted.

The enrolment may be:

  • a program enrolment, or

  • a subject enrolment (including a standalone subject enrolment).

Each upload must include the complete top-level resource and all current child objects. Additionally the cancelled enrolment contains

  • StudentStatus: Cancelled

  • StudentStatusReason: a valid cancellation reason (for example, Formal_withdrawal or Informal_withdrawal)

  • changeTrackingIdentifier

Only the enrolment being updated is cancelled; no automatic changes are applied to other enrolments.

Where available, the previously returned changeTrackingIdentifier should be supplied to identify the version being updated.

Step 3: Request asynchronous validation

  • SMS action:
    POST /vet-provider/v1/{jurisdiction}/transaction-batch/{token}/validate

  • STARS response:
    201 Created (validation queued)

Step 4: Poll for validation readiness

  • SMS action:
    GET /vet-provider/v1/{jurisdiction}/transaction-batch/{token}/validate

  • STARS response:
    Current validation status

The SMS continues polling until validation processing is complete.

Step 5: Retrieve validation results (if any)

  • SMS action:
    GET /vet-provider/v1/{jurisdiction}/transaction-batch/{token}/failed-validation-results
    (pagination supported)

  • STARS response:
    Any blocking or non‑blocking validation results

Steps 2–5 may be repeated if corrections are required before submission.

Step 6: Submit transaction batch

  • SMS action:
    POST /vet-provider/v1/{jurisdiction}/transaction-batch/{token}/submit

  • STARS response:
    200 OK with status Submitted

End state

The enrolment has been successfully cancelled and submitted.