Roots and overlays
Lesson 5 of 25 7 min read
A root holds a whole specification; an overlay holds only changes to its base. Learn when to use each, and how an overlay follows its base.
Customers rarely need a whole new map. Usually they need the shared one with one or two things different: a fixed priority, an extra field, a different date. Overlays exist for exactly that. In this lesson you will learn what an overlay is, what it can sit on, and the three ways it can follow its base.
Root or overlay
| Kind | What it holds |
|---|---|
| Root | The whole specification. |
| Overlay | Only the changes to a different map or profile, its base. |
An overlay lets one organisation change part of a map or profile and keep everything else. When the base improves, the organisation gets the improvement, because its overlay only holds its own differences.
How an overlay points at things
Each part of a body that can be changed has a node id, such as order.priority. An overlay is a list of changes, and each change names the node id it targets. That is why Prism shows node ids so prominently in diagnostics, in End result and in What actually runs: they are how you aim an overlay.
Here is the shape of an overlay body from the developer documentation, which replaces one value:
{
"operations": [
{ "op": "setExpression",
"target": "node.reference",
"expression": { "op": "literal", "id": "expr.override", "value": "FIXED" } }
]
}
You do not need to write these yourself, but recognising one helps you read what an overlay does.
What an overlay can sit on
Remember the rule from the last lesson: an organisation can publish only one map or profile for each kind, integration type and document type. That has a consequence:
- An overlay is usually onto a shared base.
- You can create an overlay onto the organisation's own map or profile for the same integration type and document type, but you cannot publish it, because the overlay would be a second published definition for the same slot.
- To change the organisation's own map or profile, edit it instead.
A quick decision
Does the organisation run a shared base? Overlay it. Does it run its own map or profile? Edit that.
Floating, pinned and held
An overlay follows its base in one of three ways:
| Shows as | Meaning |
|---|---|
| Floating | It follows each new published version of its base. This is the default. |
| Pinned | It stays on one version of its base, because someone chose that. |
| Held | It was moved off its base because a new version of the base broke it. |
Pinned and held look similar but mean different things. Pinned is a choice someone made, and a new version of the base never moves it. Held is a parking place that a publish put the overlay in because moving it would have broken it. A held overlay is a debt: it is missing whatever the newer base version changed.
Good to know
The developer notes say a chain can be more than one level deep: an overlay can sit on another overlay. Prism's End result names them Overlay 1, Overlay 2 and so on. In day-to-day work you will mostly see one overlay on a shared base.
Recap
- A root holds the whole specification; an overlay holds only changes to its base.
- Overlays target node ids, such as
order.priority. - Overlay a shared base; edit the organisation's own map or profile rather than overlaying it.
- Floating follows the base, pinned stays by choice, held was parked because a new base broke it.
- A held overlay needs someone to fix it.
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.