**TITLE**: SAP Fiori Tools — Documentation Index for Code Generation Agents

**INTRODUCTION**: This optimized reference maps the SAP Fiori Tools User Guide structure and key topic files for AI agents that generate or modify SAP Fiori applications. Use the file paths to locate exact documentation pages for implementation details (generation, preview, development, deployment, extension, and project functions). Each step groups related topics and provides the exact markdown file paths to fetch detailed instructions, examples, and configuration references.

**TAGS**: fiori-tools, sap, sapui5, cap, mta, abap, preview, mockserver, annotations, generator, deployment, extensions

**STEP**: 1 — Top-level Manual and Index
**DESCRIPTION**: Entry point and master index that links to all major sections. Use this to route the agent to the appropriate subtopic file.
**LANGUAGE**: TEXT
**CODE**:
```text
# Master index file
SAP Fiori Tools User Guide (Last Updated: May 2023)

Top-level file list:
- developing-sap-fiori-elements-applications-with-sap-fiori-tools-f09752e.md
- Getting-Started-with-SAP-Fiori-Tools/getting-started-with-sap-fiori-tools-2d8b1cb.md
- Project-Functions/project-functions-0d8fa32.md
- Generating-an-Application/generating-an-application-db44d45.md
- generating-an-application-with-the-project-accelerator-or-joule-using-sap-fiori-tools-ai-6845fed.md
- Previewing-an-Application/previewing-an-application-b962685.md
- Developing-an-Application/developing-an-application-a9c0043.md
- Deploying-an-Application/deploying-an-application-1b7a3be.md
- extending-an-existing-application-6e25aca.md
```

**STEP**: 2 — Getting Started (Installation & Environment)
**DESCRIPTION**: Use this group to set up development environment (Visual Studio Code or SAP Business Application Studio), verify prerequisites, install extensions, and configure authentication. For automation, fetch system requirements, CLI tooling info, and extension installation steps.
**LANGUAGE**: TEXT
**CODE**:
```text
Getting Started main:
- Getting-Started-with-SAP-Fiori-Tools/getting-started-with-sap-fiori-tools-2d8b1cb.md

Installation:
- Getting-Started-with-SAP-Fiori-Tools/installation-e870fcf.md
  - Getting-Started-with-SAP-Fiori-Tools/sap-business-application-studio-b011040.md
  - Getting-Started-with-SAP-Fiori-Tools/visual-studio-code-17efa21.md
    - #loio17efa217f7f34a9eba53d7b209ca4280 (Visual Studio Code section)
    - #loio002ae80eac034e6588af81827ab97332 (System Requirements)
    - #loiobdd272ac4d964fbfa59e956460e0e686 (Cloud Foundry CLI Tools)
    - #loio5701672c35354d5b91759a911eaf1171 (Prerequisites)
    - #loio4ce76a049bab42b0843111af4c7dcb4c (Set up Visual Studio Code)
    - #loiof533419b114f476e98b55622eabaf0f7 (Install Extensions)
    - #loio7b329a74721047808368fca5c28702c3 (Supported Authentication Types)
```

**STEP**: 3 — Project Functions (Project-level operations)
**DESCRIPTION**: Use these pages for inspecting and manipulating project metadata: SAPUI5 version, data editor, project validation, service/annotation file management, UI service generation, and environment checks.
**LANGUAGE**: TEXT
**CODE**:
```text
Project Functions:
- Project-Functions/project-functions-0d8fa32.md
  - Project-Functions/application-information-c3e0989.md
  - Project-Functions/application-sapui5-version-009f43e.md
  - Project-Functions/data-editor-18e43b5.md
  - Project-Functions/deleting-an-application-in-cap-project-709f838.md
  - Project-Functions/environment-check-75390cf.md
  - Project-Functions/information-panel-a9a6c4b.md
  - Project-Functions/managing-sap-system-connections-78a82b6.md
  - Project-Functions/managing-service-and-annotation-files-8182ff3.md
  - Project-Functions/project-validation-6f3c737.md
  - Project-Functions/reuse-library-support-6e99fbb.md
  - Project-Functions/viewing-service-metadata-e369c2c.md
  - Project-Functions/ui-service-generation-1a7aad3.md
```

**STEP**: 4 — Generating an Application (Fiori Elements & Freestyle)
**DESCRIPTION**: Use these topics to programmatically create applications. Follow specific pages for floorplans, supported templates, data sources, floorplan/template properties, and additional configuration like MTA generation and JS code assist.
**LANGUAGE**: TEXT
**CODE**:
```text
Generating an Application:
- Generating-an-Application/generating-an-application-db44d45.md

SAP Fiori Elements:
- Generating-an-Application/SAP-Fiori-Elements/sap-fiori-elements-1488469.md
  - supported-floorplans-2b2b12e.md
  - data-source-9906181.md
  - floorplan-properties-745ae0c.md

Freestyle SAPUI5:
- Generating-an-Application/SAPUI5-Freestyle/freestyle-sapui5-616b1a4.md
  - supported-templates-20d1146.md
    - basic-template-14fdcc0.md
  - data-source-37a0fcf.md
  - template-properties-c2a3c82.md

Additional Configuration:
- Generating-an-Application/Additional-Configuration/additional-configuration-9bea64e.md
  - generating-an-mta-deployment-file-9c41152.md
  - adding-an-sap-fiori-application-to-an-mta-deployment-file-with-5a17ba6.md
    - #loio5a17ba6b62b2462aa0e25ffae7b8d728 (Adding an SAP Fiori Application to MTA)
    - #loiod7525cef6f6c4aa4acf3ec09c5a8eacb (Adding deployment config to existing MTA)
    - #loioe03f08cfec9e44e59da828542cbaf906 (Creating MTA during generation)
  - adding-javascript-code-assist-5c561ed.md

Security Certificate:
- Generating-an-Application/security-certificate-4b318be.md
```

**STEP**: 5 — Generating with AI (Project Accelerator / Joule)
**DESCRIPTION**: Use these resources to generate entire applications using text prompts, images, or both. Includes examples and experimental advanced features and generation logs.
**LANGUAGE**: TEXT
**CODE**:
```text
AI-assisted generation:
- generating-an-application-with-the-project-accelerator-or-joule-using-sap-fiori-tools-ai-6845fed.md
  - generating-an-application-using-text-e7f9f8c.md
    - example-1-manage-contracts-and-customer-information-in-the-system-c1bccf2.md
    - example-2-display-customers-with-related-contracts-a6c978f.md
  - generating-an-application-using-an-image-39193df.md
    - example-manage-travel-list-report-page-480d33c.md
  - generating-an-application-using-text-and-images-5dd43dc.md
    - example-manage-travel-app-list-report-object-page-d17b256.md
  - viewing-generation-logs-4ecc286.md
  - experimental-developing-an-application-using-advanced-features-418d583.md
```

**STEP**: 6 — Previewing an Application (Mock, Live, Local)
**DESCRIPTION**: For local testing and preview flows: convert to virtual endpoints, use live data or mock data, install and configure MockServer, generate mock data with AI, use custom middlewares, run control, app-to-app navigation and external launchpad preview.
**LANGUAGE**: TEXT
**CODE**:
```text
Previewing an Application:
- Previewing-an-Application/previewing-an-application-b962685.md
  - convert-a-project-to-use-virtual-endpoints-630ddec.md
  - previewing-an-sap-fiori-elements-cap-project-1dc179a.md
  - use-live-data-497aee2.md
  - use-mock-data-bda83a4.md
    - installing-mockserver-2538055.md
    - generating-mock-data-with-ai-815c310.md
  - use-local-sources-6d3a210.md
  - use-custom-middlewares-dce5315.md
  - use-run-control-09171c8.md
    - run-control-overview-d7f20f3.md
    - create-a-new-run-configuration-in-visual-studio-code-3b1f37e.md
    - create-a-new-run-configuration-in-sap-business-application-studio-05f2a9e.md
  - app-to-app-navigation-preview-543675f.md
  - preview-an-application-on-external-sap-fiori-launchpad-c789692.md
  - developer-variant-creation-ceb845a.md
  - preview-an-application-with-the-sap-horizon-theme-2a42256.md
```

**STEP**: 7 — Developing an Application (Page Editor, Annotations, Extensions)
**DESCRIPTION**: Guides for project structure, page element configuration, annotation-based and extension-based elements, building blocks, feature guides (search/use), and the annotation language server (completion, snippets, diagnostics, i18n, navigation).
Use these pages when generating or modifying UI annotations and code extensions.
**LANGUAGE**: TEXT
**CODE**:
```text
Developing an Application:
- Developing-an-Application/developing-an-application-a9c0043.md
  - define-application-structure-bae38e6.md
  - configure-page-elements-047507c.md
    - maintaining-annotation-based-elements-a524d8a.md
      - overview-66c5b6f.md
        - annotation-support-796f6a4.md
        - taskbar-notification-c66373a.md
        - edit-in-source-code-7d8e942.md
        - automatic-generation-576f9fe.md
        - internationalization-i18n-eb427f2.md
        - project-cleanup-2640899.md
      - supported-elements-in-page-editor-47f0424.md
        - list-report-page-493f2aa.md
          - filter-fields-0b84286.md
          - table-aaff7b1.md
            - table-actions-da1931b.md
            - table-columns-a80d603.md
              - basic-columns-5f8c75b.md
              - rating-column-b2ba7b4.md
              - progress-column-0039256.md
              - chart-column-b78b302.md
              - contact-column-dc5931d.md
        - multiple-views-c62b82e.md
        - analytical-chart-9c086ec.md
      - form-and-object-page-1eb11a6.md
        - header-a05d7fc.md
          - #loioa05d7fc1bbbf42a0ade9fb50f6b58b56 (Header)
          - #loioe26d602fe170401abb23d963bda7dd92 (Header Properties)
          - #loioed6ebe654f8d4aacb472c691eb11e5e3 (Header Actions)
          - #loio8a127fc36f5640abaab0056e632fe630 (Header Section)
        - sections-a7b4e17.md
          - table-section-fc59378.md
          - form-section-4102b3d.md
            - basic-fields-2953503.md
            - contact-field-b78c767.md
            - connected-fields-5d85951.md
            - actions-07012f9.md
        - footer-1b391bd.md
      - appendix-457f2e9.md (field/annotation reference)
    - maintaining-extension-based-elements-02172d2.md
      - adding-custom-column-... (add column/section/field/action/view/controller extension)
    - maintaining-building-blocks-6d3ad83.md
  - use-feature-guides-0c9e518.md
    - search-for-a-guide-a50bc4a.md
      - currently-available-guides-7bda292.md
    - develop-with-a-guide-ef157a5.md
      - change-the-code-5781b28.md
    - request-a-new-guide-b672261.md
  - working-with-annotations-55bfb91.md
    - maintaining-annotations-with-language-server-6fc93f8.md
      - code-completion-dd4fc3b.md
      - micro-snippets-addf811.md
      - diagnostics-1fd8f54.md
      - internationalization-support-db02ebf.md
      - peek-and-go-to-definition-1ccb911.md
      - navigation-to-references-2bf104d.md
      - documentation-quick-info-8728bd7.md
    - visualizing-annotations-with-service-modeler-58784b5.md
      - overriding-annotations-2f1bb9c.md
```

**STEP**: 8 — Deploying an Application (Cloud Foundry, ABAP, Launchpad)
**DESCRIPTION**: Deployment configuration and steps for Cloud Foundry and ABAP, SAP Fiori Launchpad configuration, exposing to central router, security, and undeploy instructions. Use the deployment generator pages to automate pipeline steps.
**LANGUAGE**: TEXT
**CODE**:
```text
Deploying an Application:
- Deploying-an-Application/deploying-an-application-1b7a3be.md
  - deployment-configuration-1c85927.md
  - generate-deployment-configuration-abap-c06b9cb.md
  - generate-deployment-configuration-cloud-foundry-41e63bd.md
  - sap-fiori-launchpad-configuration-bc3cb89.md
  - deployment-of-application-607014e.md
  - undeploy-an-application-70872c4.md
  - expose-application-to-central-application-router-85ad10d.md
  - security-8a147c6.md
```

**STEP**: 9 — Extending an Existing Application (Adaptation Projects)
**DESCRIPTION**: Guides for creating adaptation projects for on-premise and cloud ABAP environments, making UI adaptations (control variants, fragments, controller extensions), adding app descriptor changes, previewing and deploying adaptation projects, and checking compatibility with base app upgrades.
**LANGUAGE**: TEXT
**CODE**:
```text
Extending an Existing Application:
- extending-an-existing-application-6e25aca.md

On-Premise Adaptation:
- extending-an-sap-fiori-application-for-an-on-premise-system-802f01c.md
  - creating-an-adaptation-project-072f566.md
  - working-with-an-adaptation-project-36e4b64.md
    - making-adaptations-2a076dd.md
      - adapting-the-ui-9c1e7b4.md
        - create-control-variants-views-3dbd97f.md
        - add-fragments-to-an-aggregation-or-extension-point-bdb6561.md
        - controller-extensions-ad7b4ae.md
        - internationalization-a789703.md
        - quick-actions-availability-matrix-5d3d94b.md
      - adding-app-descriptor-changes-02085cb.md
        - replacing-odata-service-6b51df2.md
        - adding-local-annotation-files-392a056.md
        - adding-odata-service-and-new-sapui5-model-71eaa3f.md
        - adding-sapui5-component-usages-manually-12be091.md
    - previewing-an-adaptation-project-8701335.md
    - deploying-an-adaptation-project-to-the-abap-repository-febf0d9.md
    - updating-the-adaptation-project-5808877.md
    - deleting-an-adaptation-project-458f1f3.md

Cloud / S/4HANA Cloud & BTP ABAP:
- extending-an-sap-fiori-application-for-sap-s-4hana-cloud-public-edition-and-sap-btp-abap-f4881a9.md
  - create-the-adaptation-project-d6ab261.md
  - making-adaptations-6d2cfea.md
    - adapt-the-ui-af9747f.md
      - create-control-variants-views-b4026b7.md
      - add-fragments-to-an-aggregation-or-extension-point-6033d56.md
      - controller-extensions-f43630d.md
      - upgrade-safe-compatibility-rules-53706e2.md
      - internationalization-f6d1972.md
      - quick-actions-availability-matrix-59408f9.md
    - adding-app-descriptor-changes-115ad56.md
      - replacing-odata-service-e913fbf.md
      - adding-local-annotation-files-c5d62ca.md
      - adding-odata-service-and-new-sapui5-model-886e83b.md
      - adding-sapui5-component-usages-dd4b6e4.md
      - change-inbound-4ce1920.md
  - previewing-an-adaptation-project-64cc15b.md
  - deploying-or-updating-an-adaptation-project-to-the-abap-repository-32c901d.md
  - check-whether-your-adaptation-project-is-up-to-date-with-base-app-upgrades-c6ef105.md
  - deleting-an-adaptation-project-3db6190.md

Release checks:
- releasing-an-sap-fiori-application-to-be-extensible-in-adaptation-projects-on-sap-s-4hana-1046206.md
  - check-consistency-of-release-state-1f91cd4.md
```

**STEP**: 10 — Quick Reference: Useful Files and IDs (Appendix & Links)
**DESCRIPTION**: Quick lookup for annotation appendix, header/footer/sections references, and field/annotation properties. Use these when generating UI annotations, i18n keys, or validating annotation-based editors.
**LANGUAGE**: TEXT
**CODE**:
```text
Annotation Appendix and references:
- Developing-an-Application/appendix-457f2e9.md
  - contact, criticality, description, dimension, display-as-image, display-type,
    external-id, forecast-value, hidden, hide-by-property, importance,
    improvement-direction, label, maximum-value, measures, minimum-value,
    restrictions, target, text, text-arrangement, tooltip, semantic-object-name,
    semantic-object-property-mapping, value-help

Header/Footer/Sections reference IDs (use when deep-linking):
- Developing-an-Application/header-a05d7fc.md
  - #loioa05d7fc1bbbf42a0ade9fb50f6b58b56
  - #loioe26d602fe170401abb23d963bda7dd92
  - #loioed6ebe654f8d4aacb472c691eb11e5e3
  - #loio8a127fc36f5640abaab0056e632fe630

Visual Studio Code link anchors:
- Getting-Started-with-SAP-Fiori-Tools/visual-studio-code-17efa21.md
  - #loio002ae80eac034e6588af81827ab97332
  - #loio4ce76a049bab42b0843111af4c7dcb4c
```

Use the file paths above as exact document keys to fetch detailed examples, code snippets, command sequences, and configuration templates when generating or modifying SAP Fiori applications.

fiori-tools sap sapui5 cap mta abap preview mockserver annotations generator deployment extensions


**TITLE**: Internationalization (i18n) for Adaptation Projects

**INTRODUCTION**: This document explains how adaptation projects provide internationalization (i18n) support. It shows where i18n files are created, how to add or override key-value pairs, and how to reference those keys from SAPUI5 controls (via the Adaptation Editor or view code). Use this when you need translatable UI text for pages in an adaptation project.

**TAGS**: fiori-tools, i18n, internationalization, SAPUI5, adaptation, i18n.properties

**STEP**: 1 — Project i18n file locations

**DESCRIPTION**: Locate the per-page i18n.properties files created when you create an adaptation project. Use these files to define keys for text shown on that page. The typical workspace folder structure under the adaptation project is:

**LANGUAGE**: text

**CODE**:
```text
<Project name>
└── webapp
    └── i18n
        ├── page1
        │   └── collection
        │       └── i18n.properties
        └── page2
            └── collection
                └── i18n.properties
```

Keep the folder hierarchy and file names exactly as above so the Adaptation Editor can find and present the keys for each page.

**STEP**: 2 — Add or override i18n key-value pairs

**DESCRIPTION**: Edit the page-specific i18n.properties file to add new keys or override existing keys from the source application. Each line is a key=value pair. Use unique keys per page/collection to avoid collisions unless you intentionally want to override the source application's key.

- Save the file in the adaptation project path shown above.
- To override an existing key from the source application, declare the same key with a new value in the adaptation project's i18n.properties file for the relevant page/collection.

**LANGUAGE**: Properties

**CODE**:
```properties
# webapp/i18n/page1/collection/i18n.properties

title=Customer Overview
button.save=Save
button.cancel=Cancel
message.empty=No items found
```

Example of overriding a source key (same key name, new value):
```properties
# override example: adaptation webapp/i18n/page1/collection/i18n.properties
button.save=Save Changes
```

**STEP**: 3 — Reference i18n keys from UI controls (Adaptation Editor or view code)

**DESCRIPTION**: In the Adaptation Editor use the Properties pane to set a control’s text via the i18n key rather than hard-coded text. The editor shows available keys from the page's i18n.properties. Alternatively, in view code (XML/JS) bind the control text to the i18n model using the i18n key.

Examples:

- XML view binding
- JavaScript usage (getText from resource bundle)

**LANGUAGE**: XML

**CODE**:
```xml
<!-- Example XML view usage -->
<core:View xmlns:core="sap.ui.core" xmlns="sap.m">
  <Text text="{i18n>title}" />
  <Button text="{i18n>button.save}" />
</core:View>
```

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// Example JS usage inside a controller
const oBundle = this.getView().getModel("i18n").getResourceBundle();
const sSaveText = oBundle.getText("button.save"); // "Save" or overridden value
this.byId("saveButton").setText(sSaveText);
```

**STEP**: 4 — Run and verify

**DESCRIPTION**: Run the adaptation project as a web application. Verify that UI controls display the text from your i18n key-value pairs. If you overrode a source key, confirm the adapted value appears instead of the original.

Checklist:
- Confirm i18n.properties file saved under the correct page/collection path.
- Confirm keys match the keys used in the Adaptation Editor or view bindings.
- Clear cache / do a hard reload if the old text still appears in the browser.

**LANGUAGE**: text

**CODE**:
```text
Run the app (e.g., via Fiori tools preview or served webapp)
Open the page and check:
- Controls using {i18n>key} show the expected values.
- Overridden keys reflect adaptation project values.
```


**TITLE**: Internationalization (i18n) for Adaptation Projects

**INTRODUCTION**: This guide explains how to provide and override translatable UI text in an adaptation project using i18n key-value pairs. It shows where i18n files live, how to define keys, and how to reference them from SAPUI5 views or controllers. Use these steps to add new translations or override existing source application text.

**TAGS**: fiori-tools, i18n, internationalization, SAPUI5, adaptation-project, i18n.properties, adaptation-editor

STEP: 1 — Locate i18n files in the adaptation project

DESCRIPTION: Find the per-page i18n.properties files that the adaptation project creates. Use these paths to add or edit i18n key-value pairs for specific pages or collections.

LANGUAGE: text

CODE:
```text
<ProjectRoot>/webapp/i18n/<page-name>/<collection>/i18n.properties
```

Example workspace tree:
```text
<Project name>
└─ webapp
   └─ i18n
      ├─ page1
      │  └─ collection
      │     └─ i18n.properties
      └─ page2
         └─ collection
            └─ i18n.properties
```

STEP: 2 — Define key-value pairs in i18n.properties

DESCRIPTION: Add i18n key-value pairs to the appropriate i18n.properties file. Use simple keys (no spaces) and assign the localized string values. Save the file in the adaptation project; the Adaptation Editor and runtime will use these values.

LANGUAGE: properties

CODE:
```properties
# webapp/i18n/page1/collection/i18n.properties
button.save = Save
button.cancel = Cancel
label.username = User Name
message.welcome = Welcome, {0}!
```

STEP: 3 — Reference i18n keys in XML-based SAPUI5 views

DESCRIPTION: Bind UI control text to i18n keys in XML views. Use the view's i18n model (commonly named "i18n") with the syntax {i18n>key}. This ensures the control renders the localized string defined in i18n.properties.

LANGUAGE: xml

CODE:
```xml
<!-- Example XML view snippet -->
<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m">
  <Page id="page">
    <content>
      <Button text="{i18n>button.save}" />
      <Button text="{i18n>button.cancel}" />
      <Label text="{i18n>label.username}" />
    </content>
  </Page>
</mvc:View>
```

STEP: 4 — Reference i18n keys in JavaScript controllers

DESCRIPTION: Retrieve i18n values at runtime in controllers. Use the view's resource model (commonly named "i18n") and call getProperty to access keys. Pass parameters for placeholder replacement.

LANGUAGE: javascript

CODE:
```javascript
// Example controller snippet
onInit: function () {
  var oBundle = this.getView().getModel("i18n").getResourceBundle();
  var sSaveText = oBundle.getText("button.save");
  var sWelcome = oBundle.getText("message.welcome", ["Alice"]); // "Welcome, Alice!"
  this.byId("saveButton").setText(sSaveText);
}
```

STEP: 5 — Override existing i18n keys from the source application

DESCRIPTION: To change text of existing UI controls, override the key-value pair in the adaptation project's i18n.properties using the same key as in the source application. The adaptation project's value takes precedence for the adapted page.

LANGUAGE: properties

CODE:
```properties
# Override example
# Original app had: button.save=Save
button.save = Commit
```

STEP: 6 — Use Adaptation Editor to assign i18n keys to controls

DESCRIPTION: In the Adaptation Editor, prefer assigning an i18n key to a control's property (instead of entering literal text). Set the property to the i18n key so the runtime looks up the value from the i18n model.

LANGUAGE: text

CODE:
```text
Steps in Adaptation Editor:
1. Select a control in the UI editor.
2. In the Properties pane, for the text/title property choose the i18n key reference (e.g., i18n>button.save).
3. Save the adaptation; the control displays the value from webapp/i18n/<page>/<collection>/i18n.properties.
```

STEP: 7 — Run and verify in the web application

DESCRIPTION: Run the adaptation project as a web application. Verify each control displays the value from the corresponding i18n.properties file. If values are not shown, confirm:
- The i18n.properties file is in webapp/i18n/<page>/<collection>/i18n.properties
- The i18n model is registered and named correctly (commonly "i18n")
- Keys in views/controllers match keys in the properties file

LANGUAGE: text

CODE:
```text
Verification checklist:
- File path exists: <ProjectRoot>/webapp/i18n/<page>/<collection>/i18n.properties
- Keys used in views/controllers exactly match properties keys
- Adaptation Editor assigned i18n keys (not literal text)
- Browser cache cleared or app reloaded to pick up changes
```


**TITLE**: Making Adaptations (fiori-tools)

**INTRODUCTION**: This guide provides an action-oriented template for creating and testing UI adaptations for SAP Fiori applications using a local UI5 development workspace. It outlines the minimal project layout and commands to scaffold, run, and validate adaptation artifacts locally. Use these steps to prepare a reproducible workspace for generating adaptation changes (flexibility/variants) and to integrate those artifacts into your CI/CD pipeline.

**TAGS**: fiori-tools, ui5, adaptation, flexibility, manifest, workspace, local-dev

**STEP**: 1 — Create a local UI5 adaptation workspace

**DESCRIPTION**: Create a workspace folder, initialize npm, install the UI5 CLI, and initialize a UI5 project structure. This sets up a predictable environment for producing adaptation artifacts (change files / variant descriptors).

**LANGUAGE**: Shell

**CODE**:
```bash
# create workspace
mkdir fiori-adaptations
cd fiori-adaptations

# initialize npm and install UI5 CLI locally
npm init -y
npm install --save-dev @ui5/cli

# initialize a basic UI5 project structure
mkdir -p webapp
```

**STEP**: 2 — Add a minimal manifest.json for the app under webapp

**DESCRIPTION**: Create or update webapp/manifest.json with the minimal keys required by UI5 and by adaptation tools (sap.app and sap.ui5). Keep this manifest as the primary descriptor that adaptations will reference.

**LANGUAGE**: JSON

**CODE**:
```json
{
  "sap.app": {
    "id": "com.example.adaptation",
    "type": "application",
    "i18n": "i18n/i18n.properties",
    "title": "{{appTitle}}"
  },
  "sap.ui5": {
    "rootView": {
      "viewName": "com.example.adaptation.view.Main",
      "type": "XML",
      "async": true
    },
    "dependencies": {
      "minUI5Version": "1.60.0",
      "libs": {
        "sap.m": {}
      }
    }
  }
}
```

**STEP**: 3 — Add sample webapp index.html and a placeholder view

**DESCRIPTION**: Provide a minimal index.html and a view to let the UI5 server serve the application for testing adaptations in the browser.

**LANGUAGE**: HTML

**CODE**:
```html
<!-- webapp/index.html -->
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Fiori Adaptation Test</title>
    <script id="sap-ui-bootstrap"
            src="https://sapui5.hana.ondemand.com/resources/sap-ui-core.js"
            data-sap-ui-theme="sap_fiori_3"
            data-sap-ui-resourceroots='{"com.example.adaptation": "./"}'
            data-sap-ui-async="true">
    </script>
    <script>
      sap.ui.getCore().attachInit(function () {
        new sap.ui.xmlview({ viewName: "com.example.adaptation.view.Main" }).placeAt("content");
      });
    </script>
  </head>
  <body class="sapUiBody" id="content"></body>
</html>
```

```xml
<!-- webapp/view/Main.view.xml -->
<mvc:View controllerName="com.example.adaptation.controller.Main"
          xmlns:mvc="sap.ui.core.mvc"
          xmlns="sap.m">
  <App>
    <Page title="Adaptation Test">
      <content>
        <VBox>
          <Text text="Adaptation test page" />
        </VBox>
      </content>
    </Page>
  </App>
</mvc:View>
```

**STEP**: 4 — Configure ui5.yaml (UI5 tooling) for local serving

**DESCRIPTION**: Add ui5.yaml so the UI5 CLI knows how to serve the project. This file enables "npx ui5 serve" to host webapp/ at the root path.

**LANGUAGE**: YAML

**CODE**:
```yaml
# ui5.yaml
specVersion: '2.2'
metadata:
  name: fiori-adaptations
type: application
server:
  customMiddleware:
    - name: ui5-middleware-simpleproxy
      afterMiddleware: compression
      mountPath: /api
      configuration:
        baseUri: http://backend.example.local
```

**STEP**: 5 — Start the local UI5 dev server and open the app

**DESCRIPTION**: Serve the application locally and open it in a browser to validate baseline behavior before applying or generating adaptation artifacts.

**LANGUAGE**: Shell

**CODE**:
```bash
# run UI5 server (from project root)
npx ui5 serve --config=ui5.yaml --open index.html
# or explicitly open:
# npx ui5 serve -o /index.html
```

**STEP**: 6 — Create a placeholder folder for adaptation artifacts (flexibility/change files)

**DESCRIPTION**: Use a predictable folder structure for generated adaptation artifacts. Adaptation tools typically generate change files (flexibility) that reference app id and control selectors. Keep these under webapp/changes or a workspace-specific folder to version and review.

**LANGUAGE**: Shell / JSON

**CODE**:
```bash
# create changes folder
mkdir -p webapp/changes
```

```json
// Example change file (webapp/changes/change_someAction.json)
// Follow UI5 flexibility change schema for real change files.
{
  "fileName": "change_someAction.json",
  "changeType": "appdescr_variant",
  "reference": "com.example.adaptation",
  "selector": {
    "id": "com.example.adaptation--someControl",
    "idIsLocal": true
  },
  "content": {
    "variantName": "Example variant"
  }
}
```

**STEP**: 7 — Build artifacts and prepare for deployment

**DESCRIPTION**: Use the UI5 build to produce a deployable bundle. Include any steps your pipeline requires to incorporate generated adaptation artifacts into the final app archive.

**LANGUAGE**: Shell

**CODE**:
```bash
# perform a build to the dist/ folder
npx ui5 build --include-task=generateCachebusterInfo --dest dist
# final bundle is in dist/webapp
```

**STEP**: 8 — Integrate adaptations into CI/CD and runtime

**DESCRIPTION**: Ensure that adaptation artifacts (webapp/changes/*) are included in your build outputs and deployed to the target hosting (SAP BTP, ABAP repository, or static web server). When deploying to SAP systems that use LREP or variant management, follow your platform's deployment steps to register/activate change files.

**LANGUAGE**: Shell (example placeholder)

**CODE**:
```bash
# copy changes into deployment package (example)
cp -r webapp/changes dist/webapp/

# deploy dist/webapp to your environment (placeholder)
# scp -r dist/webapp/* user@host:/srv/www/your-app/
```

**STEP**: 9 — Validate adaptations in target runtime

**DESCRIPTION**: After deployment, open the application in the target environment and validate that adaptations (variants/changes) take effect. Use browser developer tools to inspect loaded change files or platform-specific tools (e.g., UI Adaptation tools in SAP Business Application Studio or Fiori Launchpad personalization tools).

**LANGUAGE**: None

**CODE**:
```text
# Validation checklist (manual steps)
# - Open app in target environment
# - Verify change files are served (network tab)
# - Confirm expected UI differences appear
# - Run automated UI tests if available
```

Making Adaptations (fiori-tools)

fiori-tools ui5 adaptation flexibility manifest workspace local-dev


**TITLE**: Making Adaptations (SAPUI5 / Fiori Tools)

**INTRODUCTION**: Define and implement changes to a generated application variant in an SAPUI5 adaptation project. Use these steps to adapt the UI (views, fragments, controller extensions, compatibility rules, i18n) and to apply app descriptor changes (OData services, local annotations, models, component usages, inbound navigation). File references point to the detailed guides for each task.

**TAGS**: fiori-tools, sapui5, adaptation, app-descriptor, control-variants, fragments, controller-extensions, annotations, i18n, odata, manifest

**STEP**: 1 — Adapt the UI (overview)

**DESCRIPTION**: Overview of UI adaptation activities. Use the linked subguides to implement each adaptation. Start in your adaptation project workspace and locate the UI artifacts to change (views, fragments, controllers, variants, i18n resources). Reference: adapt-the-ui-af9747f.md

**LANGUAGE**: Text

**CODE**:
```text
See detailed guides:
- adapt-the-ui-af9747f.md
- create-control-variants-views-b4026b7.md
- add-fragments-to-an-aggregation-or-extension-point-6033d56.md
- controller-extensions-f43630d.md
- upgrade-safe-compatibility-rules-53706e2.md
- internationalization-f6d1972.md
```

**STEP**: 2 — Create Control Variants (Views)

**DESCRIPTION**: Implement view-level control variants to provide alternative UI layouts/behaviors. Create variant view definitions and register them where Variant Management is used. Follow the linked guide to place variant fragments or variant XML views in your adaptation project and reference them from the variant configuration. Reference: create-control-variants-views-b4026b7.md

**LANGUAGE**: Text

**CODE**:
```text
Actions:
- Create variant views or fragments in your webapp/adaptations or changes folder.
- Ensure variant registration is present where VariantManagement is used.
- Test switching variants at runtime.
```

**STEP**: 3 — Add Fragments to an Aggregation or Extension Point

**DESCRIPTION**: Add or replace UI fragments at aggregation points or extension points in generated views. Place fragment XML files in your adaptation project and reference them via the extension point or aggregation ID in the view or manifest. Reference: add-fragments-to-an-aggregation-or-extension-point-6033d56.md

**LANGUAGE**: Text

**CODE**:
```text
Actions:
- Create fragment XML files in webapp/fragments/ or webapp/adaptations/fragments/.
- Update the parent view or use an extensionPoint definition to insert the fragment.
- Verify ID and aggregation path match the target control.
```

**STEP**: 4 — Controller Extensions

**DESCRIPTION**: Add or override controller logic by creating controller extension files and wiring them into the adaptation. Use extension hooks exposed by the base app or UI5 component to add custom behavior without modifying the generated app core. Reference: controller-extensions-f43630d.md

**LANGUAGE**: Text

**CODE**:
```text
Actions:
- Create controller extension JS files in webapp/controllerExtensions/ or a similar folder.
- Register/declare the extension according to the base app's extension mechanism.
- Use lifecycle hooks and call base methods where needed to remain upgrade-safe.
```

**STEP**: 5 — Upgrade Safe Compatibility Rules

**DESCRIPTION**: Add compatibility rules to ensure customizations remain safe across upgrades. Implement rules that constrain or adapt changes to avoid breaking core app updates. Reference: upgrade-safe-compatibility-rules-53706e2.md

**LANGUAGE**: Text

**CODE**:
```text
Actions:
- Add compatibility metadata and rules in your adaptation metadata.
- Validate rules during build/test to ensure they do not conflict with framework upgrades.
```

**STEP**: 6 — Internationalization (i18n)

**DESCRIPTION**: Add or override i18n resources for translations and locale-specific strings. Place resource bundles in the adaptation project and reference them so the app loads adapted text. Reference: internationalization-f6d1972.md

**LANGUAGE**: Text

**CODE**:
```text
Actions:
- Create i18n.properties and locale variants under webapp/i18n/ or webapp/adaptations/i18n/.
- Register new bundles in the manifest or ensure the UI5 loader resolves them at runtime.
```

**STEP**: 7 — Adding App Descriptor Changes (overview)

**DESCRIPTION**: Make manifest.json (app descriptor) changes in the adaptation project to add/replace OData services, local annotations, new models, component usages, and inbound navigation. Work in webapp/manifest.json or use an adaptation manifest overlay. Reference: adding-app-descriptor-changes-115ad56.md

**LANGUAGE**: Text

**CODE**:
```text
Primary files:
- webapp/manifest.json
- webapp/localService/annotations/   (for local annotation files)
- webapp/adaptations/manifest-overrides.json   (if using overlay)
```

**STEP**: 8 — Replacing OData Service

**DESCRIPTION**: Replace the OData service declared in the manifest by updating dataSources and model bindings. Ensure URI, type, and settings match the target service and that the model points to the updated data source.

**LANGUAGE**: JSON

**CODE**:
```json
{
  "sap.app": {
    "id": "your.app.id",
    "dataSources": {
      "mainService": {
        "uri": "/sap/opu/odata/sap/MY_SERVICE_SRV/",
        "type": "OData",
        "settings": { "odataVersion": "2.0" }
      }
    }
  },
  "sap.ui5": {
    "models": {
      "": {
        "dataSource": "mainService"
      }
    }
  }
}
```

**STEP**: 9 — Adding Local Annotation Files

**DESCRIPTION**: Add local OData annotation XML files to the adaptation project and register them as dataSources in the manifest. Reference these annotation files from the OData dataSource settings.

**LANGUAGE**: Text

**CODE**:
```text
Actions:
- Place annotation XML files under webapp/localService/annotations/
- In manifest.json add entries under "sap.app" > "dataSources" with "type": "ODataAnnotation" and "settings": { "localUri": "localService/annotations/<file>.xml" }
- Reference the annotation dataSource from the model's "settings": { "annotations": ["<annotationDatasourceKey>"] }
```

**STEP**: 10 — Adding OData Service and New SAPUI5 Model

**DESCRIPTION**: Add a new OData service and register a new model in sap.ui5/models. Declare the service in sap.app/dataSources and declare the model in sap.ui5/models with the dataSource key.

**LANGUAGE**: JSON

**CODE**:
```json
{
  "sap.app": {
    "dataSources": {
      "NewService": {
        "uri": "/sap/opu/odata/sap/NEW_SERVICE_SRV/",
        "type": "OData",
        "settings": { "odataVersion": "2.0" }
      }
    }
  },
  "sap.ui5": {
    "models": {
      "NewModel": {
        "dataSource": "NewService",
        "preload": true
      }
    }
  }
}
```

**STEP**: 11 — Adding SAPUI5 Component Usages

**DESCRIPTION**: Add external SAPUI5 components or libraries via the componentUsages section in the manifest so the app can reference and instantiate those components.

**LANGUAGE**: JSON

**CODE**:
```json
{
  "sap.ui5": {
    "componentUsages": {
      "MyExternalComponent": {
        "name": "my.external.Component",
        "settings": {}
      }
    }
  }
}
```

**STEP**: 12 — Change Inbound (Cross-Application Navigation)

**DESCRIPTION**: Add or modify inbound intents (crossNavigation/inbounds) to change how the app is launched from other apps. Update the "sap.app" > "crossNavigation" > "inbounds" section in the manifest.

**LANGUAGE**: JSON

**CODE**:
```json
{
  "sap.app": {
    "crossNavigation": {
      "inbounds": {
        "MyApp-display": {
          "semanticObject": "MyApp",
          "action": "display",
          "title": "Open My App",
          "signature": {
            "parameters": {}
          }
        }
      }
    }
  }
}
```

**STEP**: 13 — Use the Detailed Topic for Adaptation Extensions (optional)

**DESCRIPTION**: For Fiori elements-based apps, consider adaptation extensions to extend delivered apps. Read the official UI5 topic for patterns and examples.

**LANGUAGE**: Text

**CODE**:
```text
Reference:
- Extending Delivered Apps Using Adaptation Extensions:
  https://ui5.sap.com/#/topic/52fc48b479314d0688be24f699778c47
```

fiori-tools sapui5 adaptation app-descriptor control-variants fragments controller-extensions annotations i18n odata manifest


**TITLE**: Previewing an Adaptation Project

**INTRODUCTION**: Quick, code-focused instructions to open and use the runtime preview for a Fiori adaptation project (RTA / adaptation project). Use this to validate UI adaptations, navigate the app, load test data, and verify behavior in a separate browser tab.

**TAGS**: fiori-tools, adaptation-project, preview, manifest.appdescr_variant, webapp, popup, authentication

**STEP**: 1 — Locate the manifest file in the workspace

**DESCRIPTION**: In your project workspace, find the adaptation project's descriptor file under the webapp folder. The file to open is manifest.appdescr_variant.

**LANGUAGE**: Instructions

**CODE**:
```text
workspace/
└─ webapp/
   └─ manifest.appdescr_variant
```

**STEP**: 2 — Open the preview

**DESCRIPTION**: Right-click the file manifest.appdescr_variant and select "Open Preview" from the context menu. The preview launches in a new browser tab (separate from your IDE).

**LANGUAGE**: Instructions

**CODE**:
```text
Context menu -> Open Preview
```

**STEP**: 3 — Allow popups (required)

**DESCRIPTION**: The preview opens in a new tab; your browser will prompt to allow popups. Click "Allow" for the IDE site (or enable popups temporarily). If popups are blocked, enable popups for the IDE URL in your browser settings and re-trigger "Open Preview".

**LANGUAGE**: Instructions

**CODE**:
```text
If blocked:
- Chrome: Settings -> Privacy and security -> Site Settings -> Pop-ups and redirects -> Allow [IDE_URL]
- Firefox: Options -> Privacy & Security -> Permissions -> Block pop-up windows (uncheck or add Exception)
```

**STEP**: 4 — Authenticate if prompted (optional)

**DESCRIPTION**: Depending on your authentication model and the target system, the preview might require credentials. When prompted, enter the credentials for the backend/system the adaptation targets. This is required to load real data and test interactions.

**LANGUAGE**: Instructions

**CODE**:
```text
Possible prompts:
- Basic auth dialog
- SAML/OAuth redirect to identity provider
- Single Sign-On (SSO) flow
Provide valid credentials or complete SSO to continue.
```

**STEP**: 5 — Use the preview to validate changes

**DESCRIPTION**: After the preview opens in a new tab and authentication (if applicable) completes, navigate the app, load test data, and exercise scenarios to verify adaptations. Use this tab to confirm UI changes, event behavior, and data bindings.

**LANGUAGE**: Instructions

**CODE**:
```text
Validate:
- Navigation between views
- Data loading and bindings
- Modified controls and annotations
- Custom actions or scripts
Close the preview tab when finished.
```

**STEP**: 6 — Troubleshooting common issues

**DESCRIPTION**: Quick checks if the preview does not behave as expected: ensure the correct manifest.appdescr_variant is selected, confirm popup permission, verify connectivity to backend system, and check the browser console for errors.

**LANGUAGE**: Instructions

**CODE**:
```text
Troubleshoot:
- Confirm file: webapp/manifest.appdescr_variant
- Ensure popups allowed for IDE URL
- Check network connectivity and credentials
- Open browser DevTools Console for runtime errors
- Restart preview after making changes in the adaptation project
```

Previewing an Adaptation Project

fiori-tools adaptation-project preview manifest.appdescr_variant webapp popup authentication


**TITLE**: Previewing an Adaptation Project (SAP Fiori Tools)

**INTRODUCTION**: Quick, action-oriented guide to open and preview an adaptation project created with SAP Fiori Tools. Use this to launch the project in a browser tab for interactive testing of UI adaptations and newly added functionality.

**TAGS**: fiori-tools, preview, adaptation, manifest, webapp, sap, preview-application

**STEP**: 1 — Open preview command from project explorer

**DESCRIPTION**: Locate the project entry you want to preview in your workspace. Right-click one of the valid targets (project main folder, the webapp folder, or the manifest variant file) and choose the "Preview Application" context menu command.

**LANGUAGE**: text

**CODE**:
```text
Valid right-click targets:
- <project-root>            (project main folder)
- <project-root>/webapp     (webapp folder)
- <project-root>/webapp/manifest.appdescr_variant

Context menu action:
- Right-click -> Preview Application
```

**STEP**: 2 — Start the preview and test in browser

**DESCRIPTION**: After invoking "Preview Application", click the Start button in the preview dialog. The adaptation project will launch in a separate browser tab where you can navigate the app, load data, and interactively test any adaptations or new functionality.

**LANGUAGE**: text

**CODE**:
```text
Action:
- Click "Start" in the preview dialog

Outcome:
- A new browser tab opens with the adapted application
- Use the app to navigate, load data, and verify behavior
```

fiori-tools preview adaptation manifest webapp sap preview-application


**TITLE**: Quick Actions Availability Matrix (Machine-Readable & Utility)

**INTRODUCTION**: This document provides a machine-readable availability matrix and utility code to determine whether a given quick action is supported for a specific combination of OData version, SAPUI5 version, and page type in adaptation projects based on SAP Fiori elements. Use the JSON matrix programmatically or the TypeScript helper to validate availability before attempting to apply quick actions or manifest changes.

**TAGS**: fiori-tools, sapui5, odata, adaptation, manifest.json, quick-actions, compatibility

**STEP**: 1

**DESCRIPTION**: Programmatic availability matrix (JSON). Each entry lists the quick action, supported OData versions, page types, and the minimum SAPUI5 version required for that action to be available for each OData version. Use this JSON as authoritative input for code that decides whether to present or enable a quick action in automation/adaptation tools.

**LANGUAGE**: JSON

**CODE**:
```json
{
  "matrixVersion": "1.0",
  "sapui5Columns": ["1.71","1.84","1.96","1.108","1.120","1.130","1.133","1.134",">=1.135"],
  "actions": [
    {
      "id": "addControllerToPage",
      "title": "Add Controller to Page",
      "pageTypes": ["List Report/Analytical List Page","Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.71" },
        "ODataV4": { "minSapUi5Version": "1.71" }
      }
    },
    {
      "id": "addHeaderField",
      "title": "Add Header Field",
      "pageTypes": ["Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.71" },
        "ODataV4": { "minSapUi5Version": "1.71" }
      }
    },
    {
      "id": "addCustomSection",
      "title": "Add Custom Section",
      "pageTypes": ["Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.71" },
        "ODataV4": { "minSapUi5Version": "1.71" }
      }
    },
    {
      "id": "addCustomPageAction",
      "title": "Add Custom Page Action",
      "pageTypes": ["List Report/Analytical List Page","Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.130" },
        "ODataV4": { "minSapUi5Version": "1.130" }
      }
    },
    {
      "id": "addCustomTableAction",
      "title": "Add Custom Table Action",
      "pageTypes": ["List Report/Analytical List Page","Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.96" },
        "ODataV4": { "minSapUi5Version": "1.96" }
      }
    },
    {
      "id": "addCustomTableColumn",
      "title": "Add Custom Table Column",
      "pageTypes": ["List Report/Analytical List Page","Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.96" },
        "ODataV4": { "minSapUi5Version": "1.96" }
      }
    },
    {
      "id": "addLocalAnnotationFile",
      "title": "Add Local Annotation File",
      "pageTypes": ["List Report/Analytical List Page","Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.133" },
        "ODataV4": { "minSapUi5Version": "1.133" }
      }
    },
    {
      "id": "addSubpage",
      "title": "Add Subpage",
      "pageTypes": ["List Report/Analytical List Page","Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.96" },
        "ODataV4": { "minSapUi5Version": "1.135" }
      }
    },
    {
      "id": "changeTableActions",
      "title": "Change Table Actions",
      "pageTypes": ["List Report/Analytical List Page","Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.108" },
        "ODataV4": { "minSapUi5Version": "1.130" }
      }
    },
    {
      "id": "changeTableColumns",
      "title": "Change Table Columns",
      "pageTypes": ["List Report/Analytical List Page","Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.96" },
        "ODataV4": { "minSapUi5Version": "1.96" }
      }
    },
    {
      "id": "enableDisableClearButton",
      "title": "Enable/Disable Clear Button",
      "pageTypes": ["List Report/Analytical List Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.71" },
        "ODataV4": { "minSapUi5Version": "1.71" }
      }
    },
    {
      "id": "enableEmptyRowModeForTables",
      "title": "Enable Empty Row Mode for Tables",
      "pageTypes": ["Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.130" },
        "ODataV4": { "minSapUi5Version": "1.133" }
      }
    },
    {
      "id": "enableSemanticDateRange",
      "title": "Enable Semantic Date Range",
      "pageTypes": ["List Report/Analytical List Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.96" },
        "ODataV4": { "minSapUi5Version": "1.130" }
      }
    },
    {
      "id": "enableTableFilteringForPageVariants",
      "title": "Enable Table Filtering for Page Variants",
      "pageTypes": ["List Report/Analytical List Page","Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.96" },
        "ODataV4": { "minSapUi5Version": "1.133" }
      }
    },
    {
      "id": "enableVariantManagementInTables",
      "title": "Enable Variant Management in Tables",
      "pageTypes": ["Object Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.96" }
      }
    },
    {
      "id": "enableVariantManagementInTablesAndCharts",
      "title": "Enable Variant Management in Tables and Charts",
      "pageTypes": ["List Report/Analytical List Page"],
      "support": {
        "ODataV2": { "minSapUi5Version": "1.96" },
        "ODataV4": { "minSapUi5Version": "1.133" }
      }
    }
  ],
  "notes": [
    "Actions marked with an asterisk (*) can change the app manifest (manifest.json).",
    "Actions that result in manifest.json changes are not available for adaptation projects built on OData V2 applications that use SAPUI5 < 1.134 and have an outdated array page structure in manifest.json.",
    "See: Extending the Delivered Apps Manifest Using an Adaptation Project — https://ui5.sap.com/#/topic/a2b24a69baef4b91af2293ccc6b5871f"
  ]
}
```

**STEP**: 2

**DESCRIPTION**: TypeScript utility to check quick-action availability using the JSON matrix above. Use this to gate UI presentation or automation steps. It compares SAPUI5 versions (simple semantic comparison) and validates page type and OData version availability.

**LANGUAGE**: TypeScript

**CODE**:
```typescript
// Usage:
// 1) Load the JSON matrix (embed or import).
// 2) Call isActionAvailable(actionId, "ODataV2"|"ODataV4", "List Report/Analytical List Page", "1.130")

type ODataType = "ODataV2" | "ODataV4";
type Matrix = {
  matrixVersion: string;
  actions: Array<{
    id: string;
    title: string;
    pageTypes: string[];
    support: Record<ODataType | string, { minSapUi5Version: string }>;
  }>;
  notes: string[];
};

function parseVersion(v: string): number[] {
  // Normalize formats like ">=1.135" to "1.135"
  const clean = v.replace(/^>=/, "");
  return clean.split(".").map((n) => parseInt(n, 10) || 0);
}

function compareVersion(a: string, b: string): number {
  // returns -1 if a < b, 0 if equal, 1 if a > b
  const A = parseVersion(a);
  const B = parseVersion(b);
  for (let i = 0; i < Math.max(A.length, B.length); i++) {
    const ai = A[i] || 0;
    const bi = B[i] || 0;
    if (ai < bi) return -1;
    if (ai > bi) return 1;
  }
  return 0;
}

/**
 * Determines if an action is available for the provided combination.
 * - matrix: the parsed JSON matrix
 * - actionId: id of the action (see matrix.actions[].id)
 * - odata: "ODataV2" | "ODataV4"
 * - pageType: page type string (must match one of action.pageTypes)
 * - sapUi5Version: actual SAPUI5 version string, e.g. "1.130"
 */
function isActionAvailable(
  matrix: Matrix,
  actionId: string,
  odata: ODataType,
  pageType: string,
  sapUi5Version: string
): boolean {
  const action = matrix.actions.find((a) => a.id === actionId);
  if (!action) return false;
  if (!action.pageTypes.includes(pageType)) return false;
  const support = action.support[odata];
  if (!support) return false;
  const minVersion = support.minSapUi5Version;
  // If matrix contains >= prefix originally, minVersion was normalized to numeric string in JSON.
  return compareVersion(sapUi5Version, minVersion) >= 0;
}

// Example:
// const matrix: Matrix = /* load JSON from STEP 1 */;
// console.log(isActionAvailable(matrix, "addCustomPageAction", "ODataV2", "Object Page", "1.120")); // false
// console.log(isActionAvailable(matrix, "addCustomPageAction", "ODataV2", "Object Page", "1.130")); // true
```

**STEP**: 3

**DESCRIPTION**: Manifest-related prerequisite check and guidance. Actions that modify manifest.json may be blocked by outdated manifest structures. Use this step to flag such scenarios before performing actions that mutate the manifest.

**LANGUAGE**: JSON (example file path and check hint)

**CODE**:
```json
{
  "filePath": "manifest.json",
  "check": "If your project is OData V2 and uses SAPUI5 < 1.134, verify the array page structure in manifest.json. If it is the 'outdated array page structure', block actions that modify the manifest (see matrix notes).",
  "reference": "https://ui5.sap.com/#/topic/a2b24a69baef4b91af2293ccc6b5871f"
}
```

**STEP**: 4

**DESCRIPTION**: Practical integration notes for code generators or RAG agents:
- Load the JSON matrix at startup and cache it.
- When presenting quick actions in a UI or automation pipeline, call isActionAvailable() for each candidate action.
- For actions that result in manifest.json changes, perform the manifest checks described in STEP 3 and refuse/notify if constraints apply.
- Keep the JSON matrix synchronized with official documentation when SAPUI5 or Fiori elements support changes.

**LANGUAGE**: None

**CODE**:
```text
(Integration checklist)
- Load matrix JSON at tool initialization.
- Validate project OData version and SAPUI5 version.
- For each quick action candidate:
  - Check pageType match.
  - Call isActionAvailable(matrix, actionId, odata, pageType, sapUi5Version).
  - If available and action modifies manifest.json, ensure manifest.json structure is compatible (see STEP 3).
- Use the reference link for resolving manifest structure questions:
  https://ui5.sap.com/#/topic/a2b24a69baef4b91af2293ccc6b5871f
```

fiori-tools sapui5 odata adaptation manifest.json quick-actions compatibility


**TITLE**: Quick Actions Availability Matrix (SAP Fiori tools) — Machine-readable reference

**INTRODUCTION**: This document provides a concise, machine-friendly reference of which quick actions are supported in adaptation projects of SAP Fiori elements apps, by OData version, page type, and SAPUI5 version. Use these JSON objects to programmatically validate or enable quick-action tooling and code generation flows.

**TAGS**: sapui5, fiori-tools, quick-actions, adaptation-projects, odata-v2, odata-v4, manifest.json

STEP: Add Controller to Page
DESCRIPTION: Supported for both OData V2 and V4 on List Report/Analytical List Page and Object Page across all listed SAPUI5 versions.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Add Controller to Page",
  "pageTypes": ["List Report/Analytical List Page", "Object Page"],
  "manifestChange": false,
  "support": {
    "ODataV2": {
      "1.71": true,
      "1.84": true,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": true,
      "1.84": true,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Add Header Field
DESCRIPTION: Supported on Object Page for both OData V2 and V4 across all listed SAPUI5 versions.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Add Header Field",
  "pageTypes": ["Object Page"],
  "manifestChange": false,
  "support": {
    "ODataV2": {
      "1.71": true,
      "1.84": true,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": true,
      "1.84": true,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Add Custom Section
DESCRIPTION: Supported on Object Page for both OData V2 and V4 across all listed SAPUI5 versions.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Add Custom Section",
  "pageTypes": ["Object Page"],
  "manifestChange": false,
  "support": {
    "ODataV2": {
      "1.71": true,
      "1.84": true,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": true,
      "1.84": true,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Add Custom Page Action
DESCRIPTION: Supported for List Report/Analytical List Page and Object Page. Availability starts at SAPUI5 1.130 and above for both OData V2 and V4.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Add Custom Page Action",
  "pageTypes": ["List Report/Analytical List Page", "Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Add Custom Table Action
DESCRIPTION: Supported for List Report/Analytical List Page and Object Page. Availability starts at SAPUI5 1.96 and above for both OData V2 and V4.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Add Custom Table Action",
  "pageTypes": ["List Report/Analytical List Page", "Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Add Custom Table Column
DESCRIPTION: Supported for List Report/Analytical List Page and Object Page. Availability starts at SAPUI5 1.96 and above for both OData V2 and V4.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Add Custom Table Column",
  "pageTypes": ["List Report/Analytical List Page", "Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Add Local Annotation File*
DESCRIPTION: Supported for List Report/Analytical List Page and Object Page. Availability starts at SAPUI5 1.133 and above for both OData V2 and V4. Note: Marked with * means this action results in manifest changes (see prerequisites).
LANGUAGE: JSON
CODE:
```json
{
  "action": "Add Local Annotation File",
  "pageTypes": ["List Report/Analytical List Page", "Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": false,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": false,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Add Subpage*
DESCRIPTION: Supported for List Report/Analytical List Page and Object Page. OData V2 support starts at SAPUI5 1.96 and above. OData V4 support is available only for SAPUI5 >=1.135. This action results in manifest changes.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Add Subpage",
  "pageTypes": ["List Report/Analytical List Page", "Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": false,
      "1.133": false,
      "1.134": false,
      ">=1.135": true
    }
  }
}
```

STEP: Change Table Actions
DESCRIPTION: Supported for List Report/Analytical List Page and Object Page. OData V2 support starts at SAPUI5 1.108 and above. OData V4 support starts at SAPUI5 1.130 and above.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Change Table Actions",
  "pageTypes": ["List Report/Analytical List Page", "Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Change Table Columns
DESCRIPTION: Supported for List Report/Analytical List Page and Object Page. Availability starts at SAPUI5 1.96 and above for both OData V2 and V4.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Change Table Columns",
  "pageTypes": ["List Report/Analytical List Page", "Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Enable/Disable Clear Button
DESCRIPTION: Supported for List Report/Analytical List Page for both OData V2 and V4 across all listed SAPUI5 versions.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Enable/Disable Clear Button",
  "pageTypes": ["List Report/Analytical List Page"],
  "manifestChange": false,
  "support": {
    "ODataV2": {
      "1.71": true,
      "1.84": true,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": true,
      "1.84": true,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Enable Empty Row Mode for Tables*
DESCRIPTION: Supported on Object Page. OData V2 support starts at SAPUI5 1.130 and above. OData V4 support starts at SAPUI5 1.133 and above. This action results in manifest changes.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Enable Empty Row Mode for Tables",
  "pageTypes": ["Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": false,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Enable Semantic Date Range*
DESCRIPTION: Supported on List Report/Analytical List Page. OData V2 support starts at SAPUI5 1.96 and above. OData V4 support starts at SAPUI5 1.130 and above. This action results in manifest changes.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Enable Semantic Date Range",
  "pageTypes": ["List Report/Analytical List Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Enable Table Filtering for Page Variants*
DESCRIPTION: Supported for List Report/Analytical List Page and Object Page. OData V2 support starts at SAPUI5 1.96 and above. OData V4 support starts at SAPUI5 1.133 and above. This action results in manifest changes.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Enable Table Filtering for Page Variants",
  "pageTypes": ["List Report/Analytical List Page", "Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": false,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Enable Variant Management in Tables*
DESCRIPTION: Supported on Object Page. Availability starts at SAPUI5 1.96 and above for OData V2. (No V4 support listed in the matrix.) This action results in manifest changes.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Enable Variant Management in Tables",
  "pageTypes": ["Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {}
  }
}
```

STEP: Enable Variant Management in Tables and Charts*
DESCRIPTION: Supported on List Report/Analytical List Page (OData V2) starting at SAPUI5 1.96 and above. For OData V4, support starts at SAPUI5 1.133 and above. This action results in manifest changes.
LANGUAGE: JSON
CODE:
```json
{
  "action": "Enable Variant Management in Tables and Charts",
  "pageTypes": ["List Report/Analytical List Page", "Object Page"],
  "manifestChange": true,
  "support": {
    "ODataV2": {
      "1.71": false,
      "1.84": false,
      "1.96": true,
      "1.108": true,
      "1.120": true,
      "1.130": true,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    },
    "ODataV4": {
      "1.71": false,
      "1.84": false,
      "1.96": false,
      "1.108": false,
      "1.120": false,
      "1.130": false,
      "1.133": true,
      "1.134": true,
      ">=1.135": true
    }
  }
}
```

STEP: Prerequisites and manifest.json note
DESCRIPTION: Actions marked with * modify the app manifest. They are not available for adaptation projects that are:
- based on OData V2 applications,
- using SAPUI5 < 1.134,
- and that have an outdated array page structure in the manifest.json file.
Follow the linked guidance to update the manifest before applying these actions.
LANGUAGE: JSON
CODE:
```json
{
  "note": "Prerequisites for actions resulting in manifest changes",
  "file": "manifest.json",
  "condition": {
    "notAvailableIf": [
      "OData V2",
      "SAPUI5 < 1.134",
      "outdated array page structure in manifest.json"
    ]
  },
  "reference": "See the Prerequisites section in Extending the Delivered Apps Manifest Using an Adaptation Project: https://ui5.sap.com/#/topic/a2b24a69baef4b91af2293ccc6b5871f"
}
```


**TITLE**: Releasing an SAP Fiori Application to Be Extensible in Adaptation Projects on SAP S/4HANA Cloud and SAP BTP, ABAP Environment

**INTRODUCTION**: Step-by-step actions to prepare and release an SAP Fiori application so it is safely extensible in adaptation projects (SAP S/4HANA Cloud and SAP BTP, ABAP environment). Covers required manifest.json changes, OData/BSP release states (C1/C0), authorization object release settings, and creating an API snapshot. Follow these steps to ensure ATC checks and adaptation tooling recognize your release and prevent breaking changes for customers.

**TAGS**: fiori-tools, sapui5, sap-s4hana-cloud, sap-btp, abap, adaptation, manifest.json, odata, bsp, wapa, atc, api-snapshot

STEP: 1 — Prerequisites and manifest.json requirements

DESCRIPTION: Verify development best practices and enable UI adaptation. Before releasing, increment the application version in manifest.json and ensure sap.app/id contains at least two segments. These manifest settings are required for consumers to receive ATC notifications when the base app is updated. The manifest key sap.fiori/cloudDevAdaptationStatus can be set to "released" only after the OData service C1 contract is Released.

LANGUAGE: JSON

CODE:
```json
{
  "sap.app": {
    "id": "com.example.myapp",          /* must have at least two segments */
    "applicationVersion": {
      "version": "1.2.0"               /* increment this before releasing */
    }
  },
  "sap.fiori": {
    "cloudDevAdaptationStatus": "released" /* allowed values: (null), "released", "deprecated", "obsolete" */
  }
}
```

STEP: 2 — Release the OData service with a C1 contract

DESCRIPTION: In the backend/API management, set the OData service API Release State to C1 = Released. C1 contract: forbids incompatible changes to the service structure but allows annotation changes. This step is required (prerequisite) before setting sap.fiori/cloudDevAdaptationStatus to "released" in manifest.json. ATC checks will enforce this contract.

LANGUAGE: Text

CODE:
```
Action: Set OData service API Release State = C1 (Use System-Internally) -> Released
Notes:
- C1 prevents incompatible structural changes to the OData service.
- Annotations can still be changed.
- Must be set to Released before manifest.json cloudDevAdaptationStatus="released".
```

STEP: 3 — Release the BSP (WAPA object) with a C0 contract and deploy

DESCRIPTION: Release the BSP/WAPA object with a C0 contract. Update the manifest.json as shown (sap.fiori/cloudDevAdaptationStatus="released"). Deployment of the application (BSP/WAPA) will only succeed if the OData service C1 contract is already Released. Ensure sap.app/id has at least two segments (see STEP 1).

LANGUAGE: Text

CODE:
```
Action: Set BSP (WAPA object) API Release State = C0 (Extend) -> Released
Prerequisite: OData service must be C1 = Released
Manifest file to include (manifest.json) as shown in STEP 1
Deployment: Allowed only if above prerequisite is met
```

STEP: 4 — Release authorization objects and restriction types used by the OData service

DESCRIPTION: In the authorization management area, set the relevant authorization objects and restriction types to C1 = Released and select the "Use in Cloud Development" checkbox. This is optional for enabling app variants, but if not released, app variant authorizations will be identical to the original app and original business catalogs must be assigned to the user's role.

LANGUAGE: Text

CODE:
```
Action: For each authorization object / restriction type used by the OData service:
- Set API Release State = C1 -> Released
- Check "Use in Cloud Development"
Note:
- Not strictly required for creating app variants.
- If not released, variant authorizations mirror the original app.
- Original app and original business catalogs must be assigned to user role.
```

STEP: 5 — Create an API snapshot before shipment

DESCRIPTION: Create an API snapshot that includes all released APIs right before shipping the application. Use the Manage API Snapshots application in SAP S/4HANA Cloud. This snapshot ensures a consistent reference for consumers and is used by ATC checks to verify adaptation project compatibility.

LANGUAGE: Text

CODE:
```
Action: Open "Manage API Snapshots" application
- Create a new snapshot including all APIs with Release State = Released (C0/C1 as applicable)
- Save the snapshot and include it in your release documentation
Note: Snapshots are used to check consistency of release state and to support ATC checks.
```

STEP: 6 — Verify ATC checks and consumer notification behavior

DESCRIPTION: Ensure ATC checks are configured and run to enforce release contracts. Confirm consumers receive ATC notifications when base app version is incremented. If you incremented sap.app/applicationVersion/version in manifest.json, ATC and adaptation tools will detect base app updates and notify adaptation projects.

LANGUAGE: Text

CODE:
```
Checks to perform:
- Run ATC or relevant release consistency checks to validate C1/C0 states
- Confirm adaptation projects receive notifications after manifest.json applicationVersion/version increment
- Use "Check Consistency of Release State" and "Check Whether Your Adaptation Project Is Up-To-Date with Base App Upgrades" procedures
```

fiori-tools sapui5 sap-s4hana-cloud sap-btp abap adaptation manifest.json odata bsp wapa atc api-snapshot


**TITLE**: Replacing OData Service (fiori-tools)

**INTRODUCTION**: Step-by-step instructions for replacing an OData service referenced by a Fiori app project (via fiori-tools). Use this to change the service URI, optional caching (`maxAge`), and optional annotation datasource while preserving manifest configuration.

**TAGS**: fiori-tools, OData, manifest, webapp, annotation, replace, maxAge

**STEP**: 1 — Open Replace OData Service action

**DESCRIPTION**: Initiate the "Replace OData Service" action from the project context menu. You can run this action on the project main folder, the `webapp` folder, or directly on the `manifest.appdescr_variant` file.

**LANGUAGE**: Text

**CODE**:
```text
Right-click on:
- project main folder
- webapp
- manifest.appdescr_variant
Then choose: Replace OData Service
```

**STEP**: 2 — Select the target service to replace

**DESCRIPTION**: From the "Target OData Service" dropdown, select the service entry from the base application's manifest that you want to replace. This chooses which service configuration in the manifest will be updated.

**LANGUAGE**: Text

**CODE**:
```text
Target OData Service (dropdown)
Select the service from the base application's manifest to be replaced.
```

**STEP**: 3 — Enter new OData service URI

**DESCRIPTION**: Provide the URI of the new OData service that will replace the selected target. This updates the service root in the manifest entry.

**LANGUAGE**: Text

**CODE**:
```text
Enter the URI of the OData service you want to use instead.
```

**STEP**: 4 — (Optional) Set maxAge

**DESCRIPTION**: Optionally enter the `maxAge` value for the new OData service. This controls caching TTL used by the application for the service.

**LANGUAGE**: Text

**CODE**:
```text
maxAge
(Optional) Enter the maxAge of the new OData service.
```

**STEP**: 5 — (Optional) Replace OData Annotation Data Source

**DESCRIPTION**: If the new OData service supports annotations, optionally enter the URI for the OData Annotation Data Source to use instead. The field will be visible only when annotations are supported by the selected service.

**LANGUAGE**: Text

**CODE**:
```text
OData Annotation Data Source
(Optional) Enter the URI of the OData Annotation Data Source you want to use instead.
(Visible only if the new service supports annotations.)
```

**STEP**: 6 — Save changes

**DESCRIPTION**: Finalize the replacement. Click "Finish" to apply and save the updated manifest and related configuration.

**LANGUAGE**: Text

**CODE**:
```text
Click Finish to save your changes.
```

**STEP**: Compatibility requirements (important)

**DESCRIPTION**: Ensure the new OData service is compatible with the original application service. The following must be preserved in the new service:
- The same entity set names used by the app
- The same properties within those entity sets
- Any function imports the app uses

For OData V2 services that use annotations:
- You must update the annotation data source to point to a compatible annotation file
- The new annotation file must be compatible with the original application's annotations

**LANGUAGE**: Text

**CODE**:
```text
Note:
The new OData service must be compatible with the OData service of the original app.
The entity set names, properties in the entity set, and function imports used from the original service must also exist in the new service.
For OData V2 services using annotations, the annotation data source must be changed and the new annotation must also be compatible with the annotation of the original application.
```

Replacing OData Service (fiori-tools)

fiori-tools OData manifest webapp annotation replace maxAge


**TITLE**: Replacing OData Service in an Adaptation Project

**INTRODUCTION**: This guide instructs how to replace the OData service referenced by an adaptation project by updating the adaptation project's manifest entry (manifest.appdescr_variant). Follow the wizard steps to point the adaptation to a compatible alternative OData service and, optionally, a different annotation data source and cache maxAge.

**TAGS**: fiori-tools, odata, adaptation, manifest, annotations, SAPUI5

**STEP**: Compatibility check (required)
**DESCRIPTION**: Verify the new OData service and, if used, the new annotation service are compatible with the original app. Ensure the following items exist and match the original service:
- Entity set names used by the app
- Properties within those entity sets
- Function imports used by the app
- For OData V2 with annotations: the new annotation data source must be compatible with the original annotation

**LANGUAGE**: PlainText
**CODE**:
```text
Compatibility checklist:
- Entity set names: must match originals
- Entity set properties: must include required properties
- Function imports: must be present and compatible
- OData V2 annotations (if used): new annotation DS must be compatible
```

**STEP**: Open adaptation project manifest
**DESCRIPTION**: Locate and open the adaptation project's manifest file named manifest.appdescr_variant. Right-click this file to start the Replace OData Service wizard.
- File to open: manifest.appdescr_variant

**LANGUAGE**: PlainText
**CODE**:
```text
File: manifest.appdescr_variant
Action: Right-click -> Adaptation Project -> Replace OData Service
```

**STEP**: Authenticate to system (if prompted)
**DESCRIPTION**: If the wizard prompts, enter the credentials for the backend/system where the adaptation project was created. This is required to access the base application's manifest and available services.

**LANGUAGE**: PlainText
**CODE**:
```text
Prompt: Enter credentials for the system where the adaptation project was created
Purpose: To access base application manifest and available OData services
```

**STEP**: Select target OData service
**DESCRIPTION**: In the wizard, choose which service in the base application's manifest you want to replace from the Target OData Service dropdown. This selection picks the existing service reference that will be replaced.

**LANGUAGE**: PlainText
**CODE**:
```text
Field: Target OData Service (dropdown)
Action: Select the service entry from the base app's manifest that you intend to replace
```

**STEP**: Enter new OData service URI
**DESCRIPTION**: Provide the URI of the replacement OData service that the adaptation should use instead of the original.

**LANGUAGE**: PlainText
**CODE**:
```text
Field: OData service URI
Example input: https://my.backend.example.com/odata/service/
```

**STEP**: (Optional) Set maxAge
**DESCRIPTION**: Optionally set the cache maxAge for the new OData service. This value controls client-side caching behavior for the service.

**LANGUAGE**: PlainText
**CODE**:
```text
Field: maxAge (optional)
Action: Enter numeric cache duration (e.g., 0 for no cache)
```

**STEP**: (Optional) Replace OData Annotation Data Source
**DESCRIPTION**: If the selected service supports annotations, the wizard shows a field to provide the URI for a replacement OData Annotation Data Source. Only provide this if the new annotation DS is compatible with the original annotations used by the app.

**LANGUAGE**: PlainText
**CODE**:
```text
Field: Annotation Data Source URI (visible if service supports annotations)
Action: Enter the annotation data source URI compatible with the original annotations
```

**STEP**: Finish and save changes
**DESCRIPTION**: Click Finish in the wizard to apply and save the changes to manifest.appdescr_variant. Confirm the adaptation project now references the new OData service (and annotation DS if provided).

**LANGUAGE**: PlainText
**CODE**:
```text
Action: Click Finish
Result: manifest.appdescr_variant updated to reference new OData service (and annotation DS if provided)
```

fiori-tools odata adaptation manifest annotations SAPUI5


**TITLE**: Updating the Adaptation Project (Fiori Tools)

**INTRODUCTION**: Instructions to update (redeploy) an existing adaptation project to an on-premise ABAP system using the Adaptation Project deployment flow. Use these steps to automate or script the UI actions or to implement a deployment flow in tooling.

**TAGS**: fiori-tools, adaptation-project, deployment, ABAP, on-premise, manifest.appdescr_variant

**STEP**: Prerequisites

**DESCRIPTION**: Ensure the adaptation project was previously deployed to the ABAP repository. Follow the prior deployment procedure before attempting an update:
- Reference: Deploy the Adaptation Project to the ABAP Repository — https://help.sap.com/docs/bas/developing-sap-fiori-app-in-sap-business-application-studio/deploy-adaptation-project?locale=en-US

**LANGUAGE**: Plain Text

**CODE**:
```text
Prerequisite:
- Project already deployed to on-premise ABAP system (see link above)
- Target project files present:
  - <projectRoot>/webapp/
  - <projectRoot>/webapp/manifest.appdescr_variant
```

**STEP**: Step 1 — Open Deployment Wizard

**DESCRIPTION**: Open the Deployment Wizard on the project item you want to deploy. You may open it on:
- the project root (main folder),
- the webapp folder,
- or the file webapp/manifest.appdescr_variant.

This locates the adaptation project and starts the deployment flow.

**LANGUAGE**: Plain Text

**CODE**:
```text
UI action:
- Right-click on one of:
  - <projectRoot>                   (main folder)
  - <projectRoot>/webapp            (webapp folder)
  - <projectRoot>/webapp/manifest.appdescr_variant
- Select: "Open Deployment Wizard"
```

**STEP**: Step 1 — Automation pseudocode (optional)

**DESCRIPTION**: Example pseudocode for locating the target and invoking the wizard in an automated tool or extension.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// Pseudocode: find target and open deployment wizard
const projectRoot = findProjectRoot(); // implement resolver
const targets = [
  projectRoot,
  path.join(projectRoot, 'webapp'),
  path.join(projectRoot, 'webapp', 'manifest.appdescr_variant')
];
const target = chooseFirstExisting(targets);
openDeploymentWizard(target); // hook into IDE/extension API
```

**STEP**: Step 2 — Select Target System

**DESCRIPTION**: In the Deployment Wizard, pick the on-premise ABAP system to deploy to. The system used when the project was created is selected by default. Verify or change the target system as needed.

**LANGUAGE**: Plain Text

**CODE**:
```text
UI action:
- In Deployment Wizard: select target system
  - Default: the system used to create the project
  - Option: choose another configured ABAP on-premise system
```

**STEP**: Step 2 — Automation pseudocode (optional)

**DESCRIPTION**: Example pseudocode to programmatically select a deployment system.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// Pseudocode: select or confirm deployment system
const availableSystems = listConfiguredABAPSystems();
const systemToUse = availableSystems.find(s => s.id === defaultSystemId) || availableSystems[0];
deploymentWizard.selectSystem(systemToUse);
```

**STEP**: Step 3 — Choose Update

**DESCRIPTION**: If the selected project has already been deployed to the chosen system, the wizard prompts for action. Choose "Update" to redeploy changes (alternatively "Undeploy" to remove).

**LANGUAGE**: Plain Text

**CODE**:
```text
UI prompt (when project already deployed):
- Prompt: "What action would you like to perform?"
- Options: [Update] [Undeploy]
- Action: Click "Update"
```

**STEP**: Step 3 — Automation pseudocode (optional)

**DESCRIPTION**: Pseudocode to handle the update prompt programmatically.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// Pseudocode: if project is already deployed, choose update
if (deploymentWizard.isAlreadyDeployed(target, systemToUse)) {
  deploymentWizard.chooseAction('Update');
}
```

**STEP**: Step 4 — Start Deployment

**DESCRIPTION**: After selecting Update, click "Next" to begin the deployment process. Monitor the wizard for progress and completion messages.

**LANGUAGE**: Plain Text

**CODE**:
```text
UI action:
- Click: "Next"
- The deployment process starts; observe progress and logs in the Deployment Wizard
```

**STEP**: Step 4 — Automation pseudocode (optional)

**DESCRIPTION**: Pseudocode to trigger the final deployment step and wait for completion.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// Pseudocode: start deployment and wait for completion
deploymentWizard.clickNext();
const result = deploymentWizard.waitForCompletion({ timeoutMs: 5 * 60 * 1000 });
if (result.success) {
  console.log('Deployment update completed successfully.');
} else {
  console.error('Deployment update failed:', result.error);
}
```

fiori-tools adaptation-project deployment ABAP on-premise manifest.appdescr_variant


**TITLE**: Upgrade-Safe Controller Extension Rules for SAPUI5 / SAP Fiori Adaptation Projects

**INTRODUCTION**: Practical, actionable rules and code patterns to make controller extensions resilient to base application upgrades. Use these guidelines when writing controller code, fragments, or adaptation-project changes to avoid breakage after upgrades and minimize maintenance.

**TAGS**: sapui5, fiori-tools, adaptation-project, controller-extensions, upgrades, best-practices, odata, resilience

**STEP**: 1 — Follow UI5 Best Practices

**DESCRIPTION**: Start every extension by following the official UI5 best practices. This reduces risk from framework and app changes. Use stable public APIs; avoid internal/private APIs and deprecated artifacts.

**LANGUAGE**: General

**CODE**:
```text
Reference: https://ui5.sap.com/#/topic/28fcd55b04654977b63dacbee0552712
Action: Follow the documented UI5 best practices before implementing extensions.
```

**STEP**: 2 — Use Stable IDs Only

**DESCRIPTION**: Always access controls by stable IDs. Never rely on DOM order, aggregation index, or parent-child traversal that depends on UI structure which can change on upgrade.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// Good: access by stable ID defined in XML view or fragment
const oButton = this.byId("stableIdMyButton");

// Bad: relying on aggregation order (avoid)
const aItems = this.getView().byId("myList").getItems();
const oFirstItem = aItems[0]; // fragile across upgrades
```

**STEP**: 3 — Check Existence and Control Type Before Use

**DESCRIPTION**: Always verify a control exists and is the expected control type before invoking methods or properties. This prevents runtime errors when the base app changes.

**LANGUAGE**: JavaScript / TypeScript

**CODE**:
```javascript
// JavaScript example in a controller
const oControl = this.byId("stableIdMyButton");
if (oControl && oControl.isA && oControl.isA("sap.m.Button")) {
  oControl.setEnabled(true);
} else {
  // fallback or safe handling
  // log, ignore, or use alternative logic
  console.warn("Expected sap.m.Button not found for 'stableIdMyButton'");
}
```

**STEP**: 4 — Handle Controls Added by Adaptation Projects

**DESCRIPTION**: Controls added via adaptation changes or fragments may not be present in all snapshots. Apply the same existence and type checks and avoid assuming presence.

**LANGUAGE**: XML / JavaScript

**CODE**:
```xml
<!-- fragment.xml: provide stable IDs when adding controls -->
<Button id="stableIdAddedButton" text="Do" />
```

```javascript
// Controller: safely access fragment-added control
const oAdded = this.byId("stableIdAddedButton");
if (oAdded && oAdded.isA && oAdded.isA("sap.m.Button")) {
  oAdded.attachPress(this._onAddedPress.bind(this));
}
```

**STEP**: 5 — Don’t Call or Override Private/Protected Methods

**DESCRIPTION**: Never call or override framework or base-app private/protected methods. Use public extension points, documented APIs, or official extension mechanisms (e.g., extension hooks, delegates).

**LANGUAGE**: General

**CODE**:
```text
Do:
- Use documented hooks, public APIs, or controller extension mechanisms.

Don't:
- Call methods named with leading underscore "_" or marked as @private/@protected in docs.
```

**STEP**: 6 — Avoid Deprecated Artifacts

**DESCRIPTION**: Do not use deprecated controls, properties, or methods. Use current recommended equivalents and consult UI5 documentation for replacement APIs.

**LANGUAGE**: General

**CODE**:
```text
Check UI5 API docs for deprecation notes and migrate to supported controls/APIs.
```

**STEP**: 7 — Avoid Value Help Entity Sets in Controller/Fragments

**DESCRIPTION**: Value helps are not part of the internal stability contract and may change during upgrades. Do not use value-help-specific entity sets for controller logic or for data binding inside XML fragments.

**LANGUAGE**: XML / JavaScript

**CODE**:
```xml
<!-- Avoid binding critical UI logic to value-help entity sets -->
<!-- Instead bind to stable entity sets exposed by the backend contract. -->
```

**STEP**: 8 — Write Resilient Reuse-Component Access

**DESCRIPTION**: Reuse components (e.g., smart controls, reuse libraries) may change implementation or behavior. Wrap calls in defensive code and handle errors gracefully.

**LANGUAGE**: JavaScript / TypeScript

**CODE**:
```javascript
try {
  // call into reuse component API
  const result = oReuseComponent.somePublicApi();
  // validate result before use
  if (result && typeof result === "object") {
    // proceed safely
  }
} catch (err) {
  // log and provide fallback behavior
  console.error("Reuse component call failed", err);
}
```

**STEP**: 9 — Don’t Hard-Code OData Metadata Values

**DESCRIPTION**: OData metadata can change after upgrades. Do not hard-code property values, entity names, or annotations. Read metadata dynamically and validate before use.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
const oModel = this.getView().getModel();
const oMetaModel = oModel.getMetaModel();
const sPropertyPath = "/EntityType('MyEntity')/Property('MyProp')"; // example: avoid hardcoding
// Better: discover service metadata via metaModel API and validate presence
if (oMetaModel && oMetaModel.getODataEntityType) {
  const oEntityType = oMetaModel.getODataEntityType("MyService.MyEntity");
  if (oEntityType && oEntityType.hasOwnProperty("MyProp")) {
    // safe to use MyProp
  }
}
```

**STEP**: 10 — For Fiori Elements Apps, Use Official Extension Guide

**DESCRIPTION**: For SAP Fiori elements-based apps, extend using the documented adaptation extension mechanisms to ensure compatibility with upgrades.

**LANGUAGE**: General

**CODE**:
```text
Reference: https://ui5.sap.com/#/topic/52fc48b479314d0688be24f699778c47
Action: Follow "Extending Delivered Apps Using Adaptation Extension" for Fiori elements.
```

**STEP**: 11 — Understand Snapshot Behavior in Adaptation Projects (S/4HANA Cloud)

**DESCRIPTION**: An adaptation project deployed to S/4HANA Cloud contains a runnable snapshot of the base application and local UI annotations. The snapshot keeps extended apps runnable after a base-app upgrade, but you must resolve conflicts and redeploy the adaptation project to benefit from the upgraded base app and to receive support.

**LANGUAGE**: General

**CODE**:
```text
Note: Snapshot ensures runtime stability after base-app upgrades.
Action: After base-app upgrade:
1. Test the adaptation using the snapshot.
2. Resolve conflicts between extension code and new base-app implementation.
3. Deploy a new version of the adaptation project to align with the upgraded base app.
Reference: Check Whether Your Adaptation Project Is Up-To-Date with Base App Upgrades (adaptation project documentation)
```

sapui5 fiori-tools adaptation-project controller-extensions upgrades best-practices odata resilience


**TITLE**: Viewing Generation Logs for SAP Fiori tools AI

**INTRODUCTION**: Steps to view the logs produced by the Project Accelerator using SAP Fiori tools AI in VS Code. Use these logs to troubleshoot generation failures or to attach when opening a support ticket. For produced applications, the generated project's logs are stored in its .fiori-ai folder — attach a .zip of the generated project when reporting issues with the app.

**TAGS**: fiori-tools, sap, sap-fiori, ai, logs, troubleshooting, vscode, project-accelerator

**STEP**: 1 — Open Command Palette and set log level

**DESCRIPTION**: Open the VS Code Command Palette and run the Developer: Set Log Level command. Set the log level to Info. Important: set the log level before generating your application and again whenever the dev space is restarted.

**LANGUAGE**: VS Code / Instructions

**CODE**:
```text
Keyboard: [CMD/CTRL] + [Shift] + [P]
Command: Developer: Set Log Level
Set value: Info
```

**STEP**: 2 — Open Terminal and switch to Output channel

**DESCRIPTION**: Open the Terminal view and switch to the Output tab. From the Output dropdown, select the SAP Fiori tools - AI channel to view generation logs in real time.

**LANGUAGE**: VS Code / Instructions

**CODE**:
```text
Menu: View > Terminal
Tab: Output
Output channel dropdown: select "SAP Fiori tools - AI"
```

**STEP**: 3 — What to include when filing a ticket

**DESCRIPTION**: If generation fails, include the SAP Fiori tools - AI logs when opening a ticket. If the generated app has issues, create and attach a .zip archive of the generated project. The generated app’s logs are located in the project's .fiori-ai folder — include those files in your archive.

**LANGUAGE**: Instructions / File paths

**CODE**:
```text
If generation fails:
  - Attach SAP Fiori tools - AI logs from the Output channel.

If the generated app has issues:
  - Create a .zip of the generated project.
  - Include files from the project's .fiori-ai folder in the .zip.
```

fiori-tools sap sap-fiori ai logs troubleshooting vscode project-accelerator


**TITLE**: Working with an Adaptation Project (SAP Fiori Tools)

**INTRODUCTION**: This guide gives concise, action-oriented steps for opening, preparing, editing, and running a Fiori adaptation project so code-generation agents can automate common tasks (setup, launch, edit, test). Use the commands and file examples below as executable building blocks in automation scripts or generation templates.

**TAGS**: fiori-tools, sap, ui5, adaptation, dev-setup, manifest

**STEP**: 1 — Verify prerequisites

**DESCRIPTION**: Ensure the environment has Node.js, npm, and an editor/IDE (e.g., VS Code). These checks are the first automated steps before performing any project operations.

**LANGUAGE**: Shell

**CODE**:
```bash
# Check Node.js and npm versions
node -v
npm -v

# (Optional) Check VS Code CLI availability if using VS Code for automation
code --version
```

**STEP**: 2 — Open the adaptation project in your workspace

**DESCRIPTION**: Open the local adaptation project directory in your editor/IDE so subsequent automation tasks can read and modify files. Use an absolute or repository-relative path when scripting.

**LANGUAGE**: Shell

**CODE**:
```bash
# Open project in VS Code (replace with your path)
code /path/to/adaptation-project
```

**STEP**: 3 — Install project dependencies

**DESCRIPTION**: Install npm dependencies declared by the adaptation project. Run this in the project root so the environment is prepared for local development, building, or running preview servers.

**LANGUAGE**: Shell

**CODE**:
```bash
cd /path/to/adaptation-project
npm install
```

**STEP**: 4 — Start the local dev/preview server

**DESCRIPTION**: Launch the project’s local server or preview command. This commonly runs UI5 or Fiori tooling preview/watch tasks. Use the project’s package.json scripts; fall back to a standard "start" script in automation.

**LANGUAGE**: Shell

**CODE**:
```bash
# Common start command (use the project's defined script)
npm run start

# If the project defines a specific preview script:
npm run preview
```

**STEP**: 5 — Locate and edit key UI5/Fiori files for adaptation

**DESCRIPTION**: Typical adaptation edits are made in webapp/ (source), manifest.json (component and routing configuration), and UI controller/view files. Automation tools should target these canonical paths when generating or patching code.

**LANGUAGE**: Plain Text

**CODE**:
```text
Common file locations to read or update (relative to project root):
- webapp/manifest.json
- webapp/index.html
- webapp/Component.js
- webapp/controller/*.controller.js
- webapp/view/*.view.xml
```

**STEP**: 6 — Minimal manifest.json example for automation templates

**DESCRIPTION**: Use this minimal manifest skeleton when generating or validating a manifest.json during code generation. Include required sap.app and sap.ui5 sections and expand as needed.

**LANGUAGE**: JSON

**CODE**:
```json
{
  "sap.app": {
    "id": "my.adaptation.app",
    "type": "application",
    "i18n": "i18n/i18n.properties"
  },
  "sap.ui5": {
    "dependencies": {
      "minUI5Version": "1.60.0",
      "libs": {
        "sap.m": {}
      }
    },
    "models": {},
    "rootView": {
      "viewName": "my.adaptation.app.view.App",
      "type": "XML",
      "async": true
    }
  }
}
```

**STEP**: 7 — Persist and validate changes

**DESCRIPTION**: After edits, commit changes, and run validation or lint tasks. Use npm scripts or CLI tools to validate project integrity before building or deploying.

**LANGUAGE**: Shell

**CODE**:
```bash
# Run linter/validator if available
npm run lint

# Run tests if defined
npm test

# Commit changes (example)
git add .
git commit -m "Adaptation edits: <brief description>"
```

fiori-tools sap ui5 adaptation dev-setup manifest