Most import failures are caused by lookup and matching issues, not system errors.
Identifiers
Administrate uses a combination of:
- System IDs (internal identifiers).
- Natural keys (such as email address or name combined with context).
Which identifier is valid depends on the object being imported and the action being performed.
Lookups
A lookup is a reference from one object to another.
Examples include:
- Linking an Event to a Course Template.
- Assigning an Instructor.
- Associating a Location.
Lookup values must match existing records exactly.
Matching rules
- Matching is typically case-sensitive.
- Whitespace and formatting matter.
- Values must already exist unless the import action explicitly creates them.
If a lookup value does not match an existing record, the import row will fail.
A lookup must also match exactly one record. If a value matches several records — for example a Course Template title shared by two templates — the row fails rather than picking one arbitrarily. Use a unique identifier such as a code or ID in that case.
Common causes of failure
- Referenced records do not exist.
- Names differ from system records.
- Incorrect identifiers are used for the selected action.
- Mixed identifier types are used in the same column.
Key principle
An import succeeds only when every lookup can be resolved unambiguously.
Understanding this principle prevents most import issues.