Clean Core Extensibility: Key-User Adaptation Projects Step by Step
Clean core, without the slideware
"Keep the core clean" means: stop modifying standard code — every modification is a tax paid at every upgrade. The alternative isn't "no customization." It's extensibility in the sanctioned layers.
For UI, that means adaptation projects: key-user and developer adaptations living outside the standard app, surviving upgrades.
This post builds a developer adaptation project for S/4HANA Cloud, step by step.
What an adaptation project can change
- Control variants and page views — different layouts per role.
- UI fragments at extension points — the clean way to inject fields and sections.
- Controller extensions — override or extend standard controller methods.
- App descriptor changes (manifest.json settings, original untouched).
- OData service — add or replace the consumed service.
- Component usages — reference other SAPUI5 components.
What's not there: editing SAP's views and controllers directly. That's the whole point.
Prerequisites (boring, but they block you)
- App released for extensibility by SAP — not every app is. Check first.
- 3-system landscape with a developer tenant (S/4HANA Cloud).
- Right business catalogs assigned (extensibility catalogs).
- On-premise (VS Code flow): SAP_UI 7.54+ / SAPUI5 1.72+, base app needs manifest.json. ABAP Cloud packages can't be used with on-premise adaptation projects.
Step 1: Create the adaptation project
In VS Code with SAP Fiori tools: Template Wizard → Adaptation Project → point at your base app. The wizard scaffolds a changes folder for your adaptations, separate from the base app's code.
That separation is the clean core.
Step 2: Open the Adaptation Editor
A WYSIWYG layer over the running app. Key users can already do a lot here: rearrange, hide, relabel, create variants.
Always check whether the requirement is solvable in the editor first. The best customization is the one with no code.
Step 3: Add a fragment at an extension point
Find the app's extension points (documented per app), add your fragment there. Example: a customer field group on the object page header. The fragment lives in your project; the framework merges it at runtime.
<!-- Fragment added at the standard app's extension point -->
<core:FragmentDefinition xmlns:core="sap.ui.core"
xmlns="sap.m">
<VBox>
<Label text="Customer Priority" />
<Text text="{Priority}" />
</VBox>
</core:FragmentDefinition>
Standard app untouched. Your addition upgrade-safe.
Step 4: Extend the controller (only if you must)
Behavior changes need a controller extension: override specific lifecycle methods or event handlers, call the base implementation where standard behavior should stay.
Rule of thumb: extend, don't replace. Every overridden line is a line you re-verify at upgrade.
Step 5: Preview, then deploy
Preview against the live app — the editor shows changes in context. Then deploy to the ABAP repository. The adaptation ships as its own transportable unit, applied on top of the standard app at runtime.
Key-user vs developer adaptation
Teams get this wrong, so: key users = layout changes in the editor (hide, move, relabel, variants). Developers = fragments, controller extensions, service changes.
Push everything you can to the key-user layer. Reserve developer adaptation for what genuinely needs code.
The upgrade test
Here's how you know it worked: at the next S/4HANA Cloud release, your adaptation applies cleanly on the new standard app. An extension point moved? You adjust one fragment — not re-apply a pile of modifications.
That's the ROI, and why customers mandate this approach in 2026.
Questions on a specific app's extension points? Comments are open.
Read more →