Adaptation Projects for Fiori UI Extensibility

An adaptation project is built in SAP Business Application Studio against an existing Fiori elements (or freestyle) app and generates a delta: an app variant descriptor referencing the original app id, plus a set of change files describing manifest edits, hidden or added UI elements, and optionally controller extensions. Nothing about the original app is copied or rewritten. The structural fact that explains most confusion: the adaptation is not a fork of the app, it is a layer resolved at runtime on top of whatever version of the original app is currently deployed. That is why the same adaptation project can work fine in the sandbox and then fail silently or throw an error in production after SAP ships a feature update to the underlying app - the element ids or fragment structure the delta references may no longer exist in the new version.

Use an adaptation project for cosmetic and structural UI changes that do not require new backend data: hiding or reordering table columns, renaming field labels, adding a custom section or field to an object page, adding an extension point fragment, or exposing the app under a different tile for a specific business unit. Do not use it to add new business logic, a new screen flow, or a field that does not already exist in the OData service payload - the field has to be added at the CDS/service layer first via custom field extensibility, and the adaptation project only repositions or reveals what is already exposed. It is also the wrong tool when every user of the app, regardless of role, should see the change permanently; that is better handled by changing the standard configuration or the backend annotation itself rather than layering a variant on top.

Below the adaptation project sits the standard Fiori elements app, itself generated from CDS view annotations bound through a service definition and service binding, consuming an OData service. The adaptation project references that app's manifest and view structure by id. Above it sits the Fiori Launchpad, which either shows the original tile unchanged or, for an app variant, registers a new tile pointing at the adapted variant with its own semantic object and role assignment. It supersedes the older pattern of duplicating an app's full UI5 source in Web IDE and modifying it directly, which required carrying forward manual merges on every SAP update. It complements, rather than replaces, in-app key-user 'Adapt UI' runtime adaptation, which is simpler, needs no BAS or transport, but cannot add controller extensions or new fragments.

A business unit wants the Net Value column removed from a sales order list report and a custom field, Regional Risk Score, shown on the object page's general information section, but only for its own users. The backend team first adds the custom field through custom field extensibility, exposes it in the relevant CDS view extension, and confirms it appears in the OData service payload. A developer then opens Business Application Studio, creates an adaptation project against the standard sales order Fiori elements app, and uses the UI adaptation editor to remove Net Value from the table's column list - a manifest-level change - and add the custom field to the general information section through an extension point wizard, which generates a change file referencing the property already present in the service. The project is deployed as an app variant with its own semantic object, given a new launchpad tile, and assigned only to the target business unit's role. The original app and its tile remain untouched for everyone else.

On-premise S/4HANA still supports controller extensions in adaptation projects through an access key, but that path is discouraged under a clean core approach because it couples the customer's extension to the internal structure of SAP's UI code. Manifest-only adaptations that need no access key are the preferred pattern under current extensibility guidance. On S/4HANA Cloud public edition, the permitted surface is generally limited to in-app key-user adaptation and manifest-based adaptation projects without controller extension; anything requiring local UI5 code changes or an access key falls outside supported extensibility. Older ECC-era customer modifications built as full UI5 app copies are the pattern adaptation projects are meant to retire, and migrating them off is a recurring workstream during an S/4HANA conversion.

Simple field visibility and layout changes belong to the functional or key-user side through in-app Adapt UI. Anything built as a formal adaptation project in Business Application Studio, especially with controller extension or extension points, belongs to a Fiori/UI5 developer. Handover should include the app variant id, the exact version of the standard app it was built against, and the list of referenced manifest properties or element ids so regression testing can target them after every upgrade of the underlying app.

Read fiori-elements-list-report-and-object-page first to understand what an adaptation project is actually layering changes onto. Read extending-a-rap-business-object and cds-annotations-and-where-they-take-effect for the backend side of exposing a new field before an adaptation project can surface it. Read fiori-elements-versus-freestyle-fiori when the real answer is that the requirement has outgrown what adaptation can deliver.