Recomputing Versions after a Template or API Collection Change¶

A Business Event version connects two things it doesn't own: the source — the operations of the API Collection it intercepts — and the target — the Frame Type of the Template it populates. Its mappings are only valid as long as both sides stay as they were when the mappings were drawn.

While the Template or the API Collection is still being worked on (not PUBLISHED), it can be edited in place: a component renamed or retyped, a column added, an operation removed, a field added to a response. Instead of leaving the Business Event versions built on it with stale or broken mappings, BizMetry recomputes them automatically, in real time: it reconciles their mappings with the change, and then runs IntelliSense to map what the change left unmapped.

What Triggers a Recompute¶

The editors tell you beforehand. In the Template editor's API Collections tab, switching or unlinking a collection shows which Business Events will be recomputed with IntelliSense and go back to DRAFT. When you edit an API Collection's contract, the Swagger editor's Validate panel lists the breaking changes and, under Recomputed after saving, the Business Event versions that use the changed operations (name, version, status and the operations involved):

Saving the Swagger doesn't apply it yet: the Edit Collection dialog shows the edited contract with the same summary — Recomputed after applying — and the recompute only starts when you click Apply Changes. Discard drops the edit without touching any Business Event.

Which versions are recomputed¶

How the Recompute Works¶

The recompute runs in the background, right after you save the change: saving the Template or the API Collection never waits for it.

flowchart LR
    A["Template or API Collection
edited in place"] --> B["1 · Deterministic
reconciliation"]
    B -->|nothing left unmapped| D["Recomputed"]
    B -->|targets left unmapped,
or new API fields| C["2 · IntelliSense
remap"]
    C --> D

Step 1 — Deterministic reconciliation¶

First, each affected version's mappings are reconciled with the exact change set, by fixed rules. This step is immediate.

When the target (Template / Frame Type) changed — only changes to the version's own Frame Type apply:

Nested Table columns follow the same rules, column by column: a table keeps its own mapping when only one of its columns changes.

A change only recomputes the versions it actually affects: removing a component that no version had mapped, for instance, leaves every version untouched — no badge, no notification.

When the source (API Collection) changed — only the operations the version sources from apply:

ASBO dependencies in BMEL¶

The documented #{Name} operator identifies resource types and attributes in BMEL. Dependency checks follow their function context, including nested expressions such as:

bmel:get-json-field(bmel:get-resource-by-id(#{Product}, {getOrder:Response Payload}.$.product_id), #{unit_price})

Removing Product or its referenced unit_price invalidates the dependent mapping even when the target frame's computed component did not change. Reconciliation drops the invalid mapping and IntelliSense reviews the remaining sources. If no valid replacement exists, that component stays unmapped for manual review. These checks also apply when editing a Biz Event and forking a Published version; the original Published version remains unchanged.

Step 2 — IntelliSense remap¶

If step 1 left targets unmapped, or the API contract added fields, IntelliSense runs over the version's operations and the current Template — the same engine you use from the mapping canvas, including the generation of BMEL expressions. It usually takes around a minute.

• Only unmapped targets are filled: mappings that survived step 1 are never replaced.
• A suggestion is applied automatically when its confidence is 0.55 or higher — the same default as the Biz Event composer. Suggestions below that threshold aren't applied; they're listed for review instead.
• When the trigger is a field added to the API contract, a suggestion is applied only if it actually reads one of the added fields. A component that already has a mapping is never moved to the new field — not even when the field is the one it used to read before an earlier change — and if nothing gets mapped, the recompute stays silent.
• A target IntelliSense can't match stays unmapped, for you to complete manually.

IntelliSense works over every operation the version sources from, not only the one that changed — so a dropped mapping can come back from another operation or API Collection that carries an equivalent field. It also writes the BMEL the new source needs:

• a conversion when the types differ — for example, an integer $.seed mapped to a component retyped to String becomes bmel:to-string({invokeAgent:Request Payload}.$.seed);
• an aggregation when the source operation has cardinality MANY — IntelliSense receives each operation's cardinality, so an occurrence array is reduced before reaching a single-value component, for example bmel:first({createChatCompletion:Request Payload[]}.$.reasoning_effort).

Status after the recompute¶

Following the Recompute in Real Time¶

The Business Events tab shows the recompute as it happens, in the Status column of each affected version. The list refreshes on its own — every 4 seconds while IntelliSense is at work on a listed version — so you don't need to reload the page.

IntelliSense… — the version is being updated¶

While IntelliSense is mapping what the change left unmapped, the version shows an IntelliSense… badge under its status. Hovering it shows when it started; the mappings appear when it finishes, usually within a minute.

When the reconciliation already had something to report, the Recomputed badge appears next to it right away, and is completed with IntelliSense's result when it finishes.

Recomputed — what changed and why¶

When the recompute is final, the version shows a Recomputed badge. Hover it to see the summary: first the reason — the change behind the recompute — and then one section for each kind of effect it had.

The badge turns to a warning color when the recompute dropped mappings or sources. Click it to acknowledge the recompute and dismiss it — the mappings and the status aren't affected.

The examples below show each section as it appears on a real version.

New unmapped — a required component, INTERNAL_COST_CENTER, was added to the Frame Type, and IntelliSense found no field carrying it in the version's operations. The version keeps its status: a new component alone doesn't need rework.

Remapped by IntelliSense — the added component HYPERPARAM_SEED matched the $.seed field of invokeAgent, with a confidence of 0.80, so IntelliSense mapped it and it no longer appears as unmapped.

Remapped by IntelliSense (NESTED_TABLE column) — an OBJECT FIELD REF column, model_supports_vision (aimodel → supports_vision), was added to the LLM_TURN_SUMMARY table. IntelliSense mapped it, row by row, from the field carrying the model's ID — $.model of each createChatCompletion call — with a confidence of 0.80. Columns are listed as TABLE.column.

Updated (Template) — a mapped component was renamed; the mapping follows it under its new name.

Updated (API Collection) — an operation the version sources from was renamed in the contract; the source, the mappings and their BMEL references follow it.

Review — the bounds of a mapped Integer component changed; the mapping is kept, flagged so you can check the values it captures still fit.

Dropped + Status reverted — a mapped component was removed from the Template while the version was PENDING_REVIEW; the mapping is dropped and the version goes back to DRAFT. The badge shows the warning color.

Dropped + Remapped (type changed) — a mapped component was retyped from Integer to String; the old mapping no longer fits and is dropped, and IntelliSense maps the component again, converting the value (bmel:to-string(…)).

Dropped + Remapped (API field removed) — the reasoning_effort field was removed from the request of invokeAgent; IntelliSense found the same field in another operation of the version, createChatCompletion, from a different API Collection.

Every recomputed version also produces a notification with the same summary, sent once the recompute is final.

Reviewing a Recomputed Version¶

A recomputed version is a regular DRAFT (or keeps its status, if nothing needed rework). Before publishing it:

1. Read the Recomputed summary to see what changed.
2. Open the mappings (Edit Mappings) and check the targets Remapped by IntelliSense, and their BMEL expressions.
3. Map what's listed as New unmapped, and decide on the suggestions listed for Review.
4. Submit it for review and publish it through the normal lifecycle.

Related Sections¶

• Versioning & Fork-on-Bump
• IntelliSense Auto-Mapping
• Managing Versions
• Lifecycle & States
• Edit an existing API Collection
• Editing a Frame Type