Concepts
A "thing" your app 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 app provides.
Every graded item in your app 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 apps 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 app provides.
- A digital textbook titled Introductory Law that your app publishes.
An app that provides only one "thing" should define a single location.
Internal and external identifiers
Every location has two IDs, and both arrive in every launch:
| ID | Assigned by | What it's for |
|---|---|---|
| extid | Your app | The primary way your app identifies a location. A location is found by app id + extid. |
| location id | Voshi | Voshi's internal identifier. These start with the letter I and are unique across the entire Voshi ecosystem — across apps, schools, and courses. |
Your app 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 apps identify locations — during instructor linking and during student launches.
An extid is how your app 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 app, not by Voshi and not by the LMS. That is deliberate: it means your app 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 app 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 app? 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 deep linking, when an instructor adds links to your app in their course, Voshi asks your app for the locations it currently offers. Your app answers with one or more extids (plus names, descriptions, points, and so on), and Voshi presents them to the instructor as the available links within your app. 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, Voshi sends the linked extid to your launch receiver. Your app reads the extid and shows the matching resource, quiz, or tool.
- When your app posts a grade back, it names the launch by its
launch_id. Voshi resolves the course, the student, and the gradebook column from that launch — so the extid you placed is what decides where the score lands.
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 app 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 app, 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 app data 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 app 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 app is never notified when any of that happens.
Your app 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 app. - 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 app. Identify your resources by extid.