Quickstart: Command Your Data

The engine parses your source data and presents the Visual Field Mapper — drag-and-drop UI showing source fields on the left, Aeion target fields on the right.

Auto-detected mappings:

• Exact-name matches (source email → target email)
• Common synonyms (first_name → firstName, Acct_Name → companyName)
• Type-compatible inferences (source created ISO date → target createdAt)

Manual mapping for everything else — drag, drop, save.

Mapping options per field:

• Required vs optional — flag fields that MUST be present
• Default value — fill empties with a default
• Computed value — derive a target field from one or more source fields (e.g., fullName = firstName + " " + lastName)
• Lookup — fetch a related record (e.g., source companyName string → target companyId UUID via lookup on company name)
• Skip — explicitly drop fields you don't want to import

Save the mapping as a template — reuse for future migrations from the same source. Templates can be exported / imported across tenants.

Click Preview Import. Aeion validates the mapping itself before you commit to a full run:

1. Field mapping — confirms every required target field is mapped
2. Type compatibility — flags source/target type mismatches (string vs number, date format, etc.)
3. Sample rows — a handful of parsed rows from your source file, so you can eyeball the detected fields and values before mapping

Output of the dry-run:

• Row-by-row preview of a sample of what mapping produces
• Validation warnings with the field + reason

Common dry-run failures:

• Missing required field → add a default value or skip those rows
• Invalid date format → apply the Parse Date transformer
• Referenced record not found → enable "auto-create missing FK records"
• Schema mismatch → check that your tenant's collection extensions are up to date

Click Execute Import. The batch processor chunks the data (default 100 rows per chunk) and streams them into PostgreSQL transactionally.

Progress tracking:

• The job record tracks phase (pending → validating → mapping → processing → completed/failed/partial)
• Processed / success / error / skip counts are recorded on the job as it runs
• Row-level errors are recorded with the exact row + reason
• Cancel a running job with the cancel action in the Admin panel (or POST /jobs/:id/cancel)

Post-import:

• Review the job's success/error counts and error detail
• Re-run the same connector to pick up records changed since the last run — supply a modified-since filter (many connectors, e.g. Opera and Mews, accept a modifiedSince option) so each run pulls only recent changes, and smart upserts keep repeated runs duplicate-free. Trigger it manually, or point your own external scheduler at the import-job API for a recurring cadence. Singularity doesn't track the watermark for you — you supply the cutoff.