Concepts
A "thing" your tool provides that can be placed in a course.
Your own permanent identifier for a location.
An instructor putting one of your locations into their course.
Location
A location is a "thing" that your tool provides.
Every graded item in your tool should be one location, and every non-graded thing you want a student to be able to open should be one too. A location's grades land in a single gradebook column, so if you want two graded activities, you define two locations.
Most tools offer several "things" that can be placed in a course. Locations are how you define them. For example:
- A quiz on architecture in the Persian Empire.
- A currency conversion tool your tool provides.
- A digital textbook titled Introductory Law that your tool publishes.
A tool that provides only one "thing" should define a single location. Hosted tools call that one location home.
Internal and external identifiers
Every location has two IDs, and both arrive in every launch:
| ID | Assigned by | What it's for |
|---|---|---|
| extid | Your tool | The primary way your tool identifies a location. A location is found by tool id + extid. |
| location id | Voshi | Voshi's internal identifier. These start with the letter I and are unique across the entire Voshi ecosystem — across tools, schools, and courses. |
Your tool should key its own data and its own routing on the extid. The internal ID is there for correlating with Voshi's dashboard and logs.
Extid
Extids are the primary way tools identify locations — during instructor linking and during student launches.
An extid is how your tool declares that a resource exists and can be added to a course. Each extid must represent a unique "thing" that has identity and can be linked within a course.
Extids are created by your tool, not by Voshi and not by the LMS. That is deliberate: it means your tool controls what "location" means inside your product.
Extids identify a resource everywhere
An extid should identify the same resource consistently across semesters, courses, and schools. If a quiz on Persian architecture has extid = quiz1 in one course, that same quiz in a second course also has extid = quiz1.
Defining your extids is one of the most important design decisions your tool makes. Extids are permanent and cannot be changed once they have been linked into a course. When you design your extid strategy, think through:
- Resource identity — what counts as one distinct "thing" in your tool? What things are graded?
- Cross-semester persistence — if an instructor is teaching the same course again next semester, they will likely want the same locations (perhaps with minor changes). Will these ids still be valid then?
- Provisioning - what needs to be set up (database objects, etc.) when a new course starts? When a new semester starts?
Rules for extids
- Extids may contain letters, numbers, dashes, and underscores. No other special characters.
- Extids should not normally include course-specific identifiers — no context id, semester code, or instructor id.
When extids are used
- During placement, when an instructor adds links to your tool in their course, Voshi shows them the locations your tool currently offers — each one an extid plus a label, a description, points, and so on. A hosted tool declares them in the dashboard or in its
manifest.json(see Locations); a self-hosted tool answers a request from Voshi with the list (see Serving your locations). - Extids must be assigned during link placement, at course setup time. They cannot be assigned later, during student launches.
- When a student clicks a link, the launch names the linked extid. Your tool reads the extid and shows the matching resource, quiz, or tool. In a hosted tool it is
api.location.extid. - When your tool reports a grade, the score goes to the gradebook column for that student at that location. The extid the instructor placed is what decides which column the score lands in.
Examples of extid strategies
Placement
A placement is an instructor putting one of your locations into their course — the link students click. Placements happen through a content picker that Voshi presents: the instructor sees the locations your tool currently offers, picks one, and confirms. For a graded location, that's also when the gradebook column is created.
Placement is where an extid gets attached. Everything downstream — the launches students produce, the storage rows, the gradebook column your grades land in — follows from the extid the instructor placed.
One location per thing
The rule that keeps an integration simple:
Define one location for each thing you want graded, and one location for each non-graded thing you want to show.
If it needs its own gradebook column, it's its own location. If it's a distinct thing a student can open, it's its own location. Nothing else needs to exist.
Don't design around placing the same location more than once in a course. A location is one "thing" in your tool, and it should correspond to one link in the course and — when it's graded — one gradebook column.
If you want two graded activities, define two locations with two extids. Reaching for two placements of the same location instead means both links point at the same resource, share the same storage rows, and compete for the same gradebook column. All grades for a location go to a single column regardless of how many links exist, so the extra placement gets you nothing and confuses the instructor's gradebook.
Duplicate placements happen anyway
Even though your tool shouldn't rely on them, duplicate links to the same location do occur, and you can't prevent them: instructors duplicate links, LMS platforms roll courses forward into new terms in their own ways, and a link deleted from one module can be added back in another. Your tool is never notified when any of that happens.
Your tool doesn't need to do anything about it — the behavior is already consistent:
- All launches carry the same
location.extid, so they all resolve to the same resource in your tool. - All of them share the same location storage rows.
- Grades always go to the first gradebook line item for that extid, so a student's score for a location always lands in the same place.
This is exactly why Voshi identifies resources by location and extid. The individual links in the course — and the LTI resource_link_id behind them — are outside Voshi's control and shouldn't carry meaning in your tool. Identify your resources by extid.