Configuring field mappings
This page describes the operator workflow for configuring a field mapping in the dashboard. For the capability reference, see Field mapping.
Field mappings are per (partner, resource). A partner may have one mapping for orders, another for inventory, another for products.
Where
Settings → Integrations → Partners → {partner} → Field mapping → {resource}.
What you configure
| Section | What it does |
|---|---|
| Field map | Source → target renames. Supports dot paths and array indices. |
| Nested mappings | Array-to-array transforms (e.g. Details[] → items[]). |
| Static values | Fields injected into every mapped payload. |
| Identifier field | Override the partner's default identifier for just this resource. |
| Is active | Disable the mapping without deleting it. Inbound payloads flow through as-is when inactive. |
Recommended workflow
- Start from a template. Even if you're on Custom, open the Acumatica template to see a reference shape.
- Send one real payload from the external system with mapping disabled.
- Open Integration Logs in the dashboard. Copy the raw payload.
- Enable the mapping and define paths to match the real payload. Target names must match the platform's internal field names — see the API Reference for the canonical field list.
- Send the payload again. Compare raw vs. mapped payload in the log entry.
- Iterate until the mapped payload matches the internal schema exactly.
Validating a mapping
Pre-production checks you can run:
- Dry-run create — the dashboard's mapping editor previews the mapped payload against a sample request without persisting.
- Negative test — send a request deliberately missing a mapped field. Check that the validation error names your field, not the internal one.
- Round trip —
GETa record after creation, confirm the response uses your field names.
Reverse mapping: how responses look
Responses and validation errors are reverse-mapped using the same field map. If you mapped po_number → order_number, a GET returns po_number, and a validation error on that field reports po_number.
Fields not present in your mapping pass through with their internal names. This is usually what you want — e.g. id, created_at, status on orders.
Disabling
Set the mapping to is_active = false to bypass it. Payloads must then use internal field names. Useful as a kill switch when a template breaks after an external system upgrade — you can cut over to raw mode while you fix the mapping.