Acumatica Data Migration — Import Scenarios

Import Scenarios (SM206036) are Acumatica's built-in mechanism for one-time and recurring data loads from CSV or Excel — customer masters, opening balances, inventory counts, whatever a go-live or a bulk update needs. The reason to prefer it over a raw SQL insert is that an import scenario runs through the same PXGraph and business logic the screen uses, so it validates, triggers workflow, and updates related tables the same way a user typing the data in would.

How a scenario maps fields

A scenario is built against a target Acumatica screen — say, Customers (AR303000) — and defines a field mapping from source columns (by header name or position) to specific fields on that screen's data view, including detail-line fields for grids like tax zones or contact info. You build this once through the Import Scenario wizard while a sample file is open, then reuse the mapping for every subsequent load of the same shape.

Source column          -> Acumatica field
CustomerID             -> Customer.AcctCD
CustomerName            -> Customer.AcctName
CustomerClass           -> Customer.CustomerClassID
Terms                   -> Customer.TermsID
BillAddressLine1        -> Customer.MainContact.Address.AddressLine1
BillCity                -> Customer.MainContact.Address.City
BillState                -> Customer.MainContact.Address.State
TaxZone                  -> Customer.Location.TaxZoneID

Stage the source file before you import

Raw exports from a legacy system rarely match Acumatica's expectations exactly — state codes in the wrong format, currency values as text with commas, blank rows, duplicate customer IDs. Rather than fighting these inside the import scenario's mapping, stage the source data in an intermediate spreadsheet or a temporary SQL table, clean and validate it there, then export the clean version as the file the scenario actually consumes. This keeps the transformation logic visible and repeatable instead of buried in mapping formulas.

Handling partial failures

Import Scenarios process rows and report per-row success or failure rather than committing atomically as a batch — a good default for large files, since one bad row (an invalid customer class, a duplicate ID) doesn't roll back the 4,000 good rows before it. The scenario's execution log lists the failed rows with the validation error, which you fix in the source file and re-run; Acumatica's business logic naturally skips rows that would create true duplicates on re-run, but only if your key field (like Customer ID) is what's being matched.

Designing for safe re-runs

Because migrations rarely succeed in one pass, design the source file and mapping so a scenario is idempotent-ish: map to the natural key field the target screen matches on (Customer ID, Item ID, Employee ID), so re-running the same file after fixing a handful of rows updates existing records instead of creating duplicates. This is the single most useful habit for import scenario work — it turns "start over from scratch" into "just run it again."

Sequencing when several entities depend on each other

A real migration is rarely one file — customers depend on customer classes existing first, sales orders depend on customers and inventory items existing first. Import scenarios don't manage this sequencing for you; you do, by ordering your import runs to match the dependency graph: reference data (classes, terms, tax zones) first, then master records (customers, items, vendors), then transactional data (open balances, open orders) last.

Wrapping up

Import Scenarios earn their keep by running data through the same validation and business logic a user would trigger manually, which is worth more than the convenience of a raw SQL load the moment your source data isn't perfectly clean. Stage and validate the file before it reaches Acumatica, test the full run against a sandbox, map to natural keys so re-runs are safe, and sequence multi-entity migrations by dependency — that combination covers the vast majority of go-live data loads without writing custom import code.