Versioning
Every change to a published rule or analysis generates a new version. Each version records who changed it, when, and what changed. A previous version goes live again when published again.
The mechanics are the same for the rule and for the analysis: a published version is immutable, a new version starts as a draft, and publishing replaces what is live. What differs for the analysis is covered in Analysis versions.
Status
Each version is in one of the following states:
| Status | Behavior |
|---|---|
| Draft | accepts free modification and only takes effect after being published |
| In observation | runs in parallel with the active version, deciding nothing, as described in Observation |
| Active | is published and in use by the API; accepts no modification, and a change generates a new version |
| Inactive | was active at some point; kept for traceability and goes live again through the Publish button |
| Archived | hidden in the panel and preserved in the history; remains visible when inspecting older events that used it |
A rule or an analysis allows at most one active version and one version in observation at the same time. A published version shows the New version from this one button in place of the edit button, and states that it cannot be edited.
New version
The New version button, on the rule or analysis page, creates a draft from one of two origins:
| Origin | Draft content |
|---|---|
| From a version | copy of the chosen version’s conditions, or of its cells, in an analysis; the active version comes selected |
| Blank | no conditions, or no cells, in an analysis |
The menu of a published version offers the same path, with the version already chosen, under New version from this one. Editing a published version does not create a draft: the draft always comes from New version or from New version from this one. Creating a version requires the Editor or Administration profile.
A blank rule draft exists with no conditions, but the editor only saves the rule with at least one condition. Publishing requires the same.
Open drafts
A rule allows up to three open drafts at the same time. The rule page shows the count, such as 1 of 3 open drafts. With the limit reached, creating drafts is unavailable until a draft is published or discarded. The analysis has no such limit.
Archive and discard
Discard deletes a draft permanently.
Archive preserves the history and removes from the panel a rule, an analysis or an inactive rule version:
| Item | Effect | Restriction |
|---|---|---|
| Rule | the drafts are deleted and the inactive versions become Archived; a rule that only ever had drafts is deleted | refused while any version is active or in observation |
| Analysis | the analysis and all its versions are archived | refused while a published rule uses the analysis |
| Inactive rule version | the version becomes Archived | the active version and the version in observation are not archived |
The panel does not restore an archived item.
Comparison and publishing
Every version that can take effect (draft, inactive or in observation) shows the Publish button. With another version active, publishing requires reviewing the changes against it beforehand: the comparison screen opens positioned between the active version and the version to be published, and the publish button is in the comparison itself. With no active version, publishing asks only for a confirmation. The panel flags a rule with no published version, which only takes effect after the first publication.
The comparison covers the conditions and the actions. Each row corresponds to a condition. Colored rows indicate the conditions that changed, and a label identifies the change (added, removed, reordered, or altered). In the actions column, a struck-through action no longer applies and the one that replaces it appears after the arrow; an action marked with + is new. The comparison exposes the exact effect of publishing before the version takes effect.
In an analysis, each row corresponds to a cell, with the previous and the new value of each changed setting.
Conditions met
Each condition of a rule version records how many times it was met on each day. The panel shows the count on the condition itself, alongside the period’s total runs. The reading distinguishes three situations: the day the rule received no traffic, the day the rule ran without the condition being met, and the day the condition was met at least once.
The count locates the condition that is never met, whether because the expression does not match real traffic or because an earlier condition already filled the field it tests. A condition that is not met even once since publication is a candidate for review before the next version.
The count starts at the version’s publication and considers only real events: simulations are left out. A newly published version therefore starts with no reading.
Observation
Publish a version in observation (shadow) before it takes effect. The version in observation runs in parallel with the active version, over the same real events, and nothing it produces changes the event’s outcome: the decision remains the active version’s. The lifecycle becomes draft, observation and active.
An inactive version can also be put in observation. This evaluates a version already replaced without putting it back in charge of decisions. The active version is the only one that cannot be observed, since it is already deciding.
A version in observation is immutable, like the active one: editing it creates a new draft. The version promoted is exactly the one that was observed, with no rewriting of the actions.
Observed outputs
Observation is selective. When publishing, you mark which outputs you want to track. The platform writes each marked output to the same event, in a field with the _shadow suffix, next to the value the active version wrote. The _shadow field follows the storage settings of the source field (size limit, truncation, sensitivity and decimal places). A change to the source field that the observed twin cannot accommodate is refused. Unmarked outputs are discarded along with the rest of the run.
Since both values sit on the same event, the comparison uses the existing screens: filters in Explore, metrics and dashboards compare the field and its observed twin with no extra configuration.
Change the observed outputs at any time, without republishing the version. A version that fills no field has no outputs to observe and cannot be published in observation.
Every processed event also records the version in observation that processed it, besides the name and version of the active rule. Without that record, an observed value could not be attributed to the version that wrote it, since every revision is a new version.
What observation does not run
A version in observation does not change the shared state that other runs read:
- Actions that write to lists are suppressed. Conditions that consult lists keep reading the real list. A rule whose behavior is to feed a list and then consult it is observed approximately, not exactly.
- The analyses recorded by the version in observation sit in windows of their own, separate from those the active version feeds and consults.
The observation’s windows start empty and need a full retention of traffic before they mean anything. When the version is promoted to active, the windows start over from zero for the same reason.
In an event type with a version in observation, the event becomes visible in queries some moments after being received, rather than immediately. The write waits for the observed run so both values travel in the same record.
Analysis versions
An analysis follows the same cycle as a rule, with three particularities.
Every change to an analysis, whether a cell or the order of the cascade, is made in a draft, and publishing takes the whole set live at once. There is no publishing of an isolated cell: the cascade is published as a whole, and the cells never sit in different versions from one another.
An analysis allows several drafts at the same time, each starting from the version it came from. The analysis page shows the open drafts and the path to each one.
Changing what a cell measures, or the window in which it accumulates, discards the history already accumulated by that cell. The cell starts empty again and needs a full retention of traffic before it means anything again. The comparison flags this consequence before publishing, and confirmation is requested at the moment of the change. The analysis’s remaining cells keep their windows.
History
Each rule and each analysis has a history of the actions performed on its versions: creation, editing, publishing, publishing in observation, withdrawal from observation, replacement, unpublishing, discarding and archiving. Each entry records the version, the author and the moment.
The history shows the most recent actions and keeps the rest collapsed. The version list is the full record.
Traceability in events
Every event processed by a rule records the rule’s name and the number of the version that processed it, plus the version in observation, when there is one. This record reconstructs later which logic produced each value, even when the version has since been replaced or archived.
The run analysis action publishes the version of the analysis that decided an event in the version key, which a set field action writes to the event.