Unified mappings build
truto unified-mappings build reads an integration's proxy API and writes the JSONata mapping rows connecting it to a unified model (crm, ats, hris). It saves the result as a local MappingFile, for example acme.crm.mappings.json.
Nothing reaches Truto until you run truto unified-mappings apply.
This is the mapping-side companion to truto integrations build. Build the integration first, so it has proxy resources. Then map it to a unified model.
flowchart LR
source["Account or docs"] --> build["build"]
build --> asked{"Questions?"}
asked -->|"yes"| answer["build --continue"]
answer --> validate["validate"]
asked -->|"no"| validate
validate --> apply["apply"]
Quick start
# 1. Build mappings for an integration against a unified model
truto unified-mappings build acme crm --account <id>
# 2. Answer anything the build asked (it prints this command for you)
truto unified-mappings build --continue acme.crm.mappings.json --answer q1="…"
# 3. Check the file without pushing
truto unified-mappings validate acme.crm.mappings.json
# 4. Push it to Truto
truto unified-mappings apply acme.crm.mappings.json --target baseNo account yet? Build straight from docs instead:
truto unified-mappings build acme crm \
--source-url https://docs.acme.com/openapi.json --yesAlready marked a test account for this integration? Skip --account: truto profiles set test-account.<integration> <id> is used automatically. The profile's default integrated account is never sampled.
Before you start
You need:
- A built integration with proxy resources. Build it first if it doesn't exist yet.
- A Truto login, so the build can read the integration config, the unified model schema, and any existing mapping rows.
- Live samples or docs: pass
--account <id>(or mark a test account), at least one--source-url, or both. Without either, the build exits with an error. - An LLM key
- Anthropic (the default):
ANTHROPIC_API_KEY - Fireworks, only with
--llm-provider fireworks:FIREWORKS_API_KEY
- Anthropic (the default):
- A Firecrawl key (
FIRECRAWL_API_KEY), only for docs sites that need crawling
No key set? In a terminal the CLI asks for it and offers to save it to your profile. Resolution order: flag, environment variable, truto profiles set-key, then an interactive prompt.
Want a different model? Override it with --anthropic-model (Anthropic) or --llm-model (Fireworks).
Building from docs? Searching them needs no key. A small local model (~35 MB) downloads on first use.
How a build works
The build is agentic: the model routes each unified resource/method (a "cell," for example contacts.list) to a proxy endpoint. It samples the endpoint, writes the JSONata, and validates it. --structured swaps in a fixed per-cell pipeline instead, for cheaper or parity runs.
- Routes each cell to the proxy endpoint that serves it. This includes cross-name routes (unified
accountsto proxycompanies) and conditional, when-guarded routes. - Grounds it in a sample, in order:
- a live proxy call, when
--accountor a marked test account is set - a documented example already on the integration
- your
--source-urldocs - After a recent config change, the first live sample waits (about 7 minutes) for the cache to refresh. Later samples don't wait.
- A read cell with no sample waits on a question instead of guessing. Write cells (
create/update/delete) build from the documented request body even with no response example.
- a live proxy call, when
- Generates and checks the JSONata. Validates each field against the sample and the unified schema. Rejects expressions copied verbatim from another integration.
- Refines interactively. In a terminal, type a plain-English fix, such as "strip the trailing Z from start times", and the agent rebuilds that cell.
- Type
:showto print the full review. - Press Enter on an empty line to finish.
- Skipped with
--no-refine,--yes,--only-missing, or when output is piped.
- Type
- Saves the result:
acme.crm.mappings.json: the MappingFile (integration and model identifiers, awrite_targetofbaseorenv, and the generatedcells[])acme.crm.mappings.report.md: a report you can read- a
.committedcopy beside it, thatapplycompares against
Rerunning a build? It resumes from the existing file: built cells are kept, failed ones retried. Pass --fresh to start over, or --only-missing to add only the cells you're missing.
When the build asks a question
A cell waits instead of shipping a guess when, for example:
- a read cell has no sample: no live call, no documented example, no docs hit
- the router can't tell which proxy method serves the cell
- a required field or a value list's source is unclear
Answer it
- In a terminal: the build asks at the end of the run, before the refinement loop.
- From a script or an agent: answer later.
truto unified-mappings build --continue acme.crm.mappings.json --answer q1="…"
truto unified-mappings build --continue acme.crm.mappings.json --answers answers.json--continue rebuilds only the cells your answers name. Every other cell stays exactly as committed.
- Naming a proxy method? Answer with
resource.method, for examplepeople.list. - No sample to give? Point it at one:
--account <id>or a--source-urlwith an example. Or confirm the mapping as already built.
Edited the file by hand? Run truto unified-mappings build --recheck acme.crm.mappings.json first.
Never paste a key, token or password as an answer. Say where the value comes from instead, for example <value from the previous response>. An answer that looks like a credential is refused.
Results and exit codes
Every build ends with a summary: status, counts, open questions, and the next command to run. The same summary is saved in the file, with a Markdown report beside it (for example acme.crm.mappings.report.md).
| Exit | Meaning |
|---|---|
| 0 | Nothing waits or is blocked. |
| 3 | A cell waits for an answer or is blocked, or there's a conflict over the file or its target. |
| 1 | A cell failed with an error and waits on no question, or the build itself failed. |
- This build has no
--fail-onflag. Exit3means waiting or blocked, not broken. - Scripts and agents should pass
-o json: one JSON summary and no prompts, printed once at the end. build_summary.statusiscomplete,partial(built, with recorded gaps), orincomplete(cut short).skippedcells say why no mapping was made.warningsflag ones worth a second look, for example a hardcodedcustom_fields.
Changed from 1.0.38: a routed cell the build could not produce used to exit 0. It now exits 3, with other waiting or blocked cells.
Validate
Check a MappingFile without pushing anything. It's deterministic: no LLM calls, no writes.
truto unified-mappings validate acme.crm.mappings.json
truto unified-mappings validate acme.crm.mappings.json -v # list every warning- Checks each cell against the target config and schema.
- Only an observed sample or a documented example backs a check. Anything else is unverified, not passed.
- Passing locally isn't backend parity: the CLI and worker engines differ.
- Exits non-zero on errors. Warnings never fail it.
- Pass
--environment-idto check against an env schema override.
Apply
Push a MappingFile to Truto. Apply rechecks every cell, reconciles it against its baseline and live state, and writes only what it validates.
truto unified-mappings apply acme.crm.mappings.json --target base
truto unified-mappings apply acme.crm.mappings.json --dry-run # offline preview, no live comparison--target basewrites team-owned rows.--target envwrites per-environment overrides and needs a file built with--environment-id.--resolve '<cell>=mine|theirs'settles a reported clash:--resolve '<cell>=mine'keeps your draft,--resolve '<cell>=theirs'takes the live row.--test-account <id>(or a marked test account) lets apply run eligible read tests against the live account. It never runs provider mutations.--yesskips the confirmation, not validation.- Every write is reread, so a stale or partial run stays recoverable.
Without a terminal (a script, an agent, CI, or -o json), apply writes nothing and exits 3, unless you pass --yes. The safer path: run --prepare, then --plan <path>.plan.json --expect-digest <digest> once the plan is approved.
Useful flags
| Flag | What it does |
|---|---|
-a, --account <id> |
Integrated account for live proxy samples |
--source-url <url|path> |
Docs URL or local file. Repeatable, comma-separated, or a glob |
--resources <list> / --methods <list> |
Build only these unified resources or methods |
--only-missing |
Build only cells absent from the existing file |
--fresh |
Ignore the existing file and start over |
--environment-id <id> |
Resolve schema overrides and target env rows |
--out <file> |
Output path (default <integration>.<model>.mappings.json) |
--no-refine |
Skip the interactive refinement loop |
--yes |
Non-interactive: skip account/docs prompts |
See every flag: truto unified-mappings build --help
Next
- AI-powered integration build: build the integration first so it has proxy resources
- What are Unified APIs?: the models you're mapping to
- Data plane: run
unified test-mappingto try one mapping locally