> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runorion.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Orion is a collaborative analytics platform built by Gravity (bygravity.com). It connects to data warehouses, to Looker and dbt for existing business logic, and to a small set of external-context sources, and it lets teams ask questions in natural language to get shared analyses, dashboards, reports, and slide decks. The Connecting Data Sources page is the authoritative list of supported sources. When referencing Orion features, always link to the relevant documentation page. Orion is not open-source; it is a commercial SaaS product accessed at runorion.com.

# History and Review

> Compare versions, restore one, and require approval for changes

Metrics, views, catalog metrics, dashboards, MDX reports and Workflows keep each version they are saved as. **History** lists those versions so you can compare them and restore one. A level on the item decides what else happens when it changes. The **Controlled** level holds changes to what an item says or does until an admin approves them.

> [!NOTE]
>
> History and review are available on select workspaces. Ask your Gravity contact to enable them.

History is not **Run history**. Run history, in the **More** menu of a Workflow dashboard, lists the results of earlier Workflow runs. [Sync to Git](https://docs.runorion.com/version-control/sync-to-git.md) explains what **Tracked in GitHub** commits, which items are always tracked, and where to set a level and who can.

## Where History appears

| Item | Where |
| - | - |
| Metric or view | **History** in the action row of the metric's side panel |
| Catalog metric | **History** in the header of the catalog metric, for admins and analysts |
| Dashboard | **History** in the header, beside the level menu |
| MDX report | **History** in the report header, in the editor and in the viewer |
| Workflow | **History** in the toolbar of the Workflow editor |

Slide decks and HTML dashboards have no **History** in Orion. Once published, each change to them is committed to GitHub, so their earlier versions are in the repository's history. See [Publishing](https://docs.runorion.com/version-control/sync-to-git.md#publishing) in Sync to Git.

A project copy of a catalog metric has no **History** button. Open the catalog metric instead. Anyone who can open an item can read its History, and restoring a version needs edit access.

Context pages other than [Structured Context](https://docs.runorion.com/core-concepts/structured-context.md) pages have no **History** button. Their change requests are listed under the **History** tab of the [review queue](https://docs.runorion.com/knowledge-base/creating-pages.md#reviewing-change-requests).

## Compare versions

**History** opens a panel with every version, newest first. A row shows the version number, when it was saved, who saved it, and the note if there is one. A change Orion made for someone reads **Orion on behalf of** their name. A version recorded when history began reads **Recorded when version history started**.

On an item at **Tracked in GitHub** or **Controlled**, with a repository connected, a version committed to GitHub shows the first seven characters of its commit. The selected version links to it as **v3 on GitHub**. The newest version reads **Committing** until its commit lands. Edits saved close together can share one commit, so an earlier version may show none.

A chip names the kind of change a version holds: **Definition**, **Meaning**, **Visibility**, **Settings** or **Look**. **Full snapshot** marks the first version that recorded settings and look, after versions that held only the definition, so what else changed in it is not known. Versions that changed only settings or look are hidden. Select **Show settings and look changes** to list them. The newest version always shows.

Under **Compare**, choose an **Older version** and a **Newer version**. The panel starts with the version you selected against the one before it. It shows added and removed lines for text such as SQL or Python code, and a table of changed fields. A dashboard also lists the cards added, removed or changed, and a report does the same for sections. Text that a run writes into a report is left out of the comparison.

## Restore a version

1. Open **History** and select an older version
2. Select **Restore this version**
3. Add a note if you want one, then select **Restore**

A restore saves the old content as a new version. Earlier versions stay in History, so a restore can itself be undone. The newest version and a version that records a deletion have no **Restore this version** button.

What comes back depends on the item:

* **Metric:** the definition, description, settings, look and who can see it. A saved schedule and pin come back too
* **View:** the name, program, frame, Python and sources. Today's data completeness and pin stay as they are. A view that comes from a notebook keeps its program and sources, and a version that would change them cannot be restored. A version with no sources cannot be restored while the view has some
* **Catalog metric:** the definition, name and description. Owners and folder stay as they are, and every project that uses the metric follows
* **Dashboard:** the layout and cards, the name and who can see it. Metrics stay on their current version
* **Workflow:** the steps, name, description and schedule. The steps are checked as for any edit, so a version that no longer passes, for example because it uses a metric that was deleted, cannot be restored and nothing changes. A dashboard that a removed step published is linked to the Workflow again, as long as the notebook the dashboard came from is still in that step. If it is not, the restore is refused and nothing changes. Who can see the Workflow comes back only if you may change it, and who the Workflow runs as does not come back
* **MDX report:** the sections, text and look. Text that a run writes stays as it is now, so a restore never brings back old numbers. Who can see the report comes back only if you may change it

Workflows have no review step, so a Workflow restore saves directly, as an edit does. Nothing runs until the next scheduled run or **Run Now**, and the steps use the metrics and notebooks as they are now. On a Controlled item, an admin who can approve changes restores directly. For everyone else the button reads **Request restore**, and **Send for review** files the restore as a change request. Nothing changes until an admin approves it.

## Review changes to a Controlled item

A Tenant Admin can make an item Controlled and take it off. So can a [Group Admin](https://docs.runorion.com/configuration/groups.md#roles-at-a-glance), for items in projects that belong only to the groups they manage. See [who can change a level](https://docs.runorion.com/version-control/sync-to-git.md#who-can-change-a-level). For dashboards, reports and metrics, the same people can approve or reject a change. A catalog metric belongs to no project, so only a Tenant Admin can make it Controlled or approve a change to it. Context pages have their own reviewers, listed under [Context pages](#context-pages).

What goes to review depends on the item:

| Item | Goes to review | Saves directly |
| - | - | - |
| Metric or view | Name, code, data sources, engine, value type, a view's program and frame, description, chart type, and who can see it, including the share toggle | Schedule and chart settings other than chart type, when sent on their own |
| Catalog metric | Name and definition | Owners, folder, and the description when edited on its own |
| Dashboard | Everything except look | Look: theme, custom CSS, shell HTML, columns, card grid, grid options, chart options and number format |
| MDX report | Everything except look | Look: theme, logo, appearance, section layout and grid options |
| Context page | Every edit, including the creator's and an admin's | Nothing |

On a Controlled dashboard or report, changing who can see it is not sent for review. Only someone who can make the item Controlled can change it, and they change it directly. A metric that a Controlled dashboard uses needs approval too. Its chip names the dashboard, as in **Needs approval: used by Sales (Controlled)**, or counts them, as in **Needs approval: used by 3 dashboards (Controlled)**.

### Dashboards and reports

1. Edit the Controlled dashboard or report. The save button reads **Save draft**. Before the first save, a banner reads **Controlled dashboard** or **Controlled report** and says saving creates a draft for review. After it, the banner reads **Editing a draft**. Viewers keep seeing the published version. Only you see the draft until you submit it.
2. Select **Submit for review**. Until the draft is saved, and while you have unsaved edits, the button is disabled and a note beside it reads **Save the draft first**.
3. Write the note under **What changed? (required)** and select **Submit**. The draft shows **Waiting for review**, and **Save an edit to change it** appears beside the button.

A draft is based on the version that was current when it was last saved. If someone publishes another version first, Orion refuses to approve the draft until the editor saves it again and resubmits. Each editor has one open draft. **Withdraw** takes the draft out of the queue and returns the editor to the published version, and unsaved edits are lost.

A reviewer sees a pill in the header that reads **1 change waiting for review**, or **3 changes waiting for review** when there are several. A Tenant Admin can also open the request from the [Inbox](https://docs.runorion.com/chat/inbox.md). The review panel compares the published version with the proposed one. Add a note if you want one, then select **Approve and publish** or **Reject**. The change goes live under the editor's name with their note.

After a rejection the banner reads **Rejected** with the reviewer's note, and **Start a new draft** begins again from the published version.

### Metrics, views and catalog metrics

A metric has no draft. Save a change that needs approval and the side panel opens a form. Write why, then select **Send for review**. The note is required. Sending another change replaces your pending one.

A reviewer opens the request in the metric's side panel and sees each field before and after. Select **Approve and apply** or **Reject**. The metric runs as soon as a change is approved. The sender can **Withdraw** a pending request.

If the metric's definition, description, chart type or sharing changed after the request was sent, Orion refuses to approve it until it is sent again. For a view or a catalog metric, any new version counts. It also refuses when the sender can no longer edit the metric. Reject the request, or ask someone who can edit the metric to send it again.

On a catalog metric, a new name needs a **Reason for a name change**. A definition change needs a **Change summary**, even though the field reads optional. Both go to review the same way.

### Context pages

The level menu sits in the page header, beside **Edit**. On a Controlled page the save button reads **Submit for review**. A panel asks for a note under **What changed and why (required)**, and **Confirm & submit** sends it. Reviewers use the [change request queue](https://docs.runorion.com/knowledge-base/creating-pages.md#reviewing-change-requests). A Tenant Admin, the page's creator, or a Group Admin of a group that has the page or a parent folder enabled can approve a request. The creator and a Group Admin cannot approve their own change.

### Who hears about it

For a dashboard, report or metric, each Tenant Admin except the sender gets an [Inbox](https://docs.runorion.com/chat/inbox.md) item asking for a review, and it clears once the request is decided. Project owners who are not Tenant Admins get a notice that a change was sent. For a Context page, each Tenant Admin gets an Inbox item, and the page's creator gets an email when someone else sends a change. In every case the sender gets a notice when it is approved or rejected.

## Deleting a Controlled page

A Controlled Context page always deletes through a change request. Admins and the page creator are no exception. Orion shows **Submitted for review**, and the page stays until a reviewer approves the deletion. A folder or page with a Controlled page anywhere below it takes the same route, because deleting it would delete that page too.

> [card] [Sync to Git](https://docs.runorion.com/version-control/sync-to-git.md)
>
> Connect a repository and choose what is committed

> [card] [Creating Context Pages](https://docs.runorion.com/knowledge-base/creating-pages.md)
>
> Lock pages and review change requests


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.