Data Import field guide

Data Import is the controlled path for loading companies, partners, items, opening balances, prices, transactions, and integrations. A successful upload is not the same as correct data. OSERP should preserve source rows, mapping version, validation results, created IDs, rejected rows, and reconciliation evidence.

Import batch fields

Open Administration → Imports → New Batch.

Field	Example	Purpose and impact
Batch ID	IMP-2026-004281	Immutable migration key
Entity	Business Partner	Target object
Source system	NAV	Provenance
File name	customers-2026-09.csv	Source evidence
Company	company_uae	Legal scope
Mode	Validate / upsert / create	Mutation behavior
Mapping version	NAV-CUS-v4	Column interpretation
Idempotency key	nav-cus-20260917	Retry safety
Submitted by	Data steward	Accountability
Submitted at	2026-09-17T09:00Z	Sequence
Status	Uploaded / validated / applied	Batch lifecycle

Other fields include delimiter, encoding, decimal separator, date format, timezone, attachment, dry-run flag, row count, error count, created count, updated count, skipped count, and rollback policy.

Mapping fields

Mapping rows define source column, target field, transformation, required flag, default, lookup, validation, and error behavior. For a customer file, CustomerNo maps to external ID, Name to legal name, TRN to tax number, and Currency to ISO code.

Never map display name to an immutable ID without a controlled lookup. Store source-to-target mapping and sample output. A changed mapping version creates a new batch; historic batches retain their interpretation.

Scope and referential integrity

Every row must carry or inherit tenant, organisation, company, branch, warehouse, and effective date where relevant. The server verifies that referenced partner, item, account, tax code, and warehouse belong to the scope.

An item may be found by source external ID, not by name alone. A row referencing an unknown account should be rejected or held for master-data resolution; it must not create a suspense posting invisibly.

Validate and dry run

Validation checks file structure, required fields, formats, precision, dates, currency, duplicates, legal scope, references, policy, tax, and permissions. A dry run executes validation and transformations without mutation and returns row-level outcomes.

For 10,000 rows, report valid, invalid, duplicate, update, create, skipped, and warning counts. A dry run should be repeatable with the same mapping version and source hash.

Upsert and idempotency

Choose create-only, update-only, or upsert deliberately. Upsert key should be immutable source external ID plus company scope. Never use a mutable name or email as the sole key.

Retries use the same batch or idempotency key. If a timeout occurs after partial processing, the next run resumes by row status and server ID. A duplicate batch should return original result or explicit conflict, never create a second partner, item, invoice, receipt, or journal.

Error fields and correction

Row errors include row number, source key, target field path, code, message, severity, current value, expected value, and suggested action. Example: TAX_CODE_INVALID: row 41, taxCode=UAE-STD-7 is not active for company_uae on 2026-09-17.

Correct the source or mapping and create a new batch/version. Do not edit the original source file without preserving before/after hashes. Warnings need owner and disposition; errors block application unless policy allows partial success.

Partial success and rollback

Batch policy states all-or-nothing, atomic by row, or partial with retry queue. For master data, partial success may be acceptable if rejected rows are visible. For opening balances or journals, atomicity by company/period is usually safer.

Rollback fields include batch ID, created IDs, reversal method, reason, approver, and status. Rolling back a posted invoice or stock receipt uses business reversal, not database deletion. A failed rollback creates a high-severity exception.

Opening balances and transactions

Opening balances require source account, target account, company, period, currency, debit/credit, dimension, item/warehouse quantity, source evidence, and approval. Trial balance totals must balance by company and currency, while subledgers reconcile to control accounts.

Transactional imports require source document, external reference, customer/supplier, item, quantity, price, tax, dates, currency, warehouse, and status. Do not import posted journals without testing period, tax, and idempotency behavior.

Reconciliation after application

Reconcile source row count to created/updated/rejected counts. Compare totals, quantities, tax, balances, partners, items, stock, opening GL, and document numbers. Store report, filters, run time, reviewer, and difference owner.

An applied purchase receipt must reconcile to PO, batch, stock movement, GRNI, and later invoice. An applied customer receipt must reconcile to bank, allocation, AR, and statement. Import completion is not acceptance until reconciliation passes.

API and audit mapping

Import APIs use batch ID, entity, source, mapping version, source hash, scope, mode, dry-run flag, rows or file reference, and idempotency key. Responses expose validation summary, row statuses, created IDs, error file, and correlation ID.

{"entity":"BUSINESS_PARTNER","companyId":"company_uae","source":"NAV",
 "mappingVersion":"NAV-CUS-v4","mode":"UPSERT","dryRun":true,
 "sourceHash":"sha256:...","idempotencyKey":"nav-cus-20260917"}

Audit includes upload, mapping change, validation, application, row correction, rollback, user, approval, timestamps, request ID, and source hash. Sensitive files require restricted access and retention.

Practice checklist

Import customers, items, opening balances, and prices with a dry run, invalid tax, duplicate key, unknown account, partial success, retry, and reconciliation. Explain every batch and mapping field, format, precision, scope, status, permission, error, rollback, API ID, and evidence. Then replay the same batch and prove no duplicate records or postings appear.

Related: Company field guide, Business Partner field guide, Inventory field guide, Journal Entry field guide, and API cookbook.