> ## Documentation Index
> Fetch the complete documentation index at: https://docs.exec.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grade Passback

> How Exec roleplay scores flow back into your LMS gradebook automatically.

When a learner finishes a scenario launched via LTI, Exec posts the score back to your LMS gradebook automatically. No manual export, no CSV uploads. The mechanism is the LTI [Assignment and Grade Services 2.0](https://www.imsglobal.org/spec/lti-ags/v2p0) (AGS) standard.

***

## How it works

```
Learner completes a roleplay
  ↓
Exec grades the session
  ↓
If a higher score → Exec POSTs the new score to the LMS lineitem
  ↓
LMS updates the gradebook
```

The flow is fully automatic — no action needed on the learner's or admin's side once the LMS activity is configured as graded.

### Best-of-N

Exec only sends a score if it's **higher than the previous one** sent to that activity. If a learner scores 60% on their first attempt and 80% on a retake, the LMS gradebook will show 60% then 80%. If the third attempt drops to 70%, no update is sent — the gradebook stays at 80%.

This matches how most learners and managers expect retakes to work: the gradebook reflects the learner's best effort, not the most recent attempt.

### Score scale

Exec roleplays produce a score on a 0–100 percentage scale. When the LMS lineitem has a different `scoreMaximum` (e.g., the activity is worth 10 points), Exec scales the percentage to the LMS's maximum before posting:

| Roleplay percentage | Activity worth in LMS | Posted to gradebook |
| :------------------ | :-------------------- | :------------------ |
| 80%                 | 100 points            | 80                  |
| 80%                 | 10 points             | 8                   |
| 80%                 | 1 point               | 0.8                 |

### What gets posted

Each grade post tells the LMS:

* The score on the activity's scale.
* **Activity progress: Completed** — the learner finished the activity.
* **Grading progress: FullyGraded** — the score is final, not pending review.
* A timestamp.

LMSes use these flags to decide what to display in the gradebook. A score with `FullyGraded` shows up directly in the column; one marked otherwise might show as "needs review".

***

## Set up grade passback

Grade passback works automatically as long as two things are true:

1. The LMS activity is configured as graded.
2. The LMS granted Exec the AGS score scope when registering the tool.

### Make the activity graded

In your LMS, when adding the Exec LTI activity to a course, mark it as graded and assign a maximum score. This causes the LMS to create a gradebook column (a "lineitem" in LTI terms) and pass its URL to Exec on every launch.

The exact toggle varies by LMS — look for an option like "Accept grades from the tool", "Graded unit", or a "Points possible" field on the activity. If the activity isn't graded, Exec simply skips passback — there's nowhere to send the score.

### Confirm the AGS scope is granted

When Exec is registered in your LMS, the LMS chooses which AGS scopes (read scores, write scores, manage lineitems) to grant. Exec uses three scopes:

* `https://purl.imsglobal.org/spec/lti-ags/scope/score` — required for passback
* `https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly`
* `https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly`

For dynamic registration, all three are requested automatically. For manual configurations, make sure your LMS's tool settings enable AGS / "grade sync" — usually under a Services or Scopes section in the External tool config.

If the score scope isn't granted, Exec records the launch but skips the grade post (silently — no error).

***

## Verify it works

The fastest way to verify grade passback is end-to-end with a test learner:

<Steps>
  <Step title="Add the LTI activity to a test course">
    Use a course you can safely add and remove learners from.
  </Step>

  <Step title="Enroll a test user">
    Use a real LMS account, not the admin account.
  </Step>

  <Step title="Launch and complete the scenario">
    Click the activity in the LMS, run through the roleplay, and let it grade.
  </Step>

  <Step title="Refresh the gradebook">
    The score should appear within a minute or two of the roleplay being graded. Most LMS gradebooks refresh on page load.
  </Step>
</Steps>

If the score doesn't appear, see [Troubleshooting](/lti/troubleshooting#grade-passback-issues).

***

## What's not supported

* **Two-way comments** — Exec doesn't push the AI coach's qualitative feedback into the LMS gradebook. Learners view feedback in Exec; the LMS only stores the numeric score.
* **Pending / partial grades** — Exec only posts when a session is fully graded. Sessions that are still being processed don't show up in the LMS gradebook.
* **Manual override from the LMS** — Edits to the score made directly in the LMS gradebook stay in the LMS. Subsequent passes from Exec will overwrite them only if the new Exec score is higher than the last value Exec posted.

***

## Getting Help

Grade passback issue? Contact us at [hello@exec.com](mailto:hello@exec.com) and include the LMS name, the scenario, and the user who launched the activity.