Create an overlay
Lesson 14 of 25 6 min read
Change part of a shared base for one organisation, choose whether the overlay floats or is pinned, and know what you can and cannot publish.
An overlay is how you give one customer something different without copying, and then maintaining, a whole map or profile. In this lesson you will create one onto a shared base and decide how it should follow that base in future.
Before you start: is an overlay the right tool?
Use this check:
What actually runs (later in this course) tells you which of these applies.
Create the overlay
- Open the list of the kind, then select Add.
- Select the Integration type and Document type.
- In Layers onto, select the base. The list shows only published maps and profiles, with Shared base or This organisation next to each one.
- To keep the overlay on one version of the base, set Hold this on one version of its base to on, then select the Base version. If it is off, the overlay follows each new version of the base.
- In Body, type only the changes.
- Select Create draft.
When you choose a base, Prism lists that base's versions and starts the body in the overlay form, ready for your changes.
Floating or pinned?
| Choice | Result | When to use it |
|---|---|---|
| Hold this on one version of its base off | Floating: follows each new published version of the base. | Almost always. The customer gets base improvements, and a publish that would break the overlay is caught first. |
| On, with a Base version | Pinned: stays on that version. A new base version never moves it. | When the customer must not change until they have tested, for example during a peak trading period. |
Pins do not unpin themselves
A pinned overlay stays where it is until someone rebases it. If you pin for a reason, write the reason and an end date in your ticket, or the customer can drift many versions behind without anyone noticing.
What you can and cannot do with an overlay
- You cannot validate an overlay on its own. Supply Lens checks it with its base when you publish it. Use End result before publishing to see what it produces.
- You cannot publish an overlay onto this organisation's own map or profile for the same integration type and document type, because the organisation can publish only one of each. Edit the organisation's own map or profile instead.
- You cannot layer onto a draft. The Layers onto list only shows published maps and profiles.
Express orders for Hilltop Coffee
Hilltop Coffee wants every Acme warehouse order sent as express. Hilltop runs the shared base Acme orders v1, and the base already has a node order.priority.
You open Create maps, select Add, choose Acme API and warehouse orders, and in Layers onto select Acme orders (Shared base). You leave Hold this on one version of its base off, so Hilltop keeps getting base improvements. Your developer gives you a one-operation body that sets order.priority to express. You name it Acme orders: express and select Create draft. Next, you will check its end result.
Recap
- Overlay a shared base; edit the organisation's own map or profile; create a root when nothing exists.
- Layers onto lists only published bases, marked Shared base or This organisation.
- Leave Hold this on one version of its base off to float; turn it on and pick a version to pin.
- The body holds only the changes.
- Overlays cannot be validated alone, and cannot be published onto the organisation's own definition for the same slot.
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.