Background Work on Android: The Problem WorkManager Solves
Android aggressively kills background processes to preserve battery. Services get stopped. AlarmManager jobs get deferred. JobScheduler requires API 21+ and still doesn't survive app force-stops. Every year, new OS restrictions tighten the screws further.
WorkManager is Google's unified solution for deferrable, guaranteed background work. "Guaranteed" means the work will execute even if the user force-stops the app or reboots the device. "Deferrable" means you don't control the exact execution time -- the system batches work for efficiency. This makes WorkManager ideal for syncing data, uploading files, sending analytics, cleaning caches, and any other background task where eventual completion matters more than immediate execution.
WorkManager uses JobScheduler on API 23+, and a combination of AlarmManager and BroadcastReceiver on older devices. You don't manage this -- it's abstracted behind a single, consistent API.
Defining Workers: OneTime and Periodic
A `Worker` subclass defines the actual work. The `doWork()` method runs on a background thread and returns a `Result` indicating success, failure, or retry. For coroutine-based code, use `CoroutineWorker` instead, which provides a `suspend` function as described in the getting started guide.
OneTimeWorkRequests execute once. PeriodicWorkRequests repeat at a minimum interval of 15 minutes (OS-enforced). Both support constraints, tags, input data, and backoff policies.
kotlin
// Coroutine-based worker for syncing articles
class ArticleSyncWorker(
appContext: Context,
params: WorkerParameters,
private val articleRepo: ArticleRepository // Injected via Hilt
) : CoroutineWorker(appContext, params) {
override suspend fun doWork(): Result {
// Read input data
val forceRefresh = inputData.getBoolean("force_refresh", false)
return try {
val syncCount = articleRepo.syncWithRemote(forceRefresh)
// Pass result data to the next worker in the chain
val output = workDataOf(
"sync_count" to syncCount,
"synced_at" to System.currentTimeMillis()
)
Result.success(output)
} catch (e: HttpException) {
if (e.code() in 500..599) {
// Server error: retry with exponential backoff
Result.retry()
} else {
// Client error (4xx): don't retry
Result.failure(workDataOf("error" to e.message))
}
} catch (e: IOException) {
// Network error: retry
Result.retry()
}
}
override suspend fun getForegroundInfo(): ForegroundInfo {
return ForegroundInfo(
NOTIFICATION_ID,
createNotification("Syncing articles...")
)
}
}
// Hilt integration: custom WorkerFactory
@HiltWorker
class ArticleSyncWorker @AssistedInject constructor(
@Assisted appContext: Context,
@Assisted params: WorkerParameters,
private val articleRepo: ArticleRepository
) : CoroutineWorker(appContext, params)Constraints: Running Work at the Right Time
Constraints let you specify conditions that must be met before work executes. Need Wi-Fi for a large upload? Require charging for a database compaction? Only run when the device has sufficient storage? Constraints handle all of this declaratively.
The system checks constraints before starting work and cancels in-progress work if constraints are no longer met. Your worker can check `isStopped` periodically to stop gracefully.
kotlin
// Constraints: only sync on Wi-Fi while charging with sufficient battery
val syncConstraints = Constraints.Builder()
.setRequiredNetworkType(NetworkType.UNMETERED) // Wi-Fi only
.setRequiresCharging(true) // Plugged in
.setRequiresBatteryNotLow(true) // Battery > 15%
.setRequiresStorageNotLow(true) // Storage available
.build()
// One-time sync with constraints and backoff
val syncRequest = OneTimeWorkRequestBuilder<ArticleSyncWorker>()
.setConstraints(syncConstraints)
.setBackoffCriteria(
BackoffPolicy.EXPONENTIAL,
30, TimeUnit.SECONDS // 30s, 60s, 120s, 240s...
)
.setInputData(workDataOf("force_refresh" to true))
.addTag("article_sync")
.build()
WorkManager.getInstance(context).enqueueUniqueWork(
"article_sync", // Unique name
ExistingWorkPolicy.KEEP, // Don't restart if already running
syncRequest
)
// Periodic sync: every 6 hours on any network
val periodicSync = PeriodicWorkRequestBuilder<ArticleSyncWorker>(
repeatInterval = 6, TimeUnit.HOURS,
flexInterval = 30, TimeUnit.MINUTES // Can run 30min early
).setConstraints(
Constraints.Builder()
.setRequiredNetworkType(NetworkType.CONNECTED)
.build()
).addTag("periodic_sync")
.build()
WorkManager.getInstance(context).enqueueUniquePeriodicWork(
"periodic_article_sync",
ExistingPeriodicWorkPolicy.UPDATE, // Update existing schedule
periodicSync
)Chaining Work: Complex Pipelines
WorkManager supports chaining multiple workers into sequential or parallel pipelines. The output of one worker becomes the input of the next. If any worker in the chain fails, the entire chain is marked as failed.
A common pattern is download → process → upload. Another is parallel fetch (multiple API endpoints) → merge → notify. Chains are built with `beginWith()` and `then()`, and parallel work uses lists of requests.
kotlin
// Chain: Download images → Compress → Upload → Notify
val downloadWork = OneTimeWorkRequestBuilder<DownloadImagesWorker>()
.setConstraints(networkConstraints)
.addTag("image_pipeline")
.build()
val compressWork = OneTimeWorkRequestBuilder<CompressImagesWorker>()
.addTag("image_pipeline")
.build()
val uploadWork = OneTimeWorkRequestBuilder<UploadImagesWorker>()
.setConstraints(networkConstraints)
.addTag("image_pipeline")
.build()
val notifyWork = OneTimeWorkRequestBuilder<NotifyCompletionWorker>()
.build()
WorkManager.getInstance(context)
.beginWith(downloadWork) // Step 1
.then(compressWork) // Step 2 (gets output from step 1)
.then(uploadWork) // Step 3
.then(notifyWork) // Step 4
.enqueue()
// Parallel work: fetch from multiple APIs, then merge
val fetchUsers = OneTimeWorkRequestBuilder<FetchUsersWorker>().build()
val fetchPosts = OneTimeWorkRequestBuilder<FetchPostsWorker>().build()
val fetchComments = OneTimeWorkRequestBuilder<FetchCommentsWorker>().build()
val mergeResults = OneTimeWorkRequestBuilder<MergeDataWorker>().build()
WorkManager.getInstance(context)
.beginWith(listOf(fetchUsers, fetchPosts, fetchComments)) // Parallel
.then(mergeResults) // Merge
.enqueue()Observing Work Progress in Compose
WorkManager provides `WorkInfo` objects that you can observe reactively in your UI. This lets you build progress indicators, success/failure feedback, and cancel buttons tied to background operations.
The `getWorkInfoByIdFlow()` and `getWorkInfosByTagFlow()` methods return Kotlin Flows that integrate naturally with Compose's `collectAsStateWithLifecycle()`.
kotlin
@HiltViewModel
class SyncViewModel @Inject constructor(
private val workManager: WorkManager
) : ViewModel() {
// Observe all sync workers by tag
val syncState: Flow<SyncUiState> = workManager
.getWorkInfosByTagFlow("article_sync")
.map { workInfos ->
val latest = workInfos.lastOrNull()
when (latest?.state) {
WorkInfo.State.RUNNING -> SyncUiState.Syncing(
progress = latest.progress.getInt("progress", 0)
)
WorkInfo.State.SUCCEEDED -> SyncUiState.Success(
count = latest.outputData.getInt("sync_count", 0)
)
WorkInfo.State.FAILED -> SyncUiState.Error(
message = latest.outputData.getString("error") ?: "Sync failed"
)
WorkInfo.State.ENQUEUED -> SyncUiState.Waiting
else -> SyncUiState.Idle
}
}
fun startSync() {
val request = OneTimeWorkRequestBuilder<ArticleSyncWorker>()
.addTag("article_sync")
.build()
workManager.enqueueUniqueWork(
"manual_sync",
ExistingWorkPolicy.KEEP,
request
)
}
fun cancelSync() {
workManager.cancelUniqueWork("manual_sync")
}
}
sealed interface SyncUiState {
data object Idle : SyncUiState
data object Waiting : SyncUiState
data class Syncing(val progress: Int) : SyncUiState
data class Success(val count: Int) : SyncUiState
data class Error(val message: String) : SyncUiState
}
@Composable
fun SyncButton(viewModel: SyncViewModel = hiltViewModel()) {
val state by viewModel.syncState
.collectAsStateWithLifecycle(SyncUiState.Idle)
when (state) {
is SyncUiState.Syncing -> {
LinearProgressIndicator(
progress = { (state as SyncUiState.Syncing).progress / 100f }
)
}
is SyncUiState.Error -> {
Button(onClick = { viewModel.startSync() }) {
Text("Retry Sync")
}
}
else -> {
Button(onClick = { viewModel.startSync() }) {
Text("Sync Now")
}
}
}
}Key Takeaways
- 1WorkManager guarantees execution even across app restarts and device reboots -- it is the only correct choice for deferrable background work on modern Android.
- 2Use CoroutineWorker for suspend-function-based work, and return Result.retry() with exponential backoff for transient failures.
- 3Constraints (network, charging, battery, storage) let you declaratively schedule work for optimal conditions without manual checks.
- 4Work chains enable sequential and parallel pipelines where output data flows between workers automatically.
- 5Observe WorkInfo flows in Compose to build reactive progress UIs that reflect background work state in real time.
- 6PeriodicWorkRequests have a minimum interval of 15 minutes and support flex windows for battery-efficient scheduling.
Frequently Asked
WorkManager vs JobScheduler vs AlarmManager?
Use WorkManager for most background work. It uses JobScheduler on API 23+ and falls back to AlarmManager + BroadcastReceiver on older devices. Only use JobScheduler directly for system-level integration.
Why isn't my work running immediately?
WorkManager is not for immediate or foreground work. It's optimized for deferrable, guaranteed execution. Use foreground service for immediate work. WorkManager may delay based on constraints and system state.
Ready to architect your next Android app?
ANDROID-ARCHITECT generates production-ready Kotlin code, architecture blueprints, and CI/CD configurations from plain-language descriptions. Start building for free.
ANDROID-ARCHITECT · CONSOLE
S/N · AX-1A-00001
STRATEGIA-X · ENGINEERED · IN · CALIFORNIA