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 theBOMnow supplies for transitive libraries match your expectations. - Clean build: Run
./gradlew clean assembleDebugto confirm the project still builds after removing the hard-coded versions. - Component publishers: Run
./gradlew publishToMavenLocaland inspect the generatedbuild/publications/release/pom-default.xml(or thePOMfile in your local Maven cache) to confirm the<dependencyManagement>entries carry concrete versions rather than versionless ones.