Versioning & Fork-on-Bump¶

Business Events in BizMetry are versioned entities. Each time you need to change an event's configuration — either proactively (new business requirements) or reactively (a Template version bump) — a new version is created. The old version continues to capture telemetry uninterrupted until the new one is published.

Why Versioning Exists¶

A Business Event's mapping depends directly on the Frame Type structure defined in the Template. When a Template version is bumped (new components added, existing ones renamed or restructured), the field mappings in active Business Events may become stale or incorrect.

BizMetry handles this through fork-on-edit and fork-on-bump: a PUBLISHED version is never edited in place — any change, whether made by you or triggered automatically by a Template bump, creates a new version instead, giving you time to fix or adjust mappings before publishing it.

Version Numbering¶

Every Business Event's first version is always 1.0, created in DRAFT. From there, editing a PUBLISHED version automatically forks a new version — you never choose the number yourself; BizMetry calculates it based on the scope of the change:

Only the largest applicable step is used per save — steps are not additive. The result is also collision-safe: it's always calculated against the highest version number that already exists for that Business Event, so re-forking after deletions never produces a duplicate.

See Lifecycle & States → Versioning for the full rule reference.

Creating a New Version by Editing¶

There's no separate "New Version" or "Bump Version" button. To create a new version of a PUBLISHED Business Event, simply edit it:

1. In the Business Events tab, find the PUBLISHED version you want to change.
2. Click Edit (or Edit Mappings, if you only need to touch the field mapping) — see Managing Versions.
3. BizMetry forks a new DRAFT version, copying all existing mappings, operations, and configuration from the PUBLISHED version, and automatically assigns its version number per the bump rules above.
4. Make your changes in the DRAFT.
5. Submit it for review and, once approved, Publish it.

The original PUBLISHED version is untouched and keeps capturing telemetry throughout this whole process.

Automatic Fork-on-Bump¶

This is triggered from the Template Release Manager, in an environment's Profile settings: when you edit a PUBLISHED Template and then assign the new version to an environment, BizMetry runs a reconciliation pass — the same pass that also fixes up affected Resources and Clients — and, as part of it, forks every affected Business Event automatically. You don't run this yourself; it's a side effect of assigning the Template.

Two guards decide whether a fork happens at all¶

Not every template reassignment triggers a fork. Before touching any Business Event, BizMetry checks:

If either guard fails, the affected Business Events are untouched — no new DRAFT, no DEPRECATED transition. This is silent from the UI's perspective: the Template reassignment itself still succeeds (Resources/Clients are still reconciled), only the Business Event fork step is skipped.

When both guards pass¶

For every PUBLISHED Business Event version targeting the old Template instance:

1. Per-mapping classification. Each existing field mapping is checked against the new Template's definition of the same target component:

   Outcome	Meaning
   Stable	The target component still exists with an identical definition (same type/constraints, same referenced Resource Type + Attribute, same Nested Table column) → the mapping is kept exactly as-is.
   Unstable	The component still exists but its definition changed (renamed field, changed constraints, re-pointed reference, etc.) → resolved automatically via IntelliSense (see below).
   Eliminated	The component no longer exists anywhere in the new Template → the mapping is dropped.
   New	The new Template's Frame Type has components the old mapping never covered (fields added since the parent version) → IntelliSense is also asked to try mapping these, not just the broken ones.

   What \"stable\" means, per component type

   • CUSTOM — same scalar type and the same constraints (max length/regex for strings, bounds for numbers, enum values for enums).
   • OBJECT_REFERENCE — same target Resource Type, with that Resource Type's own definition (name, attributes) unchanged.
   • FIELD_REFERENCE — same target Resource Type and Attribute, both unchanged.
   • NESTED_TABLE — the specific column (Resource Type + Attribute pair) still exists with its definition unchanged; other columns can change without affecting this column's stability.

2. IntelliSense resolves unstable and new components automatically. This is the same matching engine described in IntelliSense Auto-Mapping — same field-matching heuristics, same automatic BMEL expression generation for computed/aggregated values — just triggered by Bizmetry instead of by you clicking the button, and scoped only to the components that actually need it rather than the whole Frame. A component IntelliSense can't confidently match is simply left unmapped, for you to complete manually in the forked DRAFT.

3. Two special cases skip the merge entirely:

   • Frame Type eliminated from the new Template — the Business Event's target no longer exists at all, so there's nothing to fork onto. This version is not forked automatically; it stays PUBLISHED against the old Template instance (see the warning below).
   • Frame Type exists but shares no components with the old one (effectively a different Frame Type reusing the same ID) — merging mapping-by-mapping wouldn't mean anything, so BizMetry skips straight to a full IntelliSense pass over the new Frame Type instead, exactly as if you'd clicked IntelliSense on a blank mapping canvas.

4. A new DRAFT version is created with the merged mapping set already applied — populated, not blank, but not guaranteed complete. Review it like any other fork: check the mappings IntelliSense filled in, complete anything left blank, then submit/approve/publish through the normal lifecycle.

5. The original PUBLISHED version is deprecated — but, same as any Template bump, only once every environment sharing that Profile has migrated off the old Template instance. See the Deprecation guard. This check re-runs safely on every Template reassignment, so it also catches versions left over from an earlier bump that hadn't been fully deprecated yet.

Multiple Environments & Partial Migration¶

A Business Event can be PUBLISHED for multiple environments simultaneously — one PUBLISHED version per target Frame Type + Version (see Multiple PUBLISHED versions).

Consider this scenario, starting from a single PUBLISHED version v1.0 targeting Template v1.1, active for all three environments:

When DEV is bumped to Template v1.2:

• A new DRAFT v2.0 is forked (major bump — the target Template version changed), pointing at v1.2.
• v1.0 remains PUBLISHED — QA and PROD are still on Template v1.1, so the deprecation guard keeps it active for them.
• Once you review/fix v2.0's mappings and publish it, it becomes PUBLISHED for DEV's scope — coexisting with v1.0, which is still PUBLISHED for QA/PROD.

Once QA and PROD are also bumped to Template v1.2 and their scope moves onto v2.0:

• v1.0 is automatically DEPRECATED — no environment references Template v1.1 anymore.
• v2.0 is now the only PUBLISHED version, active for all three environments.

Version Tree View¶

The Business Events tab shows every version of an event in a Version Tree, with:

Related Sections¶

• Lifecycle & States
• Managing Versions
• Editing a Business Event
• Configure Mapping
• IntelliSense Auto-Mapping
• Managing Templates