Prepare the import file
Most import failures come from the import file, not the import dialog. This guide explains what the file needs to contain before you upload it in Admin.
Before you start
- Use only one object type per import file.
- In an Add import, the columns
extIdandtypesare required, together with all mandatory fields for the object type.- Ext IDs are not generated if you leave them empty. The simplest option is to reuse a unique value from one of the other columns, for example the person ID.
- In a Replace import, use the current ext ID of each object, so the import updates the right object.
Column structure
Column names must match the expected names exactly, and they are case-sensitive. Use extId, not extID, ExtId or any other variation.
Start from an export
Before you create an import file, export the object type you want to import. Use the exported file as your template. It already has the correct column names and structure, so you don't have to guess or type the headers yourself.
Example file
A typical object import file is an xlsx file with one row per object. This example imports a student:
| Column | Example value | Purpose |
|---|---|---|
extId | gunnar.haugen | The unique ext ID of the object being created or updated |
field:person.id | gunnar.haugen | Field value written to the object |
field:person.name_first | Gunnar | Field value |
field:person.name_last | Haugen | Field value |
field:person.email | gunnar.haugen@timeedit.net | Field value |
field:person.campus | North Sea | Field value (links to a Campus object) |
types | student | The object type to create |
relations | course_occurence.MAD001_2026_S1|course_occurence.ARC001_2026_S1|... | Ext IDs of other objects to relate this object to |
Ext IDs drive relations and memberships
This is the most important rule in the file: relations and memberships are never set by internal system ID. They are always set by ext ID.
The relations column on a student row lists the ext IDs of the course occurrences that the student should be related to or a member of. During the import, each ext ID is matched to an existing object, and the relation or membership is created to that object.
If no object with that exact ext ID exists in the database, for example a course occurrence that has not been created or synced yet, that relation fails. You see the failure when the file is validated or when the import runs.
Why consistent naming matters
Conflict control depends on the same ext ID based relations and memberships. That is why ext IDs need to follow the same naming in customer integrations and in manual imports in Admin.
A missing or misspelled ext ID does not just fail one field. It can silently break a membership that conflict control needs later.
Multiple relations in one cell
One object can be related to, or be a member of, several other objects. To do this, put several ext IDs in the same cell and split them with a separator character.
Example value for one student:
This one cell creates four course occurrence relations.
Use pipe as the separator
Use the pipe character (|) as your separator, not a comma or a semicolon. Pipe almost never shows up in real data such as names, emails, IDs or course titles.
A comma is risky because it often appears in course titles, addresses and some name formats. It can split a multi-value cell in the wrong place without any warning.
You choose the separator in the import dialog after you upload the file.
