Mapping Overrides

What an override can and cannot do

An override is a small JSON document (override/v1, see the document reference) that adjusts one conversion pair. Each rule picks a registered mapping row and either:

• applies a named transform from a fixed list (truncate, fixed-value, code-table, pass-through),
• supplies a default literal when the target would otherwise be empty, or
• suppresses the field.

It can never add logic, create a conversion the engine does not offer, or touch an amount or a currency. Output still passes the same schema validation as without an override.

Override documents are your configuration, not message content. Nothing in transmute builds one from a message you converted, and the API only accepts a document you mark as written by a person. Type default values yourself; never paste values out of live messages.

Before you start

You need a key with the opt-in overrides:manage scope (plus convert to see the effect). On the portal, workspace admins and owners manage the same documents under Overrides.

1. Validate (dry run)

This document shortens the MT940 :20: reference to 4 characters when converting camt.053 to MT940:

curl -sS -X POST https://api.transmute.403fin.io/v1/overrides/validate \
  -H "Authorization: Bearer $TRANSMUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document": {
        "schema": "override/v1",
        "pair": { "from": "camt.053", "to": "mt940" },
        "rules": [ { "path": ":20:", "action": "transform", "transform": "truncate", "params": { "max": 4 } } ]
      }}'

{
  "valid": true,
  "errors": [],
  "pair": { "from": "camt.053", "to": "mt940" },
  "sr": "SR2025",
  "rules": 1,
  "bindings": [
    { "leg_from": "canonical.Statement", "leg_to": "mt940", "source": "messageRef", "target": ":20:", "action": "transform" }
  ]
}

Nothing is stored. bindings lists the exact table rows each rule attached to. A document that breaks a rule comes back with "valid": false and the reasons in errors.

2. Store

PUT /v1/overrides/{name} creates or replaces a document. The body must carry "userAuthored": true; the API refuses anything else.

curl -sS -X PUT https://api.transmute.403fin.io/v1/overrides/short-ref \
  -H "Authorization: Bearer $TRANSMUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userAuthored": true, "document": { "schema": "override/v1",
        "pair": { "from": "camt.053", "to": "mt940" },
        "rules": [ { "path": ":20:", "action": "transform", "transform": "truncate", "params": { "max": 4 } } ] }}'

The change applies to your next conversion. Limits:

Two enabled documents may not attach to the same table row; the second write is a conflict 409.

3. Check it took effect

Convert as usual. When a rule changed a field, the response carries an OVERRIDE_APPLIED warning naming the field (and a suppress adds OVERRIDE_SUPPRESSED). That warning is the proof a rule took effect.

4. Manage

"resolves": false means a Standards Release update moved a row under a stored document. Conversions skip that document until you replace it.

Every write is recorded in your audit trail with the pair and rule count, never the document. These routes are account management: never metered, never counted toward your quota. Overrides apply to /v1/convert and /v1/normalize; batch items run without them today.

Errors