How launches work
A launch is what happens when someone opens your tool from inside an LMS course. Voshi sits between the LMS and your tool: it handles the LMS integration and hands the user to your tool with everything you need in a single signed token.
The lifecycle
- Someone launches your tool. An instructor or student clicks your tool's placement in a course. The LMS hands the launch to Voshi — your tool isn't involved yet.
- Voshi forwards the launch to you. Voshi sends the user's browser to your tool's callback URL with a
POSTof a single field,launch_data: a signed JWT identifying the school, course, user, and which of your locations was launched. - Your tool takes over. You verify the JWT, create your own session, and render whatever the user should see. From here on, the user is simply navigating your tool.
Nothing precedes step 1 for people: Voshi doesn't announce a school, course, or student before they launch, so the launch is also where your tool first hears about them. See what a launch tells you about.
Courses are the exception. The first time anyone — student, instructor, or admin — launches into a course, Voshi tells your tool to set that course up, and holds the launch until your tool says it's ready. See How provisioning works. So any launch that does land on your callback URL names a course your tool has already prepared.
The launch POST arrives through the user's browser, not from a Voshi server. That has two consequences: the JWT's signature is the only thing standing between you and a forged launch (so verify it, always), and Voshi never sees your tool's response — errors on your side are between your tool and the user.
What arrives in the launch
The JWT identifies the user (a stable ID, their course membership, and their role groups), the course, the school, your launched location, where to publish a score if this placement can take one, and URLs for your four storage storage rows. See the Launch Data reference for every field.
Three properties worth knowing up front:
- All IDs are Voshi's own IDs — stable across launches, but never the LMS's internal IDs.
- No PII on student launches. Name and email arrive only when the launching user is course staff (
manager,instructor, orassistant); on every other launch they arenull. Recognize a returning user byuser.id. - One token, one session. Tokens expire after 2 hours, but you shouldn't rely on that — trade the token for your own session on first use and don't accept the same token twice.
How placements happen (deep linking)
Instructors place your tool into their course through a content picker that Voshi presents. Your tool's only part in it is one server-to-server request: Voshi asks your Locations URL what you currently offer, and shows the instructor that list. They pick a destination, optionally rename the placement, and Voshi handles the rest (for assessment locations, a gradebook column is created as part of the placement).
Because the list is fetched at placement time, what instructors can place is always current. What arrives in a launch, though, is the copy Voshi captured when that placement was made — so drive your tool off location.extid and your own data rather than treating the launch claim as live configuration. See Concepts, Locations, and Serving your locations.