> ## 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.
# Add Roleplays to a Course
> Wire individual Exec scenarios up as LMS activities using the scenario_id custom parameter.
Once your LMS is [connected to Exec](/lti/connect-lms), every roleplay activity you add to a course points at exactly one Exec scenario. The scenario is identified by a **custom parameter** on the LTI activity called `scenario_id`.
The LMS holds the activity wrapper (title, due date, gradebook column); Exec runs the actual scenario.
***
## What you need before you start
* The Exec scenario must already exist in the workspace that's connected to the LMS.
* You need the scenario's **`scenario_id` custom property** — Exec gives you this with one click on the scenario page (see below).
### Copy the custom property from the scenario page
Once you've connected at least one LMS, every scenario page in Exec shows the LTI custom property at the bottom for admins. Open the scenario in Exec, scroll to the bottom, and click **Copy** next to the **LTI custom property** row.
The copied value looks like `scenario_id=discovery-call-practice` — exactly what your LMS expects in the activity's **Custom parameters** field. Paste it as-is.
The custom property row only appears for workspace admins, and only after at least one LMS is connected. If you don't see it, [connect an LMS first](/lti/connect-lms).
***
## Add an LTI activity to a course
The exact menu names vary by LMS, but the pattern is always the same:
In your LMS course editor, add a new activity and pick "External tool", "LTI 1.3 tool", or whichever phrasing your LMS uses. Select **Exec** from the list of preconfigured tools.
Use a title learners will recognize — e.g., "Discovery Call Practice" or "Objection Handling Roleplay". This is the link text learners click in the LMS.
Open the scenario in Exec, scroll to the bottom of the scenario page, and click **Copy** next to **LTI custom property**.
Back in your LMS, find the activity's **Custom parameters** field and paste. It should look like:
```
scenario_id=discovery-call-practice
```
Each activity points at exactly one scenario. If you want to assign a learner three roleplays, add three LTI activities, each with its own `scenario_id`.
To send roleplay scores back to the LMS gradebook, mark the activity as graded and pick a maximum score (Exec scales the percentage you earn against this value). The exact toggle varies by LMS — see [Grade passback](/lti/grade-passback) for details.
Save and publish. Learners will now see a clickable activity in their course. When they click it, the LMS launches Exec, signs them in automatically, and drops them into the scenario.
***
## What learners see
When a learner clicks the activity in the LMS:
1. The LMS hands the launch off to Exec.
2. If the learner has never used Exec before, an account is provisioned automatically and added to your workspace as a Member.
3. They land directly on the scenario page, ready to start.
4. If they aren't signed in to Exec in their browser, they're bounced through Exec's login screen first; after signing in, they land on the same scenario.
The handoff link from the LMS is single-use and expires after **30 minutes**. If a learner clicks the activity but doesn't follow through, the link is silently invalidated — they can re-click the activity in the LMS to start fresh.
If a learner is signed into Exec as a different user than the one their LMS account is linked to, Exec refuses to open the scenario as the wrong user. They'll see an error asking them to sign out of Exec (or use an incognito window) and click the LMS activity again.
***
## How user accounts get linked
Exec keys learner identity by **(LMS issuer, sub)** — the platform's stable user ID — never by email. This means:
* A learner whose LMS email later changes still maps to the same Exec account.
* Two learners with the same email on different LMSes map to two distinct Exec accounts.
* The first time a learner launches from your LMS, Exec checks whether the email already belongs to an Exec account. If it does, that account is bound to the LMS identity. If not, Exec provisions a fresh account.
Learners launched via LTI are added to the connected workspace as **Members**. Promote them to higher roles in **Workspace settings → Users** if needed.
***
## Custom parameter reference
Exec recognises the following custom parameters on an LTI launch:
| Parameter | What it does |
| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `scenario_id` (or `scenario`) | **Required.** The slug or numeric ID of the scenario to open. Scoped to the connected workspace — slugs are unique per workspace. |
If you'd like Exec to support additional custom parameters (e.g., for assignment groups or skill mappings), [let us know](mailto:hello@exec.com).
***
## Next steps
See how roleplay scores flow back into the LMS gradebook.
Diagnose launch failures using correlation IDs.
***
## Getting Help
Need help wiring up a course? Contact us at [hello@exec.com](mailto:hello@exec.com).