LTI Grade Sync

Grade Sync via AGS

The Assignment and Grade Services (AGS) specification is the LTI 1.3 standard for sending scores from a tool back to the LMS gradebook. TutorFlow implements AGS to sync scores when an internal LTI grade-sync job is queued for a launch session.

How AGS Works

AGS defines a REST API that the LMS exposes for managing line items (grade columns) and posting scores. During an LTI launch, the LMS includes an AGS claim in the JWT that provides the endpoint URLs and scopes available to TutorFlow.

AGS Claim in the Launch Token

{
  "https://purl.imsglobal.org/spec/lti-ags/claim/endpoint": {
    "scope": [
      "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",
      "https://purl.imsglobal.org/spec/lti-ags/scope/score",
      "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly"
    ],
    "lineitems": "https://canvas.instructure.com/api/lti/courses/1/line_items",
    "lineitem": "https://canvas.instructure.com/api/lti/courses/1/line_items/42"
  }
}

Score Sync Flow

When a grade-sync job runs for an LTI launch session, the following happens:

1. Student launches TutorFlow via LTI
   -> TutorFlow stores AGS endpoint and credentials in the launch session
 
2. A grade-producing flow finishes (LTI-linked test submission finalized, or an
   evaluation with clientMetadata.ltiLaunchSessionId completes) and TutorFlow
   queues platform-lti-grade-sync for that launch session
   -> The job payload carries the score and the launch session reference
 
3. TutorFlow requests an OAuth2 access token from the LMS
   POST {tokenEndpoint}
   grant_type=client_credentials
   scope=https://purl.imsglobal.org/spec/lti-ags/scope/score
 
4. TutorFlow posts the score to the LMS line item
   POST {lineitem}/scores
   Authorization: Bearer {access_token}
 
5. LMS updates the gradebook

TutorFlow handles steps 3 through 5 inside the grade-sync job.

Triggering Grade Sync from the REST API

If you are building a custom integration where evaluations are created via the REST API (rather than through the LTI UI), you can persist the launch session reference on the evaluation request.

Include the ltiLaunchSessionId in the clientMetadata field of your evaluation request:

curl -X POST https://api.tutorflow.io/v1/platform/evaluations \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "evaluationType": "open_ended",
    "questionText": "Explain the concept of supply and demand",
    "learnerAnswer": "Supply and demand is the relationship between...",
    "language": "en",
    "maxScore": 10,
    "clientMetadata": {
      "ltiLaunchSessionId": "3f0f9f52-7a1b-4b6e-9a53-2b8f6f1a2c3d"
    }
  }'

When the evaluation completes with a numeric score, TutorFlow automatically queues an LTI grade sync job for the referenced launch session. The session must belong to the same workspace as the API key — cross-workspace references are rejected by the job.

Automatic Triggers

Grade sync is dispatched automatically in two cases:

1. Test submissions — when a test opened through an LTI launch is finalized (PATCH /v1/platform/tests/submissions/{submissionToken} with isDone: true) and the submission was started with ltiLaunchSessionId, the total score is synced. The TutorFlow test-taking page wires this automatically for LTI launches.
2. Evaluations — when an evaluation created with clientMetadata.ltiLaunchSessionId completes (sync or async mode), the evaluation score is synced.

Where to Get the Launch Session ID

After a successful launch, TutorFlow redirects the browser to:

{frontend}/platform/lti/launch?sessionId={sessionId}

The launch page forwards the id to the target content as the ltiSessionId query parameter (the test-taking page passes it into the submission automatically). Read it there if you need to correlate REST-created evaluations with the LTI session.

Score Format

TutorFlow posts scores using the AGS Score service format:

{
  "scoreGiven": 8.0,
  "scoreMaximum": 10.0,
  "activityProgress": "Completed",
  "gradingProgress": "FullyGraded",
  "userId": "lti-user-sub-claim",
  "timestamp": "2026-03-25T12:05:00Z"
}

Score Fields

Activity Progress Values

Grading Progress Values

Score Mapping

TutorFlow maps the grade-sync job payload to AGS scores as follows:

Error Handling

If the grade sync fails (e.g., the LMS token endpoint is unreachable or the line item URL has expired), TutorFlow retries with exponential backoff:

After the initial attempt plus 2 retries (3 total attempts), the sync is marked as failed. The evaluation itself remains in the COMPLETED state. To check whether the grade sync succeeded, subscribe to the lti.grade_synced and lti.grade_sync_failed webhook events.

Webhook Events

When grade sync completes or fails, TutorFlow emits webhook events if you have Webhooks configured:

Example Webhook Payload

{
  "event": "lti.grade_synced",
  "sessionId": "lti-launch-session-uuid",
  "resourceLinkId": "lms-resource-link-id",
  "score": 8,
  "maxScore": 10
}

Failure deliveries use this payload shape:

{
  "event": "lti.grade_sync_failed",
  "sessionId": "lti-launch-session-uuid",
  "error": "AGS score sync failed with 401: invalid token"
}