Overview

Use Case versioning allows you to effectively track and manage the evolution of your Use Case implementations over time. Ascerta uses versioning to let you clearly distinguish between different versions of your Use Case implementations, enabling data-driven decisions to optimize your product based on your specific business KPIs.

How Versioning Works

• When you create a new Use Case Definition using the Create Use Case API, it automatically begins at version 1.
• Versions are only explicitly incremented through the Increment Use Case Version API or through the Ascerta portal.
  • You can increment a Use Case Version in the Ascerta portal by:
    • Selecting an Application
    • Choosing "Use Cases" from the bottom of the left nav
    • Ensuring the correct Use Case is selected from the top left drop down titled "Select Use Case"
    • Clicking the "Version N +" button and confirming the action
• Changing use case metadata does not trigger version increments:
  • Updating the description or name
  • Updating the default limits
• Instances use the latest version number by default.
• In scenarios where multiple versions are possible, you can explicitly specify the desired use case version with the use_case_version parameter.

Setting the Version in Code

The use_case_version parameter takes effect only when a new use case Instance is created. The Ascerta service ignores a version passed for an instance that already exists.

This matters with global instrumentation (the default): payi_instrument() creates the global use case instance, so set the version in its config:

from payi.lib.instrument import payi_instrument

payi_instrument(config={"use_case_version": 3})

A version passed later in @track or track_context() cannot change that existing instance:

@track(use_case_version=2)  # Ignored: the global instance already exists
def foo():
    with track_context(use_case_version=3):  # Also ignored
        ...

use_case_version in @track or track_context() applies only when that scope creates its own new instance, for example by passing a new use_case_name.

Viewing Versions in the Dashboard

Use Case versions are displayed and managed across various sections of the Ascerta portal. Specifically, versions are displayed in:

• Time Series: Versions within the selected time window are indicated by dotted lines marking transitions.
• Table: Includes a dedicated "Version" column listing versions active during the selected period.
• Histogram: When you select a use case definition, the histogram reflects data only from the selected version, clearly labeled (e.g., "Use Case Name (version 3)").
• Regressions: Displayed with the highest version at the start of the selected time window and the highest version at the end of the window (e.g., "version 2 → 3"). Version changes do not affect regression calculations.

The use case version selector defaults to the highest version active during your selected time period. You can choose from any version active within your selected timeframe.

Versioning Impact on Regressions and Forecasts

Ascerta does not use use case versions when calculating regressions and forecasts. It visually indicates version increments on the timeline as annotations to clearly represent the evolution of use cases over time.