Purpose: This article explains how Administrate processes your imports behind the scenes—what happens when you upload and map your file, how validation catches issues before any data changes, how matching decisions are made during processing, why some rows fail while others succeed, and how to run imports safely at scale.
Related: Importing data into Administrate
Contents
- Mental model: imports run in three phases
- Phase 1: File upload and field mapping
- Phase 2: Pre-import validation
- Phase 3: Execution (Processing phase)
- Matching and identity resolution
- Validation vs processing failures
- Order of operations and dependencies
- Performance and scale considerations
- Safe import strategy
- Re-imports, corrections, and recovery strategy
- Next steps
Mental model: imports run in three phases
When you run an import, you'll move through three phases: uploading your file and mapping its fields, validating your data and fixing any issues, and then running the import as a background job.
Once a validated import is submitted, it becomes a queued job. It enters a processing queue and is executed as a background task. During execution, the system evaluates each row, determines whether it should create or update a record, applies changes, and logs outcomes.
Import behavior is easiest to understand as three phases:
- File upload and field mapping — upload your file and match its column headers to the corresponding fields in Administrate.
- Pre-import validation — checks your data for issues before anything is submitted to the queue, so you can fix problems on screen or by re-uploading a corrected file.
- Execution (Processing phase) — evaluates rows, performs matching, applies changes, and records row-level results.
Phase 1: File upload and field mapping
Imports are not limited to a fixed template. You can upload your data using our provided Excel template, a report generated from Administrate, or your own file.
After you upload your file, you'll select the header row, then match each column header to the corresponding field in Administrate.
Value matching
Value matching lets you map specific values in your file to the equivalent values in Administrate. For example, matching what empty values should mean in Administrate is optional, but doing so allows you to override blank cells with default values during the import.
Using the provided Excel template
If you're using our provided Excel template, you can hover over a header cell to see additional details for that field, including its type, a description, and—for lookup fields—the values it supports.
Where to go next:
Phase 2: Pre-import validation
Before your import is submitted to the queue, Administrate validates your data and shows you the results on screen. If issues are found, you can fix them directly on screen, or correct your source file and re-upload it.
What validation typically checks
- File structure: headers are present where expected, and columns are consistent.
- Required fields: required columns are present and mapped. If a required column is missing from your file, Administrate will add it automatically and mark it as required.
- Mapping integrity: fields are mapped to compatible Administrate fields (e.g., date fields mapped to date columns).
- Data formatting: common issues such as invalid dates, invalid email addresses, or incorrect country/province codes are checked. Many of these are automatically corrected for you.
Lookup fields can't be fully validated upfront
Lookup/reference fields—values that must match existing records in Administrate—can't be validated before the import runs. Before running your import, confirm that any values used in lookup fields already exist in your Administrate instance.
Where to go next:
Phase 3: Execution (Processing phase)
Once validation passes and the import is submitted, the job runs in the queue. During processing, Administrate evaluates rows and attempts to apply changes.
Row-by-row behavior
Each row is processed independently. For each row, the system:
- Reads values from the row.
- Determines identity by applying matching rules (to find an existing record or decide to create a new one).
- Applies changes to mapped fields (create/update).
- Records a row result (success, warning, or error) for traceability.
Partial success is normal
Yes—partial success is expected. Some rows can succeed while others fail. A failed row does not automatically block all other rows from being applied.
This is why verification is essential after any import run—especially for large files or updates.
Where to go next:
Matching and identity resolution (in processing context)
Matching determines whether each row will create a new record or update an existing one. In practice, most "surprising" import outcomes come from identity resolution.
Important: This article explains how matching behaves during processing. The canonical rules (what Administrate treats as identifiers, how lookups work, and how safe updates should be performed) are maintained in these system-level references:
- Imports & Data Logic: Matching, Updates, and Safe Operation
- Identifiers, Lookups, and Matching Rules
Common matching outcomes you'll see during imports
- Unexpected duplicates created: matching keys were missing/incorrect, or values didn't match existing records as expected.
- Rows fail due to "not found" references: a lookup field pointed to a value that doesn't exist (or isn't visible in the current context).
- Records updated incorrectly: identifiers matched a different record than intended.
Validation vs processing failures (and what they mean)
Failures tend to happen in two distinct places:
A) Caught during pre-import validation
Most file, mapping, and formatting issues are now caught during the Pre-import validation phase, before anything is submitted to the queue. You'll see these flagged on screen and can fix them directly there, or correct your source file and re-upload it.
- Missing required columns
- Unmapped required fields
- Incompatible mappings (wrong data type)
- File formatting issues
B) Row-level processing errors
These occur while the job is running. Some rows are applied successfully; others fail and are logged. This is where lookup-related issues are most likely to appear, since lookup fields can't be fully validated before the import runs.
- Invalid data types at runtime that weren't caught during validation
- Lookup/reference values missing (e.g., referencing a related record that doesn't exist)
- Constraint or dependency issues (row requires a relationship that cannot be resolved)
- Conflicting values (row attempts to set a value that violates rules/constraints)
Where to troubleshoot:
Order of operations and dependencies
Imports become more fragile as relationships and dependencies increase. When you're importing data that depends on other data (or references other objects), ordering matters.
Common dependency patterns
- Lookup fields: if a row references another object by name/code/identifier, that referenced value typically must already exist.
- Relationship-driven fields: some fields are only valid when related objects exist or are in a compatible state.
- Visibility boundaries: if imports depend on records that are not visible/accessible under your current context, lookups may fail.
Recommended approach:
- Import "foundation" objects first (the entities other imports will reference).
- Then import dependent objects that reference those foundations.
- Verify results after each major step before proceeding.
Related conceptual references:
- How Administrate Works: Core Concepts & Relationships
- Accounts, Contacts, Companies, and Visibility Boundaries
Performance and scale considerations
Because imports are queued jobs, large imports can take time. The safest strategy for large updates is deliberate, staged execution.
Safe scale patterns
- Start small: run a pilot import with a subset of rows.
- Verify early: confirm matching behavior and results before scaling up.
- Prefer incremental updates: avoid "mega imports" that make rollback/reconciliation painful.
- Track what changed: keep a copy of the file used and a timestamped record of the run.
Safe import strategy (recommended)
Imports can permanently create or update records. Before running large imports—especially updates—use this checklist:
- Confirm identifiers/matching: understand what fields determine identity and updates.
- Run a pilot: import a small subset and validate outcomes.
- Verify results: reconcile imported data immediately after the run.
- Scale deliberately: proceed in batches rather than one large run.
- Keep the source: save the exact file used for traceability.
Re-imports, corrections, and recovery strategy
Because imports can partially succeed and do not automatically roll back successful rows, it is critical to understand how to safely correct issues after an import has run.
If duplicates were created
Duplicates usually occur when matching identifiers were missing, incorrect, or did not match existing records exactly.
Immediate steps:
- Stop further imports until matching logic is confirmed.
- Identify the duplication pattern (which identifier failed?).
- Use filtering or reporting to isolate affected records.
- Determine whether records should be merged, manually corrected, or updated via a corrective import.
Prevention going forward:
- Confirm identifier fields before running large updates.
- Run a small pilot import to verify matching behavior.
If some rows failed (partial success scenario)
Since partial success is expected behavior, some rows may succeed while others fail.
Recommended correction workflow:
- Export or review the error report to identify failed rows.
- Correct only the failing rows in your file (do not re-run the full file blindly).
- Re-import only the corrected subset.
- Verify results immediately.
This controlled approach prevents accidental duplicate processing of already-successful rows.
What happens if you re-run the same file?
Re-running a file depends entirely on matching behavior:
- If identifiers correctly match existing records, the system will update those records.
- If identifiers are missing or mismatched, the system may create duplicates.
Before re-running any import:
- Confirm which field(s) determine identity.
- Confirm that identifier values are stable and accurate.
- Test with a small subset if unsure.
There is no automatic rollback
Administrate does not automatically reverse successful rows if other rows fail. Once a row is successfully processed, the change is applied.
This means:
- Imports should be approached deliberately.
- Large corrective updates should be staged.
- Verification is not optional for production data.
Safe correction pattern (recommended)
If an import produces unexpected results:
- Pause further imports.
- Assess scope of impact.
- Determine whether manual correction or targeted corrective import is appropriate.
- Run a small corrective test.
- Verify before scaling.
Understanding how matching, processing, and partial success work together is the key to running imports safely at scale.