Import data with the import wizard

Data Import is the administrator's tool for loading records into xMatix from a file: you upload an Excel, CSV or JSON file, map its columns to one entity's fields, optionally rehearse the load with a dry run, then write the rows from the browser or as a background job. It is the "in" half of bulk data work — use it for a first data migration, for adding records in bulk, or to bring back a file you exported with Export data and edited, so that the records are updated instead of retyped.

Overview

The screen lives at Setup → Platform → Data → Import. Its body is the Import History table; the Start import button in the page header opens the Import data wizard. The wizard has three steps — Upload file & select entity, Map columns and Import — and every run, whether it finished, failed or was only a rehearsal, is recorded in Import History, where you can download the original file, download just the failed rows to fix them, and retry.

When to use it

• You are moving data into xMatix from another system or a spreadsheet: accounts, contacts, items, price lists, opening records.
• You need to change many existing records at once: export them with Id, edit the file, and import it back.
• You want to check a file against the real validation rules before anything is written: run a Dry run.

For a handful of records, typing them in is quicker. For a related data set (accounts and their contacts, orders and their lines), run one import per entity, parents first.

How xMatix handles it

• One entity per run. Each run writes into a single entity; related records are linked through lookup columns.
• Every row is an ordinary save. Each row goes through the same path as saving the record by hand: your access to the entity and its fields, mandatory fields, default and calculated values, numbering, validations, business rules, workflows and automation all apply, row by row.
• Rows commit independently. A failing row never undoes the good ones, so a run with errors is partly applied. You then fix and re-import only the failed rows.
• Create or update is decided per row. A row that carries a record's Id updates that record; on entities that have an External Id field, a row whose external id matches exactly one record updates that record; every other row creates a new record.
• Two ways to write. Import now runs from your browser tab in batches with a live per-row result table; Run async uploads the file and a background job does the work, so you can close the tab.

Prerequisites

• The data-import capability (setup.data.import.manage) on one of your security profiles. It shows the Import item under Setup → Platform → Data and allows the history, retry and download actions.
• Create access on the target entity — and Update access if rows will update existing records — plus edit access to the fields you import. Record- and field-level security apply to each row.
• A file in .xlsx, .csv or .json format, at most 100 MB, holding at most 50,000 data rows. Older .xls workbooks are refused: save them as .xlsx or .csv first.
  • Excel: the first worksheet is read; its first row is the header. A column with a blank header is dropped, and so is a row whose cells are all blank. Formula cells import their calculated result, and dates import as dates.
  • CSV: comma-separated, first line is the header, values may be quoted (") to carry commas or line breaks.
  • JSON: an array of flat objects; every key found in any object becomes a column.
• For related data, a load order: import parents first so that lookup columns in the child file have records to match.

Procedure

Step 1 — Open Data Import and start the wizard

Go to Setup → Platform → Data → Import. The page header reads Data Import — Import data from Excel, CSV, or JSON files. Select Start import; the Import data dialog opens at Upload file & select entity. Restart import at the bottom-left of the dialog clears the wizard and starts again at any point before a run begins.

123456 Expand

1. 1

   Step 1 parses the file locally and then asks for the target entity — nothing is uploaded yet.

2. 2

   Map Columns proposes a mapping per upload column and holds Download Template and Batch Size.

3. 3

   Import shows the preflight card and the Dry Run, Run Async and Import Now buttons.

4. 4

   Drop a .xlsx, .xls, .csv or .json file here; one file, one entity, at most 50,000 rows.

5. 5

   Restart Import clears the wizard at any step without touching data.

6. 6

   Next is enabled once a file is parsed and an entity is selected.

Step 2 — Upload the file and select the entity

Drop the file on the upload area, or click it to browse. The file is read in your browser — nothing is sent yet — and a summary card shows the file name and how many rows and columns were read. Replace file picks a different file; Remove clears it. If the file has no header row or no data rows, the wizard says so ("No columns found in the file…" or "No data rows found in the file.").

Under Select target entity, choose the entity to import into from the searchable list. The list holds every entity that allows new records. Until both a file and an entity are chosen, the main button reads Upload a file and choose its target to continue; then it becomes Next.

Step 3 — Map columns

The Map columns step shows Column mapping — <entity> with a table of every upload column: Upload column, Status, Maps to and Detail. The wizard proposes a mapping automatically, in this order:

1. Lookup by dot column — a header such as Account.Name maps to the lookup field Account, matched on the related record's Name. Status Accepted; if the part after the dot is not a field of the related entity, the status is Lookup (fallback) and the match uses Name instead.
2. Field name — the header equals a field's API name (case does not matter). Status Accepted, detail Direct field.
3. Field label — the header equals the label you see on the form (useful for custom fields). Status Accepted.
4. Close spelling — one or two characters off a field name. Status Suggested; check these before going on.

Anything else is Skipped and will not be imported. Change any row with Maps to: its first option, Skip (do not import), drops the column; lookup fields are marked (Lookup). The summary line counts how many columns are mapped and skipped.

Two controls sit above the table:

• Download template — a CSV (import-template-<entity>.csv) with one header per importable field, lookups written as Parent.Name. Starting a new file from this template avoids most mapping problems.
• Batch Size — 1 to 100 rows per request for an Import now run (default 25). Above 50, a warning says large batches may exceed the request timeout; use Run async for big files instead.

Select Import to continue (it is available once at least one column is mapped).

Step 4 — Check the preflight card

The Import step opens with Ready to import into <entity>: Total rows, Mapped columns and Batch size, followed by preflight messages:

• More than 50,000 rows: an error — the run buttons are disabled; split the file.
• More than 2,000 rows: a note that Run async is recommended.
• A column mapped to a system-managed field (such as created/updated stamps, owner or row version): a warning that it will be ignored.
• Unmapped columns: listed as ignored.
• A number, yes/no, date, time or id column whose values in the first 200 rows may not convert: a warning with the first bad value.

Required fields are not checked here; a missing mandatory value surfaces as a row error when you run.

Step 5 — Choose how to run

An Import now run depends on the browser tab. If the tab closes mid-run, the rows already written stay, and the history row can stay at Processing, because nothing on the server finishes it.

Step 6 — Read the results

Each row ends as Created, Updated, Error or — for Import now only — Transform Error (the row never reached the server, typically because a lookup value matched no record).

• Import now shows a summary such as 120 Created, 4 Updated, 3 Failed and a results table with Row #, Status, Id, Error and your file's columns. Download errors (n) and Download successes (n) save CSVs of those rows.
• Run async and Dry run show the job card — Job ID, Entity, Status, Results (Created, Updated, Errors), Progress and Message — and up to the first 50 row errors in an Import errors table. A dry run's message begins "Dry run — would create…".

Select Import another to start a new run, or close the dialog; Import History refreshes.

Step 7 — Use Import History

Every run appears in Import History with Job ID, Status, Entity, Type (Sync, Async or Dry run), Records (with a progress bar while running), Result (created, updated and error counts), Uploaded File, Failed Rows, Submitted, Submitted By and Action. The table header has search, Filter (by job, status, entity, type and submitter) and refresh; running jobs refresh themselves every few seconds.

123456 Expand

1. 1

   Start Import is the only action; it opens the wizard as a modal over this history.

2. 2

   Status ends as Completed, Partial (finished with row errors) or Failed; running jobs show progress.

3. 3

   Type records how the run was executed: Sync (Import Now), Async (background job) or DryRun.

4. 4

   Result splits the rows into created (+), updated (~) and errored (x) counts.

5. 5

   Download returns the original file; it is removed after a clean Completed run and kept otherwise.

6. 6

   Fix file downloads only the failed rows with an _error column, ready to correct and re-import.

• Uploaded File → Download returns the original file. After a background run that ends Completed with no errors the file is deleted, and the cell explains that; it is kept for Partial and Failed runs, dry runs and Import now runs.
• Failed Rows → Fix file downloads a CSV of only the failed rows, with their original columns plus an _error column. Correct the values, delete the _error column if you like (it maps to nothing), and import the file as a new run. When the original file is no longer stored, the button reads Error list and gives row numbers and messages only.
• Action → Retry queues a new background job that replays only the rows that failed, using the stored file and the same mapping; a message confirms "Retry queued" with the number of rows and the new Job ID. Fix the cause first — a retry of unchanged data fails the same way.

Expected result: Import History shows the run as Completed or Partial, the created and updated counts match the file, and every failed row has a message you can act on.

Business rules

• Statuses. A background run moves from Queued through Processing to Completed (no errors), Partial (finished with error rows) or Failed. An Import now run starts at Processing and ends Completed, Partial, Failed or Cancelled (when you select Cancel). Retry Queued and Dead-lettered can appear on jobs the background system had trouble delivering.
• Create or update. A row with a valid Id updates that record; an Id that matches no record fails with "Record with Id '…' not found." instead of creating a duplicate. Without an Id, a row with an External Id updates the one record carrying that value (only on entities that have the field; zero or several matches create a new record). Everything else creates.
• Partial updates. An update writes only the mapped columns; fields you did not map keep their values. Blank cells in a background run are not written.
• Lookups. A dot column (Account.Name) resolves the display value to a record. Several dot columns on the same lookup (Account.Name and Account.City) act together as one key. A value with no match fails the row ("Unresolved lookup for column '…': no match for "…"." in a background run; Transform Error in Import now). When several records match, the first one found is used — keep the matched values unique.
• Pick-lists must hold a value the field accepts; the export writes these stored values, so an exported file imports back cleanly.
• System fields (created/updated stamps, owner, row version) are never written by an import.
• Background processing handles rows in chunks of 200 and retries a chunk that fails for a technical reason twice; if it still fails, its rows are reported as "Chunk failed after … attempt(s)".
• Retry is accepted only for Failed and Partial runs whose file is still stored, and it replays only the failed rows. A dry run cannot be retried — run the file for real instead.
• Retention. Import job records are removed after 90 days.
• No completion notice. xMatix does not send an email or notification when a background import finishes; check Import History.

Example

An operations administrator is loading 3,400 customer contacts from the old system for accounts that were imported last week.

1. They select Start import, drop contacts.xlsx and choose Contact under Select target entity. The card reads 3,400 rows · 9 columns read.
2. On Map columns, FirstName, LastName and Email show Accepted; Account.Name maps to the Account lookup; Phon is Suggested for Phone, which they confirm; Legacy Ref is Skipped, which is what they want. They select Import.
3. Preflight notes that 3,400 rows is large and recommends Run async. They select Dry run first.
4. Two minutes later the dry run shows Errors: 37. The error list shows 30 rows with "Unresolved lookup for column 'Account.Name'…" (accounts spelled differently in the source) and 7 rows refused by a validation rule their company added to contacts.
5. They correct the spreadsheet, start the wizard again and select Run async. Import History shows the job Completed with 3,400 created.
6. A week later they need to fix the Title of 250 contacts. They export the contacts with Id and Title, correct the titles and import the file: all 250 rows read Updated, and no new contacts are created.

Training

Practice exercise

In a sandbox, create a CSV with a header row FirstName,LastName,Account.Name,Email and three rows: two whose Account.Name matches an existing account, one with an account name that does not exist. Import it into Contact with Dry run, then with Import now.

Expected result: the dry run reports 2 rows that would be created and 1 error; Import History shows a Dry run row and nothing is saved. Import now creates two contacts and shows one Transform Error; the history row reads Partial, and Fix file downloads one row with an _error column.

Quick reference

• Path: Setup → Platform → Data → Import → Start import.
• Files: .xlsx (first sheet), .csv, .json; up to 100 MB and 50,000 rows; no .xls.
• Map lookups with dot headers: Account.Name.
• Dry run = full validation, nothing saved.
• Over 2,000 rows → Run async.
• Id updates; no Id (and no matching External Id) creates — re-importing without ids duplicates.
• Rows commit one by one; a failed run is partly applied.
• Fix failures with Fix file, or Retry after fixing the cause.
• Imports fire rules and automation exactly like manual saves.

Permissions

A user without the capability does not see the Import item, and the history and job actions are refused. A user with the capability but without create access to an entity sees every row fail with an access error. The Jobs screen under Setup → Platform → Monitoring also lists import runs for users with job-monitoring access; act on them from Import History.

Configuration

Data Import has no settings screen of its own. What shapes an import is configured elsewhere:

• Mandatory fields, validations and business rules on the entity decide which rows fail. Check them before a large load.
• Automation and workflows on the entity run once per imported row. Turn off or narrow automation you don't want triggered by a migration, and turn it back on afterwards.
• Document numbering (Setup → Feature Hub → Platform → Document Settings) gives imported records their numbers; a numbered entity overwrites the Name you import with the next number in the series.
• Duplicate rules feed the duplicate finder; they do not stop an import from creating duplicates.
• Security profiles grant the import capability and the entity access each row needs.

Common problems

The re-import created duplicates

A row updates a record only when it carries that record's Id, or an External Id that matches exactly one record on an entity that has the field. Every other row creates. Export the records with Id, edit that file and import it back; to clean up, delete the duplicates (they go to the recycle bin).

"Record with Id '…' not found."

The Id column holds a value that matches no record — often an id from another environment or a deleted record. The row fails rather than creating a duplicate. Correct the id, or clear the cell to create a new record.

"Unresolved lookup for column '…': no match for "…"." or a Transform Error

The display value in the lookup column does not match a related record — a spelling or spacing difference, or the parent was never imported. Import the parents first, or correct the values in the Fix file and import that.

Dry run, Run async and Import now are all disabled

Preflight found more than 50,000 rows. Split the file into smaller files and import each one.

"Legacy .xls workbooks are not supported…"

The file is an old-format Excel workbook. Save it as .xlsx (or .csv) and upload it again.

"File size (… MB) exceeds the maximum allowed size of 100 MB."

Split the file, or save it as CSV, which is usually smaller.

"Only Failed or PartiallyCompleted jobs can be retried."

Retry works only for Failed and Partial runs — not cancelled runs or dry runs. Start a new import with the file instead.

"This job has no stored file and cannot be automatically retried. Please re-upload the file."

The original file is no longer stored. Download the Error list, correct the rows in your own copy of the file, and import them as a new run.

The import is stuck at Processing

An Import now run whose browser tab closed never finishes; the rows written before that stay. Check which records exist, then import the remainder with Run async.

Thousands of automation runs or emails after an import

Every imported row fires the entity's rules and automation like a manual save. Review what is active on the entity before a large load, and dry-run the file first.

Common questions

How do I update existing records instead of creating new ones?

Include an Id column holding each record's identifier. Rows with an id update that record, and only the columns you mapped change; unmapped fields keep their values. On entities that have an External Id field, a row without an id but with an external id that matches exactly one record also updates it. Every other row creates a record. The reliable way to get ids is to export the records with Id first, edit that file and import it back — the exported headers map themselves.

Can I import more than one entity in one run?

No — each run targets a single entity. For a related data set, run one import per entity, parents first, so that each child file's lookup columns (Account.Name) resolve against records that already exist. Keep the display values in the child file identical to the parent records and unique, because a value with no match fails the row and a value with several matches links to the first one found.

What is the difference between Dry run and the preflight messages?

Preflight is a quick check in your browser: row count, ignored system fields, unmapped columns and type conversion on the first 200 rows. A Dry run sends every row through the real create/update path on the server — mandatory fields, validations, rules, security — and stops before saving, so it is the only way to see the complete error list before anything is written. It runs as a background job and keeps the file for the real run.

Can I undo an import?

There is no single undo. Imported rows are ordinary records, so the good rows of a bad run must be found and deleted like any other data; deleted records go to the recycle bin for a grace period, from which they can be restored. Prevent the mess instead: dry-run the file, load a small test file, check the results, then load the rest. See data lifecycle concepts.

Will I be told when a background import finishes?

No email or notification is sent. Keep the dialog open to watch progress, or come back to Import History later: the row shows the status, the counts and the fix file. Running jobs refresh in the table every few seconds.

What are Job Queue records?

Job Queue is the tracking record xMatix writes behind each background data job. Every Run async, Dry run, Import now and Retry run creates one, and so does every export job. Its id is the Job ID shown in the history tables, and the workers update its status and progress message as the job runs. You don't create or edit these records yourself: Import History and Export History are where you follow and act on jobs. The Job Queue lookups you may see on KPI configurations or on documents are never filled or read by the platform. See the Job Queue reference.

Related topics

• Export data
• Duplicate rules
• Background work and jobs
• Data lifecycle concepts
• Security profiles