Purpose: This article is a task-to-template index for the Data Import tool. If you know what you want to do but not which record type, action, or columns to use, find your task below.
Related: Importing data into Administrate | Choosing your import workflow | Identifiers, Lookups, and Matching Rules
How to find the right import
Every import is a record type plus an action, chosen on the first step of Settings, then Import Tool, then Import Data. Because the tool is built on Administrate’s API, the record types and actions you see mirror the API: many records have sub-actions beyond plain create and update (for example, adding staff to an event, or adding prices to a course template). When a task is not covered by the obvious create or update template, it is almost always one of these sub-actions.
Once you pick the record type and action, the tool generates the template with the columns that action accepts. Download that template, or check the column headers on your own file during mapping, to see exactly what each action needs.
Task-to-template catalog
| Task | Record type | Action | Key columns |
|---|---|---|---|
| Create accounts / contacts | Account, Contact | create (createIndividual for individual accounts) | name / first name, last name, email |
| Update contacts by ID or email | Contact | update | contact ID or email, plus the fields you are changing |
| Load or update a course catalog | Course Template | create, then enrichment actions | see Import Course Templates |
| Add prices to a course template | Course Template | addPublicPrices / addPrivatePrices | course template reference, price, currency |
| Add a required achievement type to a template | Course Template | addAchievementType | course template reference, achievement type |
| Set or update required staff / required achievements on a template | Course Template | addRequiredStaff / updateRequiredStaff | see Import Course Templates |
| Create a season of events | Event | createClassroom / createLMS / createBlended | see Import Events |
| Update existing events | Event | update | event ID, plus the fields you are changing |
| Add an instructor (or other staff) to an event | Event | addStaff | see Import Events |
| Set an event’s primary instructor | Event | setStaffToPrimary | see Import Events |
| Adjust session times | Session | update | see Import Events |
| Register learners onto events | Event / Registration / Learner | registerContacts / registerLearner / registerUnnamedLearners / upsertByExternalIds | see Import Registrations and Results |
| Create login users and assign roles | User | createUser, then updateUserRoles | see recipe below |
If a record type or action you expect is missing from the dropdowns, it is usually a permissions matter: you only see what your role can perform. See User Roles.
Create login users and assign their roles
Creating a system user with a role takes two passes, because roles are set by a separate action:
- User record type, createUser action, to create the user. Required columns: first name, last name, and identity (the unique sign-in identifier). Optionally associate a contact ID and company ID, or flag the user as a super user.
- User record type, updateUserRoles action, to assign roles to the users you just created.
Importing contacts does not create login users; contacts and users are separate records.
Supplying references: names, encoded IDs, and legacy IDs
Reference columns (a course on an event, an account on a contact) can be filled in three ways, and the import tries them in this order:
- A name or code. This is the preferred and most readable option. Most references resolve by a natural identifier: contacts by email, courses by course code, locations by name or code, currencies by code. The value must match exactly one record. See Identifiers, Lookups, and Matching Rules.
- An encoded ID. A global identifier of the form
Base64("Type:number"), for exampleCourse:200encodes toQ291cnNlOjIwMA==. This is theidvalue the API returns for a record. - A legacy numeric ID. A plain internal number, which the tool encodes for you.
When you must use an ID rather than a name: a few references have no name to look up against, so a name will not resolve and you must supply the encoded or numeric ID. Course prices are the common example: there is no course-price name, so bulk price updates need the price’s ID, which you obtain from the API (query the course template’s prices) or a report export that includes it. Required achievement type IDs on the required-staff actions are likewise matched by ID only.
Why some templates have paired columns
A few templates show two columns that look like duplicates. They are a name-or-ID alias plus its authoritative partner:
- Location and Location ID. Both resolve through the same location lookup and accept a location name, code, or ID. Fill in one, not both; Location ID is the current field.
- Time Zone Name and Time Zone. Time Zone Name is the required field
and takes a standard IANA identifier such as
Europe/London(the template offers these as a dropdown). Time Zone is a legacy optional field; populate Time Zone Name.
Custom fields in imports
Custom fields appear as their own columns on the record types and actions whose form includes them, on both create and update (they are never marked required on update). If a custom field column is missing where you expect it, check that you are on an action that carries custom fields (the plain create and update templates do; sub-actions such as addStaff or addPublicPrices do not) and that the field belongs to that record type. Course and Course Template are two separate custom-field areas, so a field created against one does not appear on the other. See Custom Fields.
If your import will not progress
Imports run in the background in batches, so a large file legitimately takes a while rather than being stuck. For what “processing” and “pending” mean, the batch cadence, and genuine stuck conditions, see Import Processing Model (How Imports Behave) and Troubleshooting: Import Errors.