Skip to content
/ xsa-cap-migration-using-basextn Public

The SAP HANA application migration assistant demonstrates the migration of XSA application database artefacts to SAP Cloud Application Programming model with SAP HANA Cloud as a database

License

Apache-2.0 license
4 stars 1 fork Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

SAP-samples/xsa-cap-migration-using-basextn

BranchesTags

Repository files navigation

Migration of SAP HANA XS Advanced To SAP Cloud Application Programming Model Using SAP HANA Application Migration Assistant

REUSE status

Description

The SAP HANA Application Migration Assistant allows users to migrate XS Advanced application to a SAP CAP application with SAP HANA Cloud as a database. In this enhanced version, the assistant performs:

Automated Conversion of Database Artifacts: Source XS Classic Repository database objects (such as .hdbcds, .hdbtable, .hdbview, etc.) are transformed into their corresponding SAP CAP compliant database artifacts (e.g., .cds models), with naming adapted to SAP HANA Cloud conventions.

Service Layer Migration via Generative AI: Using GenAI, the assistant analyzes .xsodata, .xsjs, and .xsjslib files to generate corresponding service.cds, service.js, and custom handler implementations under the CAP srv/ layer. This accelerates the migration of service logic while preserving structure, routes, and functional behavior where possible.

Caution

As generative AI conversion is not guaranteed to be 100% accurate, human intervention is required post-migration to validate, refine, and productionize the application logic and service definitions.

In this sample, only conversion of Source XS Advanced database artifacts to the corresponding target SAP CAP compliance database artifacts are listed.

Introduction

SAP HANA Interactive Education or SHINE is a demo application. It includes the following features:

  • HDI Features:
    • Table
    • HDBCDS Views
    • Sequence
    • Calculation Views
    • Associations
    • Table Functions
    • Synonyms
    • Procedures
    • Cross Container Access
    • Multiple Containers
    • Spatial Features
    • Local Time Data Generation
    • Comments for Tables
    • Index
    • Structured Privilege
    • Analytical Privilege
    • Usage of Table Functions in CDS views

SHINE follows the XS Advanced Programming Model(XSA) and uses SAP HANA on-premise for the database. This article describes the steps to be followed to Migrate this Demo Application from XS Advanced to the SAP Cloud Application Programming Model(CAP) with SAP HANA Cloud as the database using the SAP HANA Application Migration Assistant.

Features Currently supported in SAP HANA Application Migration Assistant:

For a detailed list of the features supported by the SAP HANA Application Migration Assistant, please refer to the supportedFeatures link.

Features that are currently out of scope in SAP HANA Application Migration Assistant:

  1. Creating proxy cds for cross container schema

  2. Following Artifacts are not currently supported '.hdbreptask', '.hdbvirtualtable'.

Requirements

  • XS Advanced on-premise database source system with the SHINE content. Specifically the schema name of the deployed containers.
  • SAP Business Technology Platform subaccount with the following
    • Service instances:
      • SAP Hana Cloud and
      • SAP Hana Schemas and HDI Containers
    • Subscription
      • SAP Business Application Studio or SAP Build. SAP Build is required if you want to convert the service layer as well, since GenAI capabilities are only available in SAP Build plans.
  • SAP Cloud Connector

Where to Start

To successfully migrate the SHINE sample application using the SAP HANA Application Migration Assistant, follow the steps below:

  1. Install and Configure the SAP Cloud Connector.
  2. Setup an SAP BTP Destination to connect to the source system.
  3. Create a Dev Space in either SAP Business Application Studio or SAP Build with SAP HANA Application Migration Assistant extension installed.
  4. Migrate using the SAP HANA Application Migration Assistant.
  5. Post Migration Changes.
  6. Deployment of the Migrated database artifacts.

Note

This sample covers only the migration of the database artifacts from SAP Hana XS Advanced Database to SAP Hana Cloud. The migration steps should be tested in a development environment before production.`

Step-1: Install and Configure the SAP Cloud Connector

  1. Install the SAP Cloud Connector on your local system. For the installation and setup of the cloud connector, please refer to this Documentation.

  2. After installing the cloud connector, you can access it by opening your web browser and going to https://localhost:<port-no>/. Use your credentials to log in.

  3. Once you've successfully logged in, you should set up a connection in the Cloud Connector.

    • This connection should link to the subaccount with the source database. To establish this connection, click on the connector button in the left menu.

    • Next, enter the necessary details for your subaccount, which include the Region, Subaccount ID, Display Name, Subaccount User, Password, and Location ID. After entering all the information, click on 'Save'.

  1. Select the created connection, then add a mapping under 'Cloud to On-Premise' using the following details:

    • Back-end Type: SAP Hana

    • Protocol: TCP

    • Internal Host: localhost / on-prem hostname

    • Internal Port: < portno > (The port number to connect to the database)

    • Virtual Host: myvirtualhost

    • Virtual Port: This should be the same as your internal port

Step-2: Setup an SAP BTP Destination to connect to the source system

Navigate to the Target SAP BTP Cloud Foundry subaccount and select 'Destination' under 'Connectivity' from the left menu pane. Create a new destination using the following details:

  • Name: < Destination name >
  • Type: HTTP
  • URL: https://<virtual-host>:<virtual-port-no>/
  • ProxyType: on-premise
  • Authentication: NoAuthentication
  • Locationid: Location id as mentioned in cloud connector

And the following additional properties:

  • HTML5.DynamicDestination : true
  • WebIDEEnabled : true
  • WebIDEUsage : xs_hdb

Step-3: Create a SAP Business Application Studio or SAP Build Devspace with the SAP HANA Application Migration Assistant Extension installed

  1. In the SAP BTP subaccount where you created the destination, create a subscription to SAP Business Application Studio (BAS) or SAP Build. Choose SAP Build if you intend to convert the Service Layer. The correct way to subscribe to SAP Build Code is using the booster and not the manual setup.

Important

Service Layer migration leverages Generative AI capabilities, which are available only in SAP Build plans.

  1. Open SAP Business Application studio or SAP Build subscription.

  2. If selecting SAP Build, it will take it to lobby page. From there switch to Dev space manager.

  1. Select "Create Dev Space". Assign a desired name to your Dev Space and select the "Full Stack Cloud Application" type. Then, choose the SAP HANA Application Migration Assistant Extension to help with migration, as well as the SAP Hana Tools Extension which will be required later for deployment. Finally, click on "Create Dev Space".

  2. Wait for the status of your newly created Dev Space to change to "Running". Once it's running, you can open it by clicking on the name of the Dev space that you just created.

  3. Navigate to the folder by clicking on File -> Open Folder. Enter the path /home/user/projects/ and click on OK.

  4. Clone the XS Advanced Source application to this folder using the Terminal.

  5. Once the folder opens, you can select the SAP HANA Application Migration Assistant from the Command Palette (You can access the Command Palette from View -> Command Palette).

Step-4: Migrate using the SAP HANA Application Migration Assistant

  1. Open the the Command Palette and type "SAP HANA Application Migration Assistant" and select the command when it appears.

  2. When the Migration Assistant Wizard opens, select the migration path. Since we are migrating from XS Advanced to CAP, select XSA to CAP as your migration path.

HomeScreen

  1. In the Data Source page of the wizard, choose the destination you previously created from the dropdown menu.

DestinationList

  1. Enter the user credentials for the SAP HANA Database HDI User—username and password—into their respective fields. Then, click the login button to authorize these credentials. Click on the Next button.

Login

  1. In the "Source Type" page, select your cloned project from the drop down. In this case, its hana-shine-xsa.

selectType

  1. Select the DB Folders(It can be multiple). In this case it will be core-db and user-db.

DU1

  1. Choose the target directory. This is where the migration results will be stored.

    Note: Ensure that the directory you select is a sub-directory of /home/user/projects.

  2. Specify a unique name for the Target Folder, where the migration results will be saved. Once you've entered the name, click on Next.

end

  1. Select "Yes" if you would like to convert Service Layer using GenAI capabilities.

Important

Service Layer conversion is available only in SAP Build plans. This feature is currently experimental and free, but is subject to change in the future

end

  1. In the "Schema" page, Enter the schema name of the containers. Once entered, click on Finish.

end

  1. Once you see the pop-up notification at the bottom right corner of your screen, it means that the migration process is underway. This notification will keep you updated on all the steps that follow. At the end of the process, a CAP project with the revised database artifacts will be created. Additionally, a report.html file will be generated within the project. This file contains detailed information about your project's migration.

end

Step-5: Post Migration Changes

Once the project is created, there are some adjustments we need to make manually as these are not currently handled by the SAP HANA Application Migration Assistant.

  1. For the hana-shine-xsa project, make the following changes:

    • A folder named unsupported_feature has been created by the extension to contain file extensions that are not supported in SAP HANA Cloud. Delete this unsupported_feature folder from core-db/src/data folder. For more information on the unsupported features, please refer to this link.

    • Delete synonyms/sys_rt.hdbsynonym from core-db/src folder.

    • In core-db/cds/data/POViews.cds file, change the alias ProductName to PRODUCTNAME.

    • Replace the code in the mta.yaml with the below code. Replace <Project Name> with the name of your project.

      _schema-version: 3.3.0
ID: <Project Name>
version: 1.0.0
description: A migrated CAP Project.
parameters:
  enable-parallel-deployments: true
build-parameters:
  before-all:
    - builder: custom
      commands:
        - npm ci
        - npx cds build --production
modules:
  - name: <Project Name>-deployer0
    type: hdb
    path: gen/core-db
    deployed-after:
      - <Project Name>-deployer1
    parameters:
      buildpack: nodejs_buildpack
    requires:
      - name: <Project Name>-db0
        properties:
          TARGET_CONTAINER: ~{hdi-container-name}
      - name: <Project Name>-db1
        group: SERVICE_REPLACEMENTS
        properties:
          key: hdi-user-service
          service: ~{user-container-name}
  - name: <Project Name>-deployer1
    type: hdb
    path: gen/user-db
    parameters:
      buildpack: nodejs_buildpack
    requires:
      - name: <Project Name>-db1
resources:
  - name: <Project Name>-db0
    type: com.sap.xs.hdi-container
    parameters:
      service: hana
      service-plan: hdi-shared
    properties:
      hdi-container-name: ${service-name}
  - name: <Project Name>-db1
    type: com.sap.xs.hdi-container
    parameters:
      service: hana
      service-plan: hdi-shared
      service-name: <Project Name>-db1
    properties:
      user-container-name: ${service-name}

      Note: In the Shine demo application, since we have multiple containers, we need to define service replacements in the above format to connect the containers. If the project has only one container, the mta.yaml file created by the extension should work as expected, and no manual changes are needed.

  2. Currently, changes to Reptask and Replication artifacts are not covered. You will need to modify these manually. Unsupported types and functions in the calculation view such as "CE_FUNCTION", "CACHE", etc., need to be noted. Please refer to the SAP HANA Cloud Documentation for more details on how to handle these.
  3. Series entity is not supported in Hana Cloud so they will be removed by the extension. Please check Migration Documentation for more information.
  4. For HdbSynonym, HdbSynonymconfig and Hdbrole files, please check target object parameters before deployment.

Step-6: Service Layer Migration

Caution

While the assistant automates a large portion of the migration process, the converted output is not guaranteed to be 100% runnable or semantically equivalent. Manual validation and adjustments are essential to reach production readiness.

Conversion structure

The Gen-AI Migration Assistant converts SAP XS files and components into their equivalent SAP CAP service definitions and handlers, preserving structure and logic for ease of validation and enhancement.

Converted File Mapping

SAP XS SAP CAP
xsodata service.cds & service.js
xsjslib handlers/source_filename.js
xsjs handlers/source_filename.js

Directory and File Structure

  • The original directory structure is preserved during conversion.
  • All .xsodata files within a folder are consolidated and converted into a single service.cds file with service names derived from the original filenames.
  • Corresponding service logic is placed in a service.js file,
  • .xsjslib and .xsjs files are converted into JavaScript files and placed under the handlers/ directory, maintaining the original folder hierarchy.
  • These handler files are then properly referenced in the implementation via:
    • custom-service.cds for additional service definitions, and
    • custom-service.js for custom logic implementation.
  • Finally index.cds is generated at the root folder to import all service definitions.

Before: SAP XS Files

sales/lib/
│       |--- getSales.xsjs
│       |--- salesOrder.xsodata
│       |--- salesHelper.xsjslib
|       |--- utils.xsjslib
|       |--- config.xsjs
manufacture/lib
│       |--- workorder.xsodata
│       |--- jobcard.xsjs
│       |--- workorderHelper.xsjslib

After: SAP CAP Service Definitions & Custom Handlers

srv
|
|---/sales/lib/
│           |--- service.cds           
│           |--- service.js            
│           |--- custom-service.cds            
│           |--- custom-service.js             
│           |--- handlers/
│                  |--- getSales.js
|                  |--- salesHelper.js
|                  |--- config.js
│                  |--- utils.js
|---/manufacture/lib
│           |--- service.cds           
│           |--- service.js  
|           |--- custom-service.cds
|           |--- custom-service.js
|           |--- handlers/
|                   |--- jobcard.js
|                   |--- workorderHelper.js
|--- index.cds

Source Path Reference in converted files

Each code block will have the source code path from which it is been converted.

//converted from: /workspaces/project/sales/lib/salesOrder.xsodata
service salesOrder @(path:'/salesOrder') {

}

Post Migration Common Changes

The following steps are critical to ensure the converted project builds and runs as intended.

service.cds

  • Entity Imports: Confirm that all entities from DB are correctly imported. Some imports may be missing or incorrectly formatted. Add missing using statements manually. ℹ️ CAP by default converts HANA object names to uppercase with underscores. Refer CAP HANA Naming Convention.

  • Service Name: Each service.cds file uses the xsodata filename as the service name. There might be duplicate service names due to same .xsodata filenames across directories. Verify and rename if required.

  • Duplicate Exposed Entities: If multiple services expose the same entity, review and remove duplicates unless explicitly needed.

  • Entity Columns: Check if column names align with functional logic. If mismatches exist, correct them based on the original .xsodata logic.

  • Associations & Compositions: If an entity contains complex association or composition relationships, verify that they are correctly structured. The Gen-AI may not always interpret or convert deep associations accurately. You may need to rewrite them manually based on the original data model and business logic.

service.js

  • Review for correct binding between entity operations and handler functions (e.g., srv.on('READ', ...)).

custom-service.cds

  • Default service name is CustomService. You must rename it to a unique and meaningful name.
  • Validate that any additional or extended services are logically separated from the main service.cds.

custom-service.js

  • Ensure all custom logic handlers are correctly implemented and bound.
  • Replace or refactor placeholder logic (if any) added by the migration assistant.

handlers

  • Confirm that all converted xsjs/xsjslib files are present.

  • Import paths may be incorrect after migration. Review and adjust the import paths in your .js files to ensure all modules and handlers are correctly referenced.

  • Each file must export a function that binds to its relevant service events. In ES6 script there are multiple ways in which a function or a file can be imported or exported. Please review all the exports done in each file and make sure that they are imported correctly in other files.

Exports Imports Ways to call
export default function; import function from "./file.js"; function();
export default {function1, function2}; import file from "./file.js"; file.function1(); file.function2();
export async function function1(){}; import {function1, function2} from "./file.js"; function1(); function2();
export { function1, function2 }; import * as file from "./file.js;" file.function1(); file.function2();
export { function1, function2 }; import {function1, function2} from "./file.js"; function1(); function2();

  • If the original .xsjs code contains raw SQL statements, these may reference tables, views, or columns using SAP HANA naming. But in SAP HANA Cloud, naming conventions follow uppercase with underscores. Review and adjust any raw SQL queries in the code to align with the actual object names referring to migrated db artifacts. Reference DB migration report for the converted/ renames entities.

  • Verify functionality by comparing with original .xsjs and .xsjslib logic. Some constructs (e.g., response manipulation, error handling) require adaptation to CAP's async/event model.

Tips

  • Run cds lint to catch syntax and model issues early.

  • Use cds watch during development for hot-reloading and fast testing.

  • The entry point for the service layer is index.cds. You can use this file as a starting point to troubleshoot Node.js related issues. To isolate problems:

    • Use Node.js debuggers.
    • Temporarily comment out services in index.cds one by one to identify which service is causing the failure.

  • Unexpected Reserved Keyword is a frequently encountered issue. This typically occurs when async and await are used incorrectly. For example, using await outside of an async function or misplacing the async keyword in handler definitions.

  • For security, define @requires annotations and configure xs-security.json accordingly.

  • If xsjs logic depends on HANA procedures or views, consider rewriting as CDS views or wrapping them in srv.on(...) handlers.

  • Refer SAP CAP extensive documentation for HANA Native Object usage, service definitions and custom handlers.

Step-7: Deployment of the Migrated database artifacts.

  1. Using the Terminal, navigate to the root of the target folder.

  2. Right click on the mta.yaml and select Build MTA Project.

  3. Next, log in to your Cloud Foundry account using the following steps:

    • Open a new terminal in the SAP Business Application Studio
    • Run the command cf login -a < API_URL > and input your username and password

  4. Right click on the mtar file inside mta_archives folder and select Deploy MTA Archive.

Data Migration

For migration of data using the SAP HANA Application Migration Assistant, please refer to the DataMigration document.

Learning Resources

  1. The Self-Service Migration Tool for SAP HANA Cloud.
  2. SAP HANA Cloud, SAP HANA Database Developer Guide for Cloud Foundry Multitarget Applications (SAP Business App Studio)

How to obtain support

If you find a bug or have a question about the steps raise ticket under component BC-XS-TLS-MIG. For additional support, ask a question in SAP Community.

License

Copyright (c) 2024 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the LICENSE file.

About

The SAP HANA application migration assistant demonstrates the migration of XSA application database artefacts to SAP Cloud Application Programming model with SAP HANA Cloud as a database

Topics

sample migration bas xsa sap-hana-cloud xsa-cap

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Security policy

Security policy
Activity
Custom properties

Stars

4 stars

Watchers

8 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Contributors 6

Languages