Executing the Java Application Migration Skill Chain

Objective

After completing this lesson, you will be able to understand how specific migration skills transform Neo Java applications by identifying their artifacts, tracing their step-by-step impact, and locating guidance for remaining migration requirements.

Introduction

This lesson covers the automated migration of Java applications from the SAP BTP, Neo environment to the Cloud Foundry environment. You will explore the migration skill chain, a sequence of AI-driven transformations that modernize your code and configuration. Key focus areas include the jakarta-java25-migration for upgrading to Jakarta EE 10, setting up an Application Router, and integrating SAP Authorization and Trust Management service (XSUAA). Finally, you will learn to generate the mtad.yaml using the mta-descriptor skill.

By understanding these artifacts, you can successfully transition legacy Neo environment applications to a modular, cloud-native architecture on SAP BTP.

The Sample Application

Throughout Unit 3, all demos and exercises use a purpose-built sample application created specifically for this course. It is a representative Neo environment Java application that uses form authentication, accesses the Neo environment user management API, and is structured as a standard WAR project — typical of what you would find in a real Neo environment to Cloud Foundry environment migration.

Download the Sample Application:

  1. Download the SAP BTP, Neo environment sample application from GitHub
  2. Download the repository.
  3. Open the neo/ folder in your AI coding tool and follow along with the steps in this lesson.
Divider

After running the migration, two commands let you explore the full diff between the original and migrated application:

  • See all newly created files the AI added during migration:

    Code Snippet
    1
    git status --untracked-files=all
  • Compare every file between the original Neo environment folder and the migrated output folder side by side:

    Code Snippet
    1
    diff -r neo cf-ai-migrated

These are useful if you want to understand exactly what the skills transformed — and a good sanity check before deploying.

DividerMethod-1

Natural Language Prompt (Recommended): The simplest way to start is with a natural language prompt—no skill names required.

  • For local files:
    Code Snippet
    1
    Migrate the application in the current folder from Neo environment to SAP BTP, Cloud Foundry runtime. Create the migrated version in a new folder next to the original.
  • or GitHub repositories:
    Code Snippet
    1
    Migrate the application at <github-repo-url> from Neo environment to SAP BTP, Cloud Foundry runtime

The AI will analyze the project, determine which skills apply, and execute them in the correct order — pausing at each step for your review.

Method 2

Individual Skill Invocation: For more control, you can invoke individual skills by name. For example, to run only the namespace migration:

Code Snippet
1
Use the jakarta-java25-migration skill to upgrade this project to Java 25 and Jakarta EE 10

Skill-by-skill invocation is useful when you want to inspect or redo a specific transformation without rerunning the full migration.

The Skill Dependency Order

As established in Lesson 1.2, Track 1 skills must run in a strict dependency order. For the sample application, the relevant sequence is:

Code Snippet
12345678910
jakarta-java25-migration ↓ sdk-replacement ↓ approuter-setup ↓ authentication-xsuaa ↓ mta-descriptor ← always last

This lesson focuses on four of these skills:

  • jakarta-java25-migration
  • authentication-xsuaa
  • approuter-setup
  • mta-descriptor
These four cover the most fundamental transformations required by any Neo environment Java application migrating to Cloud Foundry runtime.

For the remaining skills in the chain — sdk-replacement, keystore-credstore, persistence-hana, document-management-sdm, destinations, connectivity-onpremise, mail-destinations, monitoring-logging, and tomee-runtime — refer to:

  • Lesson 1.2 for a summary of what each skill does and where it fits in the dependency order

  • The ai-migration/README.md in the migration repository for full per-skill technical detail

The following sections provide a detailed breakdown of the four primary skills used in this migration path.

Skill 1: jakarta-java25-migration

What it does : This is the first code transformation skill and a hard prerequisite for everything that follows. It performs two related changes:

  1. Namespace migration — every javax.* import in the Java source is replaced with its jakarta.* equivalent. This covers javax.servlet, javax.persistence, javax.inject, javax.ws.rs, and others.

  2. Java version upgrade — the project's Maven configuration is updated to target Java 25.

What it detects: The skill activates when it finds Java 8 or Java 11 source level in pom.xml, or any javax.* import in the source files.

What it produces:

  • Updated Java source files with corrected jakarta.* imports throughout

  • Updated pom.xml with Java 25 compiler settings and Jakarta EE 10 dependency versions

What to review after running it: The skill handles the bulk of the transformation automatically, but some edge cases require manual attention:

  • Apache Chemistry OpenCMIS libraries (org.apache.chemistry.opencmis) have not been migrated to Jakarta — if your application uses document store services, these dependencies need to be explicitly excluded or replaced.

  • Any reflection-based code that refers to javax.* class names as strings will not be caught by the automated migration and must be updated manually.

Skill 2: approuter-setup

What it does: Browser-facing Java applications on Cloud Foundry runtime require an Application Router — a Node.js component that sits in front of the backend application and handles OAuth 2.0 token flows, session management, and request routing. The Neo environment handled these concerns internally; on Cloud Foundry runtime they must be managed explicitly.

The approuter-setup skill creates the Application Router alongside the Java application. It generates:

  • approuter/package.json — declares the @sap/approuter Node.js dependency

  • approuter/xs-app.json — defines the routing rules: which URL patterns are forwarded to the Java backend, which serve static content, and what authentication is required for each route

What it detects: The skill activates when it finds a webapp/ directory, a web.xml file, or HTML content in the project — indicators that the application has a browser-facing component.

What it produces:

  • approuter/ directory with package.json and xs-app.json

  • Optional extended middleware configuration for complex scenarios (SAML2 federation, Basic Auth pass-through)

What to review after running it:

  • The generated xs-app.json contains a default routing rule that forwards all requests to the backend. Review and refine the route definitions to match your application's actual URL structure.

  • If your application serves static assets (HTML, JavaScript, CSS) directly, add explicit routes for those paths so they are served correctly by the Application Router rather than forwarded to the Java backend.

Skill 3: authentication-xsuaa

What it does: This skill replaces the Neo environment's built-in authentication provider with XSUAA — the SAP Authorization and Trust Management Service for Cloud Foundry runtime. On Neo environment, authentication is handled implicitly by the platform using FORM-based login. On Cloud Foundry runtime, the application must explicitly integrate with XSUAA using the cloud security services integration library.

The skill makes the following changes:

  • Updates web.xml — replaces the <auth-method>FORM</auth-method> declaration with the XSUAA-compatible configuration

  • Creates xs-security.json — the application security descriptor that defines OAuth 2.0 scopes, role templates, and role collections

  • Updates pom.xml — adds the cloud-security-services-integration-library dependency

  • Updates user principal access — replaces Neo environment's UserManagementAccessor with standard servlet methods (request.getUserPrincipal() and request.isUserInRole()); for direct JWT claims access, use SecurityContext.getToken()

What it detects: The skill activates when it finds <auth-method>FORM</auth-method> in web.xml, security-constraint definitions, or UserProvider / UserManagementAccessor usage in Java source files.

What it produces:

  • Modified web.xml with XSUAA auth configuration

  • New xs-security.json with scope and role template definitions

  • Updated pom.xml with the security library dependency

What to review after running it:

  • The generated xs-security.json defines a default scope and role template based on the existing security-constraint entries in web.xml. Review these against your application's actual authorization requirements — additional scopes or role collections may be needed.

  • On Neo environment, the Everyone role is implicitly granted to all authenticated users. This automatic assignment does not exist on Cloud Foundry runtime. Any functionality that relied on implicit access must be covered by an explicit role collection in xs-security.json.

Skill 4: mta-descriptor

What it does: The mta-descriptor skill always runs last. It generates the mtad.yaml file — the MTA deployment descriptor that ties the entire migration together for Cloud Foundry runtime deployment.

The descriptor declares:

  • The Java application module and its buildpack

  • The Application Router module (if approuter-setup was run)

  • All Cloud Foundry command line interface (CLI) services that need to be created and bound — XSUAA, Destination, Connectivity, SAP HANA Cloud, SAP Credential Store, and others — based on which skills have been applied

  • Environment variables, memory settings, and routing configuration for each module

What it detects: This skill reads the output of all previously applied skills to determine which services to declare. It should only be invoked after all other Track 1 skills have completed.

What it produces:

  • mtad.yaml — the complete MTA deployment descriptor ready for cf deploy

What to review after running it:

  • Memory and disk quota values are set to reasonable defaults. Adjust them if your application has specific resource requirements.

  • Route definitions are generated based on the application name. If you need a custom domain or specific route patterns, update the routes section manually.

  • Review all service plan names against what is actually available in your Cloud Foundry CLI space — plan availability depends on your SAP BTP entitlements.

Running the Migration

With the plugin installed and the sample application open in Claude Code, the full skill chain for this lesson can be triggered with a single orchestrator prompt:

Use the neo-to-cf-migration-orchestrator skill to analyze and migrate this Neo environment Java application.

The orchestrator will:

  • Analyze the project structure and detect which skills apply

  • Execute skills in the correct dependency order

  • Pause at each step for your review before proceeding

  • Generate the final mtad.yaml once all transformations are complete

Alternatively, invoke the four highlighted skills individually in sequence:

  1. Use the jakarta-java25-migration skill to upgrade this project to Java 25 and Jakarta EE 10

  2. Use the approuter-setup skill to create the Application Router

  3. Use the authentication-xsuaa skill to set up XSUAA authentication

  4. Use the mta-descriptor skill to generate the deployment descriptor

Note

For GitHub Copilot and Cursor users: Automatic skill chaining is not available in these tools. Invoke each skill manually in the order shown above and verify the output of each step before proceeding to the next.

Summary

Four skills are highlighted in this lesson:

  • jakarta-java25-migration: Namespace and Java version upgrade.
  • approuter-setup: Application Router for browser-facing applications.
  • authentication-xsuaa: SAP Authorization and Trust Management service integration and xs-security.json.
  • mta-descriptor: Final mtad.yaml generation.

Each skill produces specific artifacts and has specific areas that require human review — AI-generated output is a starting point, not a finished product.

The remaining Track 1 skills are summarized in Lesson 1.2 and documented in full in the ai-migration/README.md file in the migration repository.

In Claude Code, the neo-to-cf-migration-orchestrator automates the full skill chain. In GitHub Copilot and Cursor, skills must be invoked manually in dependency order.