Definition versions and approval

When a number changes, the first question is usually “did the data change, or did the definition?” Querri keeps every version of a definition, so you can answer that, put an old one back, and, if your organization wants it, have a second person sign off on each change.

Overview

A definition is the part of the Library that decides how a number is worked out:

• a metric (KPI): its query, table, grain, unit and categories
• a rule (a fact on the Facts & Rules tab): its statement, kind and what it’s about
• a view: the query that builds the table

Every change to one of these is saved as a new numbered version, with who made it, when, and why. Nothing is overwritten, and nothing in the history is ever rewritten.

Your organization can also turn on Require approval for definition changes. Then each change to a view or metric is marked Pending approval until someone other than its author approves it.

What a version records

Each version shows:

• Its number, like v3. The version in use is marked Current.
• Who made it. A person, or The assistant, An API key or Unknown author. Your own changes say You.
• When.
• Where it came from: In the app, Assistant, API, Blueprint, Restore or Deleted. A definition that existed before versions were kept starts with a Baseline version.
• The reason, when one was given.
• Its approval, such as “Approved by” and the approver’s name, with their note if they left one.

A save that changes nothing doesn’t make a new version. A version marked Did not take effect was attempted but never applied, so the definition stayed as it was.

The History panel

Open a metric, a rule or a view from the Library and expand History (its hint reads Versions and approval). It lists every version, newest first. The panel loads only when you open it.

At the top, the panel says where the definition stands:

Header	What it means
Approved by name on date	The version in use is approved.
Matches approved vN	The version in use isn’t approved itself, but it’s identical to an approved one, usually because someone restored it.
Changed since approval	An earlier version was approved and the definition has moved on since.
Not approved	No version has been approved.

If no versions are recorded yet, the panel says the next edit will record the current definition as version 1 first.

Compare two versions

Click Compare on a version to see Changes in vN, side by side. It’s compared with the version before it unless you pick another under Compared with. Long text, like SQL or a rule’s Statement, is shown line by line. If nothing in the definition differs, it says “No part of the definition changed.”

Restore an older version

Click Restore on a version, add a reason if you like (“Why are you going back to this version?”), and confirm with Restore vN.

Restoring doesn’t delete anything. The old definition comes back as a new version, marked Restored from vN, and the history stays as it was. For a view, the table is also rebuilt.

Before a metric or view is restored, Querri checks that its query still runs against the tables as they are now. If a table has changed so the old query no longer works, the restore is refused and nothing changes. If you restore the version that’s already in use, it tells you nothing was changed.

Who can change definitions

The person who can edit a metric, rule or view in the Library can change it and restore an older version of it. For a view, that’s its owner or someone who can manage it. Anyone who can see the item can read its history.

Approving is separate. It needs the Approve definitions permission, which is on for the Admin role by default. An admin can change this per role in Settings → Roles. Without it, people can still read history but don’t see Approve or Withdraw approval.

Require approval for definition changes

This setting asks for a second pair of eyes on every change to a view or metric definition.

Who can turn it on: admins who can edit Settings → Customize (the page titled Context Settings). Find Definition approval, tick Require approval for definition changes, and click Save Settings. See Customize.

Pending approval is a label, not a hold

Turning this on doesn’t stop a change from taking effect. The setting’s own note says: “Changes still take effect immediately.” A changed definition is in use the moment it’s saved, and every number built on it already uses it. Pending approval tells people that number rests on a change nobody else has checked yet. It doesn’t hold the change back.

What counts as a change

Only changes need approval. A definition’s first version never does: creating a metric, installing a Blueprint, or the baseline recorded for an older definition. Restoring a version someone already approved doesn’t need approving again either, since it carries that approval.

The setting covers views and metrics. Rules keep a full history, and someone with Approve definitions can approve a rule’s version from its History, but a changed rule isn’t marked Pending approval and doesn’t file an Inbox card.

What people see

While a change is waiting:

• A Pending approval badge shows on the view or metric, in its detail panel, in the metrics list and in its History. Hover it to read: “This definition was changed and the change has not been approved yet. It is already in effect, and so is every number built on it.”
• An Approval needed card goes to the Inbox. Its headline reads “Definition change awaiting approval:” with the definition’s name and version, and it explains that the version is already in effect. It has Open definition, and, for people who can approve, Approve vN.

The card goes to the workspace the definition lives in, and only people who can see that view or metric see it. A metric in someone’s private workspace gets a card only that workspace’s members can read.

Turning the setting on marks every view and metric that already has an unapproved change at once. Inbox cards are filed for changes made from then on. Turning it off closes every open approval card.

Approve a change

1. Open the Approval needed card, or the definition’s History.
2. Click Compare to read what changed.
3. Click Approve vN on the card, or Approve in History.
4. In History, you can add a Note (optional), then confirm.

The approval belongs to that exact version. Any later change starts out unapproved again. Approving closes the card and clears the badge.

An approval can be taken back with Withdraw approval in History.

Each approval and withdrawal is also written to the Audit Log.

You can’t approve your own change

The person who approves must not be the person who made the change. That holds however the change was made:

• You made it in the app. Someone else approves it.
• The assistant made it for you. You asked for it, so you’re its author. The refusal reads: “Version N was written by the assistant on your behalf, so you are its author. Someone else must approve it.”
• A Blueprint you installed made it. You’re its author.
• An API key that acts as you made it. You’re its author.

Approving has to be done by a person signed in to Querri, not through an API key or an embedded session.

A few changes have no person who can be named as their author, so nobody can show they didn’t write them, and they can’t be approved:

• a change the assistant made with no person behind it
• a change made through an embedded session that doesn’t name a person
• a change made through an API key that has since been deleted
• a change that took effect without a version being recorded at the time

The card for one of these says so and has no Approve button. Restore that version from History: the restore is recorded with you as its author, and someone else can then approve it.

A version nobody wrote is different. An older definition from before versions were kept, including an old view version with no author on record, is treated as the baseline: it isn’t marked Pending approval and doesn’t file a card. A change Querri’s system made, rather than a person, can be approved by anyone with Approve definitions.

The card stays until it’s answered

An Approval needed card can’t be dismissed, accepted or rejected like other cards. It closes only when the change is approved, when a newer change replaces it, or when the setting is turned off. You can still snooze it or discuss it.

When a view change moves your metrics

Changing a view changes every metric measured from it. Querri checks for that after a view is rebuilt on a new definition. For each metric built on the view, it compares the latest period’s new value with what the old definition reported. If any moved by a meaningful amount, the person who made the change gets a Definition change card in their Inbox.

What “meaningful” means:

• a period that gained or lost its value always counts
• a change under 2% never counts
• a change of 25% or more always counts
• in between, it counts when the move is unusual for how that metric normally changes from period to period

The card says how many metrics moved, who made the change and when, and whether the change is approved or awaiting approval. Under What moved, it lists each metric with its old and new value, as old → new, and the versions involved. It lists only the metrics you can see, and says how many more there are.

You then choose:

• Revert to vN puts the previous version back, as a new version, and rebuilds the view.
• Keep vN keeps the new definition.

Querri never reverts anything on its own. If the approval setting is on, a view change that moved metrics files both cards: Approval needed for an approver, and Definition change for the person who made it.

Using the API

Coming soon: these routes aren’t in the current release yet. The public API will read and change the same history. kind is kpis, facts or views.

Method	Path	What it does
GET	/library/{kind}/{id}/versions	List versions, newest first, each with its approval status
GET	/library/{kind}/{id}/versions/{v}	One version, with the full definition
GET	/library/{kind}/{id}/versions/{v}/diff	What changed, against ?against= (default: the version before)
POST	/library/{kind}/{id}/versions/{v}/restore	Restore a version as a new one. Body: {"reason": "..."}
POST	/library/{kind}/{id}/versions/{v}/approve	Approve a version. Body: {"note": "..."}
POST	/library/{kind}/{id}/versions/{v}/unapprove	Withdraw an approval
GET	/library/views/{id}/impact	What reads the view, and what a change did to the metrics built on it (?version=)

Reading needs the admin:library:read scope. Restoring, approving and withdrawing need admin:library:write. An item you can’t see returns 404, not 403.

An approval has to come from a person signed in to Querri. approve and unapprove return 403 when called with an API key or from an embedded session, so approve in the app instead.

Next steps

• One number, one definition: settle a number people disagree on.
• Write down definitions and rules: record your rules where Querri reads them.
• KPI details: the metric panel.
• Inbox: where approval and impact cards land.
• Audit Log: approvals and withdrawals are recorded there.