What can change under a model
A semantic model can depend on two things that move on their own:
| Source | What changes | Where you see it |
|---|---|---|
| System package | TagPipes publishes a newer version of a package the model was built from | The Package box on the model page, with Review update |
| Terrain | Your Data Dictionary agrees a newer version of a term a metric, field or segment links | Terrain Concepts on the model page, with Review N Updates |
In both cases nothing changes until you choose an action, and every action saves a new revision of the model. Earlier revisions stay in its history.
Upgrade a system package
- Open the model. In the sidebar, the Package box shows "Installed: X · Version Y available". Click Review update.
- Read the review page:
| Section | Shows |
|---|---|
| Installed → Proposed | The two versions, and Ready to upgrade or Needs attention |
| What changes | Built-in definitions your model uses that the new version changes |
| New in this version | Definitions the new version adds. They are offered, never added: add them in Edit Model if you want them |
| What stays the same | Definitions the upgrade does not touch |
| Your model customizations | Built-in definitions you changed, and what happens to each |
| Validation | Whether Check passes on the upgraded model |
- Click Upgrade to Y, or Cancel to stay on the installed version.
How your changes are kept
- A built-in definition you never changed takes the new version.
- A definition you customized is kept exactly when the package did not change it, and combined with the package's change when the two changed different properties.
- If the package and your model changed the same property differently, the upgrade is blocked. Lens will not choose between them.
- If the new version removes a definition your model uses, with no replacement, the upgrade is blocked.
- Your table connections, column mappings, row rules, reporting timezone and everything you added yourself carry over unchanged.
When the upgrade is blocked, resolve the listed items in Edit Model first. The model stays on the installed version until then.
Record Terrain coverage
The Terrain Concepts panel on the model page lists the agreed terms in this property's Data Dictionary and what the model does with each. A term is Implemented when a metric or field in the model links it (set in the editor). For the rest, pick a status:
| Status | Use when |
|---|---|
| Not reviewed | The default. Not counted as work. |
| Needs setup | The model should have it but does not yet. |
| Not applicable | The model has no reason to cover it. |
| Unavailable | The data cannot provide it. |
Add an optional note, use Search and Show to filter the list, and click Save Statuses. A save changes only the model's Terrain references, never a metric, field or query.
Review a Terrain update
- On the model page, click Review N Updates in Terrain Concepts, or Review on one term.
- For each term, read What changed in Terrain: the version note and a field-by-field table of the linked version against the agreed one.
- For each segment copied from the term, compare the rules now in the model with the rules in the new version. Click Preview Impact to see the segment's metric over the last 7 complete days, in the model's reporting timezone, on the current rules and on the new ones. The preview runs the question twice, so it only runs when you ask.
- Check Board tiles and saved analyses that use it. These show the new numbers as soon as the update is accepted.
- Pick an action:
| Action | Shown when | What it does |
|---|---|---|
| Accept vN | The term has segments | Copies the new version's rules into the segments |
| Still matches - move to vN | Metrics or fields link the term | Moves their links to the new version. Nothing in them is copied from Terrain, so read what changed first |
| Needs a model change | Metrics or fields link the term | Marks the term Needs setup with your note (required, up to 500 characters). The links stay on the old version |
| Keep current version | Always | Records that you reviewed the new version and kept the old one |
A term that Terrain retired shows Term retired. The model keeps working as it is; replace or remove the links in Edit Model when you are ready.
Check it worked
The model page's History shows a new revision. In Terrain Concepts, an accepted or moved term shows Implemented and "Linked at vN"; a kept one shows "kept after reviewing vN". After a package upgrade, the Package box shows the new version.
Troubleshooting
| Symptom | Cause |
|---|---|
| Upgrade is disabled | The review found a conflict or a removed definition. Fix the listed items in Edit Model. |
| Accept is disabled | The new version cannot be copied into one of the segments. The reason is shown above the button. |
| An action is refused | The model or the Terrain term changed after the page loaded. Reload and review again. |
| "Terrain could not be read just now" | The Terrain list could not load. Reload the page. |