How provisioning works
A course has to be set up in your tool before students can work in it there — content copied in, an assignment record created, whatever your tool needs to exist before the first student clicks. Voshi drives that setup through a second endpoint you register: the Provision URL.
Provisioning has two levels, and each happens once:
| Level | Claim | Fires when |
|---|---|---|
| Your tool in the course | provision.context | The first time anyone opens your tool anywhere in that course. |
| A location in the course | provision.location | The first time anyone opens that particular location in that course. |
Both can be asked for in the same request — the usual case being an instructor placing your tool in a brand-new course.
The lifecycle
- Voshi asks you to set up. The request arrives at your Provision URL as a
POSTfrom Voshi's server, carrying the same singlelaunch_datafield a launch carries. Theprovisionclaim says which levels to set up. Voshi asks once per level, and asks again only if about three hours pass with no answer — see You are asked once. - You answer
204immediately and do the work in the background. See Receiving provision requests. - You
PUTeach provision URL as that level finishes. That is what marks the level ready. - Launches flow normally from then on. The next launch of that course, or that location, arrives at your Callback URL like any other.
Until a level is provisioned, launches don't reach you
Voshi holds those launches itself rather than forwarding them. Whoever launches sees a "Provisioning" page — "Setting up resources for this location. Please try again in a few minutes." — and once your calls land, a relaunch gets them into your tool. The page doesn't refresh itself; the next launch is what moves them along.
A class never lands in a half-configured course, and your receiver never sees a launch for a course you haven't finished setting up.
Who triggers it, and who can finish it
Normally the instructor placing your tool triggers setup: Voshi calls your Provision URL as soon as they confirm the placement, before any student can click it. That's the path to design for.
Any launch of a not-yet-provisioned level can start setup, though — a student's included. The PUT that marks a level ready authenticates with the request's own api.token, which works whoever triggered it: it is a provisioning token, issued for this job and good for a fixed 3 hours. Finish within that window. If you don't, Voshi assumes the job died and asks again on the next launch, with a fresh token.
The user in the request is whoever triggered setup, and when that is a student the name and email fields are null. If your setup needs to know the instructor — to look up their account, say — don't depend on the triggering launch for it: design for the normal path, where the instructor placing your tool through the Voshi deep linking dialog is the trigger.
The course and location rows open at provisioning
The context and location storage rows stay closed until the matching level is provisioned; the member and member_location rows are open from the first launch.
Useful side effect: the finish call takes an optional body. PUTting {"weeks": 14, "term": "fall"} to a provision URL both marks the level ready and writes that JSON as the level's opening storage row, in one call.