gh-secondsky-sap-skills-skills-sap-fiori-tools/references/adaptation-projects.md

Adaptation Projects Reference

Comprehensive reference for creating and managing SAP Fiori adaptation projects.

Table of Contents

1. Overview
2. On-Premise Systems
3. S/4HANA Cloud and BTP ABAP
4. Creating Adaptation Projects
5. Adaptation Capabilities
6. Controller Extensions
7. Fragments and Extension Points
8. Preview and Testing
9. Deployment
10. Upgrade-Safe Rules

---

Overview

Adaptation projects allow extending existing SAP Fiori applications without modifying source code. They create application variants that maintain separation from the original application.

Benefits

• Non-invasive extensions
• Independent lifecycle from base application
• Upgrade-safe modifications
• Version control support

Supported Environments

Environment	IDE Support	Deployment Target
On-Premise ABAP	VS Code	ABAP Repository
SAP S/4HANA Cloud	BAS	BTP ABAP Environment
SAP BTP ABAP	BAS, VS Code	BTP ABAP Environment

---

On-Premise Systems

Prerequisites

Requirement	Version/Details
SAP_UI Component	7.54 or higher
System SAPUI5 Version	1.72 or higher
Base App SAPUI5 Version	1.30 or higher
Base App	Must have manifest.json

Limitations

• Cannot use ABAP Cloud Development packages
• Apps with mandatory startup parameters unsupported
• Previously deployed application variants cannot serve as bases
• Apps using sap.ca.scfld.md scaffolding unsupported

Required Services

Enable and activate:

• /sap/bc/adt - ABAP Development Tools
• /sap/bc/ui2/app_index/ - Application Index

Grant access to:

• /sap/bc/adt/discovery

Workflow

1. Create adaptation project
2. (Optional) Initialize Git repository
3. Make adaptations
4. Preview adaptation project
5. Deploy to ABAP repository

---

S/4HANA Cloud and BTP ABAP

Prerequisites

SAP S/4HANA Cloud:

• Verify extensibility support in SAP Fiori Apps Reference Library
• 3-system landscape with developer tenant required
• Submit enhancement requests via Influence Opportunity Homepage if needed

Both Environments:

• Source application must be "released for extensibility"
• Destination to development tenant configured
• Required business catalogs assigned

Required Business Catalogs

Catalog	Purpose
SAP_A4C_BC_DEV_UID_PC	Development - UI Deployment
SAP_A4C_BC_DEV_OBJ_DIS_PC	Retrieve extensible applications

Destination Configuration

Create destination in BTP Cockpit pointing to development tenant with appropriate authentication.

---

Creating Adaptation Projects

Via Template Wizard

1. Open Command Palette: Cmd/Ctrl + Shift + P
2. Execute: Fiori: Open Template Wizard
3. Select "Adaptation Project" tile
4. Configure project settings

Configuration Fields

Field	Description
Project Name	Unique project identifier
Application Title	Display title
Namespace	Prefixed with customer.
SAPUI5 Version	Target UI5 version
Target System	SAP system connection
Application	Base application to extend

Via Generator Command

Fiori: Open Adaptation Project Generator

Add Deployment Configuration

Optional during creation or added later via:

Fiori: Add Deployment Configuration

---

Adaptation Capabilities

UI Adaptations

Adaptation	Description
Control Variants	Create page variants/views
Hide/Show Controls	Toggle control visibility
Move Controls	Reposition UI elements
Rename Labels	Change display texts
Change Properties	Modify control properties

Structural Changes

Change	Description
Add Fragments	Insert UI fragments at extension points
Controller Extensions	Override/extend controller methods
Component Usages	Add SAPUI5 component references

Configuration Changes

Change	Description
App Descriptor	Modify manifest.json settings
OData Service	Add/replace OData services
Local Annotations	Add annotation files
Inbound Navigation	Modify navigation configuration

Adaptation Editor UI Operations

Access: Right-click manifest.appdescr_variant > "Open Adaptation Editor"

Operation	Method
Modify properties	Select element, adjust in Properties pane
Add fields	Right-click group > "Add Field" > select fields
Create groups	Right-click > "Add Group"
Add sections	Right-click sections > "Add Section"
Rename elements	Double-click or right-click > rename
Reorder elements	Drag and drop
Move elements	Cut, highlight target, paste
Combine fields	Ctrl+click multiple (max 3) > "Combine"
Split fields	Right-click combined > "Split"
Remove elements	Right-click > remove or Delete key

Note: Removed fields remain available for re-adding. Mandatory fields require confirmation.

Quick Actions Availability Matrix

Quick actions vary by SAPUI5 version. Key milestones:

Action	Min Version	OData
Add Controller to Page	1.71	V2, V4
Add Header Field	1.71	V2, V4
Add Custom Section	1.71	V2, V4
Enable/Disable Clear Button	1.71	V2, V4
Add Custom Table Action	1.96	V2, V4
Add Custom Table Column	1.96	V2, V4
Change Table Columns	1.96	V2, V4
Enable Variant Management	1.96	V2, V4
Add Custom Page Action	1.120	V2, V4
Add Local Annotation File	1.133	V2, V4
Add Subpage (V4)	1.135	V4 only

---

Controller Extensions

Purpose

Enhance existing controller functionality with:

• New methods
• Override methods
• Lifecycle hooks

File Structure

webapp/
├── changes/
│   ├── coding/
│   │   └── MyExtension.js
│   └── MyExtension.controllerExtension.change

Extension Template

sap.ui.define([
    "sap/ui/core/mvc/ControllerExtension"
], function(ControllerExtension) {
    "use strict";

    return ControllerExtension.extend("customer.project.extension.MyExtension", {
        // Override member for lifecycle and base methods
        override: {
            // Lifecycle methods
            onInit: function() {
                // Called after base controller onInit
            },
            onBeforeRendering: function() {
                // Called before view rendering
            },
            onAfterRendering: function() {
                // Called after view rendering
            },
            onExit: function() {
                // Called on controller destruction
            }
        },

        // Custom methods (outside override)
        myCustomMethod: function(oEvent) {
            // Custom business logic
        }
    });
});

Event Handler Binding

For methods in XML fragments, use prefix:

.extension.<controller extension namespace>

Example:

<Button press=".extension.customer.project.extension.MyExtension.myCustomMethod"/>

Provided Methods by Template

Application Type	Provided Methods
List Report	Lifecycle + template overrides
Object Page	Lifecycle + template overrides
Overview Page	Lifecycle + template overrides
Analytical List Page	Lifecycle only

Important Rules

• Keep custom code in changes/coding/ folder
• Do not create additional folders at higher levels
• Namespace extensions with .extension to avoid conflicts

---

Fragments and Extension Points

Adding Fragments to Aggregations

1. Open Adaptation Editor
2. Click Edit mode
3. Select target control (smart filter bar, toolbar, etc.)
4. Choose "Add Fragment" from context menu
5. Configure fragment settings

Quick Actions:

• Add Custom Page Action
• Add Custom Table Action
• Add Custom Table Column
• Add Header Field
• Add Custom Section

Fragment Configuration

Field	Description
Target Aggregation	Container for fragment
Index	Position within aggregation
Fragment	Select existing or create new

Fragment Template

<core:FragmentDefinition
    xmlns:core="sap.ui.core"
    xmlns:uxap="sap.uxap"
    xmlns="sap.m">
    <uxap:ObjectPageSection id="customer.project.customSection" title="Custom Section">
        <uxap:subSections>
            <uxap:ObjectPageSubSection>
                <Text text="Custom content"/>
            </uxap:ObjectPageSubSection>
        </uxap:subSections>
    </uxap:ObjectPageSection>
</core:FragmentDefinition>

Requirements

• Define namespace for all controls used
• Use stable and unique IDs
• IDs should follow pattern: customer.<project>.<elementId>

Adding Fragments to Extension Points

For freestyle SAPUI5 applications with predefined extension points:

1. Expand outline tree to find extension points
2. Right-click parent element
3. Select "Add fragment at extension point"
4. Configure fragment

Generated Files

• Fragment: webapp/changes/fragments/<name>.fragment.xml
• Change: webapp/changes/addXML.change

Cleanup

Delete associated change files when removing fragments to avoid blocking future additions.

---

Preview and Testing

Launch Preview

Fiori: Preview Adaptation Project

Or via Application Info page.

Preview Characteristics

• Runs in sandbox-like environment
• Outside SAP Fiori launchpad context
• Some FLP-dependent features may not work
• Features work correctly after deployment

Testing Adaptations

1. Make changes in Adaptation Editor
2. Preview immediately reflects changes
3. Test functionality in preview
4. Deploy only when satisfied

---

Deployment

On-Premise Deployment

Deploy to ABAP repository using standard deployment:

npm run deploy

S/4HANA Cloud Deployment

Use Adaptation Project Deployment Wizard:

Fiori: Deploy Adaptation Project

Post-Deployment

• Application variant appears in Fiori launchpad
• Independent tile/navigation configuration possible
• Base application updates do not affect deployed variant

---

Upgrade-Safe Rules

Core Principles

SAPUI5 Flexibility uses modification-free extensibility:

• Extension code separated from base application lifecycle
• Base application can upgrade independently
• Extensions remain functional across upgrades

Controller Extension Rules

1. Follow SAPUI5 best practices
2. Access only controls with stable IDs
   • Never rely on control order in aggregations
   • Never rely on parent-child relationships
3. Verify control existence before access
   • Check if control exists
   • Verify control type
4. Avoid private/protected methods
   • Do not call or override private methods
   • Do not use deprecated artifacts
5. No hardcoded property values
   • OData metadata values change during upgrades
   • Do not use value help entity sets in code
6. Handle reuse component changes
   • Implement robust error handling
   • Components may change during upgrades

Fragment Rules

• Use stable IDs with proper namespacing
• Do not reference controls by position
• Handle missing extension points gracefully

---

Checking Compatibility

Base App Upgrade Check

Fiori: Check Base App Upgrades

Verifies if adaptation project is current with base application updates.

Release State Consistency

Fiori: Check Consistency of Release State

Validates that adaptations align with released application state.

---

Documentation Source

GitHub: https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs

Key files:

• extending-an-existing-application-6e25aca.md
• extending-an-sap-fiori-application-for-an-on-premise-system-802f01c.md
• extending-an-sap-fiori-application-for-sap-s-4hana-cloud-public-edition-and-sap-btp-abap-f4881a9.md
• creating-an-adaptation-project-072f566.md
• controller-extensions-ad7b4ae.md
• add-fragments-to-an-aggregation-or-extension-point-6033d56.md
• upgrade-safe-compatibility-rules-53706e2.md
• making-adaptations-2a076dd.md
• previewing-an-adaptation-project-64cc15b.md
• deploying-an-adaptation-project-to-the-abap-repository-febf0d9.md