1. Scope & Audience

Applies to every cartridge. Ignore generated/build output (bin/, build/, target/). Focus only on source (src/main/**, staticfiles/**, legacy resources) and Gradle build scripts.

2. Target Post-Migration Structure (per cartridge)

<cartridge>/
  build.gradle.kts
  staticfiles/cartridge/configdef/
  src/main/java/...
  src/main/isml/<cartridge>/...
  src/main/resources/cartridges/...
  src/main/resources/resources/<cartridge>/
    components
    config
    dbinit.properties
    edl (ALL *.edl flattened here – no subfolders)
    extensions
    localizations
    pagelets
    pipeline (pipelets.resource + pipelets/*.xml)
    pipelines (legacy only if still referenced)
    queries
    static
    webforms

Avoid alternative layouts like src/main/resources/edl/<cartridge> or src/main/resources/<cartridge>/resources.

3. High-Level Migration Sequence

1. Convert build.gradle → build.gradle.kts.
2. Replace dependency configurations & perform Jakarta namespace replacement.
3. Move resources (staticfiles, EDL, queries, ISML, dbinit, pipelet descriptors)
4. The resources staticfiles/cartridge/configdef/* should not be moved
5. Move all *.properties files from staticfiles/share/system/config/cartridges/ to src/main/resources/cartridges/
6. Adjust Java imports javax.* → jakarta.* (except javax.annotation.processing).
7. Add required annotation processors and supplemental Jakarta dependencies.
8. Remove obsolete files & legacy folders.

4. Build Script Migration Essentials

Plugins mapping:

Dependencies rule of thumb:

Add/replace Jakarta variants per mapping (javax.* → jakarta.*) and exclude transitive slf4j-api where swagger pulls 2.x.

Some dependencies have to be renamed.

Do not duplicate with both cartridge and cartridgeRuntime for the same coordinate.

Move displayname inside of section intershop to description on top-level below plugins.

5. Resource & Asset Migration Highlights

Move from staticfiles/cartridge/... into src/main/resources/resources/<cartridge>/... and ISML to src/main/isml/<cartridge>/....
Flatten all .edl files into .../edl (no subfolders). Remove non-empty legacy directories.

6. Pipelets

Ensure two artifacts:

1. pipeline/pipelets.resource
2. pipeline/pipelets/*.xml
   Missing mappings cause runtime errors. Rebuild after adding.

7. Jakarta Migration Reminders

Regex safe replace for imports:

find: ^import javax\.(?!annotation\.processing)(.*);
replace: import jakarta.$1;

Do not touch javax.annotation.processing.

8. New Edge Cases & Resolutions

9. REST Components Naming Change

Modern platform instances use the intershop.WebShop.RESTAPI.* naming. Any legacy component fulfill referencing intershop.B2CWebShop.* or intershop.B2BWebShop.* must be updated.

Additionally some other renamings have to be done in *.component files:

Also check all *.java files if the following pattern is used @Named("intershop.WebShop.RESTAPI.*"). This has to be adapted accordingly.

10. Change Registration of cartridges to application-specific cartridge lists

In case a cartridge contains files app-extension.component or apps-extension.component the content of this file must be splitted up and moved to different apps.component files in different as_ cartridges.
The location for the apps.component is src/main/resources/resources/<cartridge>/components.

All lines of app-extension.component or apps-extension.component containing <fulfill requirement="selectedCartridge" have to be moved. The used cartridge-list (see table) determines to which cartridge the line has to be moved.
Before a line can be moved it has to be checked if there's is already a cartridge with the cartridge prefix from table. If the cartridge does not exist it must be created.
Its name is the prefix from the table cartridge prefix concatenated with a project name which the user of this script should enter.
When a line is moved, the cartridge must be added as runtime dependency in the build.gradle.kts of the as_ cartridge.

11. Dependency Configuration Clarification

12. Cleanup Checklist

• Delete obsolete *.version files in root directory
• Delete legacy build.gradle
• Delete staticfiles/cartridge/* except configdef
• Delete all app-extension.component and apps-extension.component files that do not contain any fulfill statements anymore
• Remove staticfiles/preparedStuff component duplicates post-validation.
• Remove unused empty legacy resource dirs (after verifying classpath).
• Ensure no stray javax. imports (except processing).