Skip to main content

Importing data into Administrate

Updated

Purpose: This article introduces the Data Import tool: what it does, when to use it, how an import runs, and where to find the step-by-step guides for the most common imports.

Contents

What the Data Import tool is

The Data Import tool creates or updates records in bulk from a spreadsheet. Each row in your file performs the same action you could do on screen, one record at a time, with the same validation and business rules. It supports Accounts, Contacts, Events, Course Templates, Registrations, Resources, and most other record types.

Because the tool is built directly on Administrate's API, new fields and record types appear in it automatically, including your custom fields, which get their own columns on the template.

When to use it, and when not to

Use the Data Import tool when:

  • You are loading data at scale, such as bringing accounts, learners, or a course catalog across from a previous system.
  • You are creating many similar records, such as a season of scheduled events.
  • You are updating many records at once, such as correcting a field across thousands of contacts or cancelling a batch of events. See Choosing your import workflow for how bulk updates work.

Prefer the normal screens when you are touching a handful of records: the import's power comes with responsibility, because a mistake in a file is applied at file scale. There is no undo; see How processing works.

Before you start

  1. Decide what you are importing and whether you are creating or updating. This is the most important decision; get it wrong and creates become duplicates or updates fail. See Choosing your import workflow.
  2. Prepare your file. You can use the provided Excel template (recommended, with dropdowns for valid values), a report exported from Administrate, or your own file. See Prepare your file for import.
  3. Plan a pilot. For anything large, import a small subset first, verify it, then run the rest.
  4. Check for connected systems. If an integration syncs the records you are about to touch, read the next section first.

Importing when other systems are connected

If your instance is integrated with other systems, such as a CRM syncing accounts, an HR platform syncing contacts, or an LMS integration creating learner records, imports need extra care, because the import and the integration are both writing to the same records.

Work out who owns the data before importing.

  • If the other system is the source of truth for a record type, make corrections there and let the integration bring them across. Importing changes into Administrate for synced fields at best creates a temporary difference and at worst a conflict: a one-way inbound sync can overwrite your imported values the next time it runs, and support and reporting will show values that no longer match the source system.
  • Do not create records the integration also creates. A create import for accounts or contacts that an integration owns produces duplicates the integration cannot match, because the imported copies lack the external IDs the sync uses to recognize its records.
  • External IDs are the connection. Where records carry an external ID from another system, treat it as the key both systems use to recognize the same record: never invent, reuse, or edit external IDs in an import file. The upsert-by-external-ID actions exist precisely for controlled imports keyed to another system's IDs; see Choosing your import workflow.
  • Imports behave like on-screen changes to outbound integrations. Each imported row runs the same actions as editing the record on screen, so changes can flow onward to connected systems and fire the same automation. A large import is therefore also a large outbound event; coordinate timing with whoever owns the integrations.

When in doubt, ask which fields on the entity are synced and from where, and keep those columns out of your import file entirely. Blank columns leave existing values untouched, so omitting synced fields is safe.

Running an import

Navigate to Settings, then Import Tool, and click Import Data.

  1. Choose the record type (for example Events or Contacts) and the action (for example create or update).

administrate-step-1.png

  1. Upload your file and match its column headers to Administrate fields. Most match automatically. Value matching lets you map specific values in your file to Administrate's values, including giving blank cells a default.

administrate-import-headersmatching-screen.png

  1. Review the validation results. File structure, required fields, mapping, and common formatting problems (dates, email addresses, country codes) are checked before anything is imported, and many issues can be fixed on screen.

administrate-import-screen1.png

  1. Submit. The import is queued and processed in the background.

One thing validation cannot check upfront: lookup fields, which reference other records (an event's course template, a contact's account). Those are resolved while the import runs, so a value that does not match an existing record fails as a row-level error. Make sure referenced records exist before you import. See Identifiers, Lookups, and Matching Rules.

How processing works

  • Imports are processed in the background in cycles of up to 200 rows roughly every five minutes, so large files advance at about 2,400 rows per hour. A 10,000-row file will take a few hours; this is normal.
  • Partial success is normal. Each row succeeds or fails on its own. A failed row does not stop the rest.
  • When the import finishes you get a success file (what was created or updated, with each record's identifier) and a failure file (what went wrong, row by row). Correct only the failed rows and re-import that subset.
  • There is no rollback. Rows that succeeded stay applied. This is why the pilot-first habit matters.

For the deeper explanation, see Import Processing Model (How Imports Behave).

Verifying imported data

After an import completes:

  • Confirm the expected record counts.
  • Review the failure file and any warnings.
  • Spot-check records in the application, especially lookup fields and relationships.
  • For updates, confirm a few records changed exactly as intended and nothing else changed. Blank cells in an update never change existing data; see How updates treat blank cells.

Guides and reference

Not sure which record type, action, or columns a task needs?

Step-by-step guides for the most common imports:

How the system behaves:

Related articles