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-bump: when a Template version advances, any PUBLISHED Business Event that targets the old template instance is automatically forked into a new DRAFT version pointing to the new template instance — giving you time to update mappings before publishing the new version.

🔢 Version Numbering¶

Versions follow a major.minor numbering scheme:

The version number is user-assigned when performing a manual bump. For automatic forks triggered by Template bumps, BizMetry increments the minor version.

🔄 Manual Version Bump¶

To create a new version of a Business Event manually:

1. In the Business Events tab, find the event you want to update.
2. Click "New Version" (or "Bump Version") on the event row.
3. BizMetry creates a new DRAFT version as a fork of the current PUBLISHED version — copying all existing mappings, operations, and configuration.
4. Edit the DRAFT version as needed.
5. When ready, Publish the new version.

⚡ Automatic Fork-on-Bump¶

When you bump the Template version for one or more environments in the Profile, BizMetry automatically:

1. Identifies all PUBLISHED Business Events whose targetTemplateInstanceId matches the old template version.
2. For each such event, creates a new DRAFT version pointing to the new template instance.
3. Copies all existing field mappings from the PUBLISHED version into the DRAFT.
4. Transitions the PUBLISHED version to DEPRECATED (if all its environments have migrated to the new template).

sequenceDiagram
    participant Admin
    participant Orchestrator as bizmetry-orchestrator-ms
    participant Core as bizmetry-core-ms

    Admin->>Orchestrator: Bump template version\n(DEV env: v1.1 → v1.2)
    Orchestrator->>Core: inheritTemplate(envId, newTemplateInstanceId)
    Core->>Core: Find all PUBLISHED events\ntargeting old templateInstanceId
    Core->>Core: For each event: fork → new DRAFT v_n+1\n(copy mappings, point to new template)
    Core->>Core: Check: any env still on old template?
    alt No envs remaining on old template
        Core->>Core: Deprecate PUBLISHED version
    else Some envs still on old template
        Core->>Core: Keep PUBLISHED (partial migration)
    end
    Core-->>Orchestrator: Done
    Orchestrator-->>Admin: Template bump complete

🌍 Multiple Environments & Partial Migration¶

A Business Event can be PUBLISHED for multiple environments simultaneously — one PUBLISHED version per templateInstanceId.

Consider this scenario:

When DEV is bumped from v1.1 to v1.2:

• A new DRAFT v1.1 is forked for the new template instance.
• v1.0 remains PUBLISHED because QA and PROD are still on template v1.1.
• v1.1 is PUBLISHED (for DEV scope) only once you publish it.

Once QA and PROD are also bumped to v1.2:

• v1.0 is DEPRECATED (no environments remain on template v1.1).
• v1.1 (or whatever version you published for v1.2) is PUBLISHED for all environments.

📋 Version Tree View¶

The Business Events tab provides a Version Tree for each event, showing all versions and their current state:

🔗 Related Sections¶

• Lifecycle & States
• Managing Versions
• Configure Mapping
• Managing Templates