Mapping trace

Add trace to a convert request to get one row per mapping rule that ran: where each output field came from, which transform shaped it, and which warnings it raised.

What a trace is for

A conversion reads your message into transmute's format-neutral model, then writes the target format from that model. Each step follows a mapping table, and each table row says which source field becomes which target field.

Turn on the trace and the response lists every row that ran. You can then answer an auditor's "where did this element come from?" with the table, the source field and the transform, instead of reading the converter's source code. The trace also shows which fields were defaulted because the source had no value and which source fields had no place in the target.

Turn it on

Request form	How
JSON envelope	`"options": { "trace": true }`
Raw MT or XML body	`?trace=true` query parameter, or the `X-Transmute-Trace: true` header (the query parameter wins)

curl -sS -X POST "https://api.transmute.403fin.io/v1/convert?to=camt.053&trace=true" \
  -H "Authorization: Bearer $TRANSMUTE_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @statement.mt940

The trace is returned only in the JSON envelope. If you ask for the bare document (Accept: application/xml or text/plain) or a zip with trace, you get an invalid-input 400. Batch items reject trace. Use POST /v1/convert for each message you want traced.

Turning the trace on does not change the converted output or its warnings.

The response

The usual convert envelope gains a trace array. The values below come from the sample MT940 statement in the Quickstart:

{
  "result": "<?xml version="1.0" ... camt.053.001.08 ...",
  "warnings": [ { "code": "MISSING_REQUIRED_DEFAULTED", "...": "..." } ],
  "meta": { "detectedType": "mt940", "targetType": "camt.053.001.08", "durationMs": 3 },
  "trace": [
    { "table": "canonical.Statement|camt.053", "sr": "SR2025",
      "sourceField": "messageRef", "targetField": "GrpHdr/MsgId", "outcome": "mapped" },
    { "table": "canonical.Statement|camt.053", "sr": "SR2025",
      "sourceField": "createdAt", "targetField": "GrpHdr/CreDtTm", "outcome": "defaulted",
      "warningCodes": ["MISSING_REQUIRED_DEFAULTED"] },
    { "table": "canonical.Statement|camt.053", "sr": "SR2025",
      "sourceField": "entries[].amount", "targetField": "Stmt/Ntry/Amt", "outcome": "mapped" },
    { "table": "canonical.Statement|camt.053", "sr": "SR2025",
      "sourceField": "entries[].supplementaryInfo",
      "targetField": "Stmt/Ntry/NtryDtls/TxDtls/AddtlTxInf", "outcome": "dropped" }
  ]
}

trace is always an array when you asked for it. It is absent when you did not.

Row fields

Field	Always present	Meaning
`table`	yes	The mapping table that ran, named by its source and target (see below)
`sr`	yes	The Standards Release of the table that ran, such as `SR2025` (see SR2025 to SR2026)
`sourceField`	yes	The source path: an MT tag and subfield such as `:32A:/amount`, or a path in the canonical model such as `entries[].amount`
`targetField`	yes	The target path: a canonical path, or an ISO 20022 element path such as `Stmt/Ntry/Amt`
`transform`	no	The named transform applied on the way, such as `truncate`, `code-table`, `lowercase-uetr`, `no-slot-drop`, `identity`, or `override:<name>` for one of your mapping overrides. Omitted for an internal transform that has no public name
`outcome`	yes	`mapped` (the value was carried), `defaulted` (the target needed a value the source did not have, so one was supplied) or `dropped` (the source field has no place in the target)
`warningCodes`	no	Codes of the warnings this row raised. Look them up in the warning registry

A table name is the source and the target joined by a vertical bar. MT103|canonical.Payment reads an MT103 into the model, and canonical.Statement|camt.053 writes a camt.053 from it.

Rows are grouped by table, in the order the conversion used the tables (reading the source first, then writing the target), and within a table in the order they ran.

To review only the rows that did something other than a straight copy, filter on outcome:

curl -sS -X POST "https://api.transmute.403fin.io/v1/convert?to=camt.053&trace=true" \
  -H "Authorization: Bearer $TRANSMUTE_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @statement.mt940 | jq '.trace[] | select(.outcome != "mapped")'

Paths and names, never values

A trace row holds table names, field paths, transform names and warning codes. It never holds a value from your message: no amounts, names, account numbers or references. That makes a trace safe to attach to a support ticket or keep in an audit file without the privacy review that the message itself needs.

Like everything else in a conversion, the trace exists only in the HTTP response. transmute does not store it.

Access and billing

trace is an option on POST /v1/convert, so it needs the convert scope and is billed as part of that conversion. It adds no separate charge.

Round-trip verification: check that no value was lost without a warning.
Warnings: what each code in warningCodes means.

Was this page helpful?