Overview
Astrato supports structured promotion of workbooks across environments — typically DEV → UAT → PROD. Each environment contains two key components:
Workbook — the dashboards, charts, and visualizations your users interact with.
Semantic Layer — the data definitions, field logic, data connections, and access control that power the workbook.
When promoting a workbook to another environment, you choose how the semantic layer is handled. There are three options.
Option 1 — Move Workbook and Semantic Layer Together
The workbook is added as a new version in the destination workbook, and the semantic layer travels with it. The destination environment's semantic layer is fully replaced by the source.
Best for: Initial promotions where the destination environment has no existing configuration, or when you want the destination to be an exact mirror of the source.
Option 1: Move the Workbook and the Semantic Layer together
What moves | What happens in the destination |
Workbook (as new version) | New version added to the destination workbook |
Semantic Layer | Destination SL is replaced by source SL |
Option 2 — Move Workbook Only (Connect to Existing Semantic Layer)
Only the workbook is promoted. The semantic layer stays in the source environment and is not moved. In the destination, the promoted workbook connects to the existing destination semantic layer.
Best for: Situations where the PROD (or UAT) semantic layer is already correctly configured with the right data connections and access controls, and you only want to update the workbook content.
Option 2: Move Workbook only, connect to destination Semantic Layer
What moves | What happens in the destination |
Workbook (as new version) | New version added to the destination workbook |
Semantic Layer | Unchanged — workbook connects to existing destination SL |
⚠️ Requires a published destination workbook.
Option 3 — Override Destination Semantic Layer (with Rollback)
The workbook is promoted, and the destination semantic layer's definitions and logic are overridden with those from the source. However, the destination's data connections and user access control are preserved — they are not overwritten.
A copy of the existing destination semantic layer is saved automatically before the override, allowing you to roll back if needed. The transferred version is also published automatically in the destination container.
Best for: Promoting updated semantic layer definitions from DEV/UAT to PROD, while keeping PROD's data connections and security settings intact.
Option 3: Override destination Semantic Layer, preserve connections and access control, with rollback backup
What moves | What happens in destination |
Workbook (as new version, auto-published) | New version added and published |
Semantic Layer definitions | Destination SL definitions overridden by source |
Data connections | ✅ Destination's connections are preserved |
User access control | ✅ Destination's access control is preserved |
Old destination SL | Backed up as a copy for rollback |
⚠️ Requires a published destination workbook.
Choosing the Right Option
Scenario | Recommended option |
First-time promotion to a new environment | Option 1 |
PROD SL is already set up correctly; updating workbook only | Option 2 |
Promoting updated SL logic while keeping PROD connections & access control | Option 3 |
How to Promote a Workbook
Open the workbook you want to promote.
Open the version history and select the version to promote.
Click Copy version to another workbook.
Select the destination workbook.
Choose one of the three semantic layer options described above.
Click Copy.