Scenario: change one value for one customer
Lesson 21 of 25 6 min read
Work through a customer-specific change from request to proof, choosing between an overlay and an edit.
The most common request you will get is "can we have this one thing different for this customer?". This lesson walks through it end to end, including the decision that trips people up: overlay or edit.
Moorland Candles wants a fixed carrier code
Moorland Candles uses Acme API for warehouse orders. Their contract with Acme says every order must carry the carrier code ACME-STD, but the shared map takes the carrier from the order. Everyone else is happy with the shared behaviour.
Step 1: find out what Moorland runs
Open Moorland Candles, then Settings → Maps & Profiles → What actually runs. Choose Create map, Acme API and warehouse orders, then Resolve.
How it was assembled shows one item: Acme orders v2, Shared base. So Moorland runs the shared base, and you should overlay it.
If it had shown Moorland's own map, you would edit that instead, because Moorland cannot publish an overlay onto its own map for the same slot. If it already had an overlay, you would edit that overlay rather than adding another, because the organisation can publish only one create map for Acme API warehouse orders.
Step 2: find the node id
In the same result, open the Tree and find the carrier node. Note its node id, for example order.carrier. Your overlay will target that id.
Step 3: create the overlay
Open Create maps, select Add, choose Acme API and warehouse orders, and in Layers onto select Acme orders (Shared base). Leave Hold this on one version of its base off so Moorland follows future base improvements. In Body, put only the change: set order.carrier to ACME-STD. Name it Acme orders: Moorland carrier and select Create draft.
Step 4: check the end result
Select End result. You want to see:
- the chain Root: Acme orders v2 → Overlay 1: Acme orders: Moorland carrier v1;
- Overlay 1 changes 1 node:
order.carrier; - a solid chip on
order.carrier, and Root v2 everywhere else.
If the summary says changes nothing, or lists more nodes than you expected, stop and check the body.
Step 5: publish and prove
Select Publish, then Publish in the dialog, then Done. Back on the overview, run What actually runs again: How it was assembled now shows the shared base and your overlay, and with Only overlay changes on, Who wrote each node shows order.carrier.
If this later moves into the shared base
If the carrier rule is later built into the shared base for everyone, Moorland's overlay will still be there, and still win. Check it with End result: if it now changes nothing, it can be retired. The developer notes describe releases retiring overlays like this automatically, but confirm rather than assume.
Recap
- Start with What actually runs to see whether the customer runs a shared base, its own map, or an existing overlay.
- Shared base: overlay it. Own map or existing overlay: edit that.
- Find the node id in the tree, and put only that change in the overlay body.
- Check End result before publishing, and What actually runs after.
- Leave the overlay floating unless there is a reason to pin it.
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.