Skip to content

Migrating an Existing Project to the SDK BOM

Starting with SAP BTP SDK for Android 26.11.0, the SDK publishes com.sap.cloud.android:bom — a Gradle Java Platform that centralizes the version constraints for the third-party libraries that the SAP Android SDK components (foundation, flows, fiori, odata, and so on) depend on, including AndroidX, OkHttp, Ktor, Kotlin-Coroutines, Compose, and more. Importing this BOM aligns all transitive versions to the set the SDK was tested against. This eliminates the need to pin these versions manually and prevents the silent "highest version wins" conflicts Gradle resolves when multiple components have version discrepancies.

This guide describes how to retrofit the BOM into an existing project. If you are starting a new project, see Creating Apps From Scratch, which already includes these steps.

This is optional for consuming apps

If you only use the SDK, you do not need to migrate. Each SDK component imports the BOM as an api dependency, so its version constraints already propagate to your app through Gradle Module Metadata. Consuming the SDK is enough to keep transitive versions aligned. Follow the steps below only if you want to apply the same alignment to third-party libraries declared directly, without manually pinning their versions. SAP teams publishing SDK components should follow Publishing an SDK Component with the BOM, which establishes the propagation setup.

Availability

The com.sap.cloud.android:bom is published beginning with SAP BTP SDK for Android 26.11.0. If your project targets an earlier SDK version, this artifact is not available and migration is not possible. You must upgrade to 26.11.0 or later first.

Choosing Your Repository

The repository from which you consume the BOM depends on your role:

Audience Repository Base URL
App developers consuming the SDK SAP Cloud Shipment channel https://73555000100800001281.mavensrv.cdn.repositories.cloud.sap
(China: https://73555000100800001281.val.mavensrv.repositories.sapcloud.cn)
SAP SDK component teams publishing components Internal Artifactory https://int.repositories.cloud.sap/artifactory/build-releases/

The Cloud Shipment channel requires technical-user credentials — see Creating the Required Credentials.

Step 1: Declare the BOM in gradle/libs.versions.toml

Add a sap-cloud-bom entry that reuses your existing SDK version reference:

[versions]
sapSdkVersion = "26.11.0" # or later

[libraries]
sap-cloud-bom        = { group = "com.sap.cloud.android", name = "bom",        version.ref = "sapSdkVersion" }
sap-cloud-foundation = { group = "com.sap.cloud.android", name = "foundation", version.ref = "sapSdkVersion" }
# ... your other SAP SDK library entries

Step 2: Import the BOM in app/build.gradle.kts

Add the BOM as a platform dependency, ideally as the first entry in the dependencies block so it governs everything below it:

dependencies {
    implementation(platform(libs.sap.cloud.bom))
    implementation(libs.sap.cloud.foundation)
    // ... your other SAP SDK dependencies
}

Step 3: Remove Now-Redundant Transitive Versions

After you import the BOM, any dependency whose version it constrains no longer needs an explicit version. The BOM provides it. Remove the version strings and let the BOM resolve them. See Verification to inspect the versions the BOM resolves.

dependencies {
    implementation(platform(libs.sap.cloud.bom))

    // Before: versions pinned by hand
    // implementation("com.squareup.okhttp3:okhttp:4.12.0")
    // implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.7")

    // After: versions resolved by the BOM
    implementation("com.squareup.okhttp3:okhttp")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
}

Tip

Keep explicit versions only for libraries not covered by the BOM. Run ./gradlew :app:dependencies (see Verification) to see which versions the BOM is resolving.

What Happens If You Keep the Explicit Versions

Removing the version strings is recommended but not strictly required — leaving them in place does not break the build. Understanding why they should be removed is important. An outdated version may be unnecessary or could silently override the intended versions.

When you import a BOM through platform(...), Gradle does not treat it as a set of defaults the way Maven treats <dependencyManagement>. Instead, the BOM adds dependency constraints, with an explicit version on a direct dependency serving as a required version. Both the constraint and the required version participate in Gradle's conflict resolution, and by default the highest version wins. That can lead to three outcomes:

Explicit version retained BOM-constrained version Gradle's resolve version Consequence
Equal to the BOM version e.g. 2.11.0 The same version Redundant — the pin does nothing but must now be maintained by hand. When the BOM bumps the version, this line silently disagrees with it.
Lower than the BOM version e.g. 2.11.0 The BOM version (2.11.0) Your pin looks authoritative but is ignored. The next reader cannot tell from the build script which version actually ships.
Higher than the BOM version e.g. 2.11.0 Your version You override the BOM with a version the SDK was not tested against, reintroducing exactly the "highest version wins" divergence the BOM exists to prevent.

For example, with the BOM constraining androidx.lifecycle:lifecycle-runtime-ktx to 2.11.0:

dependencies {
    implementation(platform(libs.sap.cloud.bom))

    // Resolves to 2.11.0 (the BOM wins) — the 2.8.7 pin is silently ineffective
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.7")

    // Resolves to 2.12.0 (your pin wins) — overrides the tested-against version
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.12.0")
}

Intentionally overriding the BOM

If you need a version that differs from the one the BOM constrains, do not use a plain version string — as shown above, a lower value is ignored and a higher value wins silently. Declare a strict version instead. This makes the intent explicit and forces Gradle to fail the build (rather than resolve quietly) if the requested version is incompatible with another constraint:

dependencies {
    implementation(platform(libs.sap.cloud.bom))

    implementation("androidx.lifecycle:lifecycle-runtime-ktx") {
        version {
            strictly("2.8.7")
        }
    }
}

Use this approach as an escape hatch for a specific, well-understood situation (for example, a regression in the BOM-supplied version). Strive to align with the BOM whenever possible, so your app keeps running the exact set of versions the SDK was tested against.

Publishing an SDK Component with the BOM

This section applies to SAP teams publishing SDK components (for example a new foundation-style module). Consuming apps can skip this section.

Import the BOM as an api Dependency

Published component must import the BOM using the api configuration rather than implementation:

dependencies {
    api(platform(libs.sap.cloud.bom))   // propagates to consumers
    // not: implementation(platform(libs.sap.cloud.bom))

    implementation("androidx.lifecycle:lifecycle-runtime-ktx") // version resolved by the BOM
}

Using implementation restricts the platform constraints to the component's own build only — they do not reach the apps that consume the component, resulting in unaligned transitive versions for those apps. Instead, use api(platform(...)) to publish the constraints into the component's Gradle Module Metadata, which is exactly what lets consuming apps skip importing the BOM themselves. Emit the Gradle Module Metadata file (<artifact>-<version>.module) alongside the POM — the maven-publish handles this by default, so do not disable the GenerateModuleMetadata task.

Back-Fill Versionless POM Entries

When a component imports com.sap.cloud.android:bom via platform(), Gradle resolves dependency versions at build time but does not write them as explicit version strings into the published POM file. Those dependencies appear as versionless <dependency> entries in the published <dependencyManagement> section, which breaks consumers that resolve dependencies from the POM file.

To fix this, add the following withXml block inside publishing > publications > release(MavenPublication) > pom in the component's build.gradle:

withXml {
    def compileClasspath = project.configurations.findByName('releaseCompileClasspath')
    def runtimeClasspath = project.configurations.findByName('releaseRuntimeClasspath')
    def resolveVersion = { group, artifact ->
        [compileClasspath, runtimeClasspath].findResult { cp ->
            cp?.resolvedConfiguration
                ?.lenientConfiguration
                ?.allModuleDependencies
                ?.find { it.moduleGroup == group && it.moduleName == artifact }
                ?.moduleVersion
        }
    }
    def backfill = { section ->
        section?.dependency?.each { dep ->
            if (!dep.version.text()) {
                def resolved = resolveVersion(dep.groupId.text(), dep.artifactId.text())
                if (resolved) {
                    if (dep.version) { // If version is empty
                        dep.version[0].value = resolved
                    } else {
                        dep.appendNode('version', resolved)
                    }
                }
            }
        }
    }
    backfill(asNode().dependencyManagement?.dependencies)
}

This process accesses the <dependencyManagement> block at publication time, checks each versionless entry against the resolved compile and runtime classpath, and back-fills the concrete version.

Note

The backfill deliberately runs on dependencyManagement only; the regular dependencies section remains versionless. Consumers of a BOM-adopting component are expected to import com.sap.cloud.android:bom themselves, which supplies those transitive versions. Backfilling them here would pin fixed versions that override the consumer's BOM.

Verification

  • Inspect resolved versions: Run ./gradlew :app:dependencies (or :app:dependencies --configuration releaseRuntimeClasspath) and confirm the versions the BOM now supplies for transitive libraries match your expectations.
  • Clean build: Run ./gradlew clean assembleDebug to confirm the project still builds after removing the hard-coded versions.
  • Component publishers: Run ./gradlew publishToMavenLocal and inspect the generated build/publications/release/pom-default.xml (or the POM file in your local Maven cache) to confirm the <dependencyManagement> entries carry concrete versions rather than versionless ones.

Last update: October 8, 2026