Background processing in Android has grown increasingly complex as the platform has evolved. Battery optimization restrictions, Doze mode, app standby buckets, and background execution limits all constrain what applications can do when not in the foreground. WorkManager provides a unified API for deferrable, guaranteed background work that respects these constraints while ensuring tasks complete reliably.
This guide covers WorkManager from basic task scheduling through advanced patterns for complex background processing requirements.
Understanding WorkManager’s Role
WorkManager is designed for work that needs guaranteed execution—tasks that must complete eventually, even if the app exits or the device restarts. Syncing data with servers, processing images, backing up user data, and sending analytics are ideal candidates.
WorkManager is not for work that must happen immediately or work tied to specific user actions. For immediate work, use Kotlin coroutines or threads directly. For exact timing, use AlarmManager with appropriate permissions. For foreground processing with user visibility, use Foreground Services.
Under the hood, WorkManager chooses the best execution mechanism based on API level—JobScheduler on API 23+, a combination of AlarmManager and BroadcastReceivers on older versions. This abstraction shields developers from platform differences while leveraging the most efficient approach available.
Creating Basic Workers
Workers encapsulate the actual work to be performed. Extend Worker for synchronous work or CoroutineWorker for suspend function support.
class DataSyncWorker(
appContext: Context,
workerParams: WorkerParameters
) : CoroutineWorker(appContext, workerParams) {
override suspend fun doWork(): Result {
return try {
val syncService = SyncService.getInstance(applicationContext)
syncService.syncAllData()
Result.success()
} catch (e: IOException) {
// Network error - retry
if (runAttemptCount < 3) {
Result.retry()
} else {
Result.failure()
}
} catch (e: Exception) {
// Other error - fail
Result.failure(
workDataOf("error" to e.message)
)
}
}
}Workers return Result.success() when work completes successfully, Result.retry() to request rescheduling, or Result.failure() when work cannot complete. Failed work can include output data describing the failure.
Configuring Work Requests
WorkRequest objects define how and when work should execute. OneTimeWorkRequest runs once. PeriodicWorkRequest runs repeatedly at specified intervals.
// Simple one-time work
val syncWork = OneTimeWorkRequestBuilder<DataSyncWorker>()
.build()
WorkManager.getInstance(context).enqueue(syncWork)
// Work with constraints
val constrainedWork = OneTimeWorkRequestBuilder<DataSyncWorker>()
.setConstraints(
Constraints.Builder()
.setRequiredNetworkType(NetworkType.CONNECTED)
.setRequiresBatteryNotLow(true)
.build()
)
.build()
// Work with input data
val uploadWork = OneTimeWorkRequestBuilder<UploadWorker>()
.setInputData(
workDataOf(
"file_path" to filePath,
"upload_url" to uploadUrl
)
)
.build()
// Work with backoff policy
val retryableWork = OneTimeWorkRequestBuilder<DataSyncWorker>()
.setBackoffCriteria(
BackoffPolicy.EXPONENTIAL,
Duration.ofMinutes(1)
)
.build()
// Work with initial delay
val delayedWork = OneTimeWorkRequestBuilder<ReminderWorker>()
.setInitialDelay(Duration.ofHours(24))
.build()Periodic Work
PeriodicWorkRequest schedules recurring work with a minimum interval of 15 minutes. The system may delay execution to batch work with other apps for battery efficiency.
val periodicSync = PeriodicWorkRequestBuilder<DataSyncWorker>(
repeatInterval = Duration.ofHours(6),
flexInterval = Duration.ofHours(1)
)
.setConstraints(
Constraints.Builder()
.setRequiredNetworkType(NetworkType.UNMETERED)
.setRequiresCharging(true)
.build()
)
.build()
// Enqueue uniquely to avoid duplicates
WorkManager.getInstance(context).enqueueUniquePeriodicWork(
"periodic_sync",
ExistingPeriodicWorkPolicy.KEEP,
periodicSync
)The flex interval defines a window at the end of each period during which work can execute. This flexibility allows the system to batch work efficiently while still meeting your timing requirements.
Work Chains
Complex workflows often require sequential or parallel task execution. WorkManager supports chaining work requests into workflows.
// Sequential chain
WorkManager.getInstance(context)
.beginWith(downloadWork)
.then(processWork)
.then(uploadWork)
.enqueue()
// Parallel work followed by sequential
val parallelDownloads = listOf(
OneTimeWorkRequestBuilder<DownloadWorker>()
.setInputData(workDataOf("url" to url1))
.build(),
OneTimeWorkRequestBuilder<DownloadWorker>()
.setInputData(workDataOf("url" to url2))
.build()
)
WorkManager.getInstance(context)
.beginWith(parallelDownloads) // Run in parallel
.then(mergeWork) // Then merge results
.then(uploadWork) // Then upload
.enqueue()
// Unique work chains
WorkManager.getInstance(context)
.beginUniqueWork(
"import_workflow",
ExistingWorkPolicy.REPLACE,
downloadWork
)
.then(processWork)
.enqueue()Output data from one worker flows as input to the next in chains. Use InputMerger to combine outputs from parallel workers.
Observing Work Status
WorkManager provides LiveData and Flow APIs to observe work progress and status.
// Observe by ID
val workInfo = WorkManager.getInstance(context)
.getWorkInfoByIdLiveData(workRequest.id)
workInfo.observe(lifecycleOwner) { info ->
when (info?.state) {
WorkInfo.State.SUCCEEDED -> handleSuccess(info.outputData)
WorkInfo.State.FAILED -> handleFailure(info.outputData)
WorkInfo.State.RUNNING -> updateProgress(info.progress)
WorkInfo.State.ENQUEUED, WorkInfo.State.BLOCKED -> showPending()
WorkInfo.State.CANCELLED -> handleCancellation()
else -> { }
}
}
// Observe by unique name
WorkManager.getInstance(context)
.getWorkInfosForUniqueWorkLiveData("sync_work")
.observe(lifecycleOwner) { workInfos ->
// Handle list of work infos
}
// Flow API for Compose
@Composable
fun SyncStatus(workName: String) {
val workInfo by WorkManager.getInstance(LocalContext.current)
.getWorkInfosForUniqueWorkFlow(workName)
.collectAsStateWithLifecycle(initialValue = emptyList())
val isRunning = workInfo.any { it.state == WorkInfo.State.RUNNING }
if (isRunning) {
CircularProgressIndicator()
}
}Progress Reporting
Long-running workers can report intermediate progress for UI updates.
class UploadWorker(
appContext: Context,
workerParams: WorkerParameters
) : CoroutineWorker(appContext, workerParams) {
override suspend fun doWork(): Result {
val files = inputData.getStringArray("files") ?: return Result.failure()
files.forEachIndexed { index, filePath ->
uploadFile(filePath)
// Report progress
setProgress(
workDataOf(
"current" to index + 1,
"total" to files.size
)
)
}
return Result.success()
}
}Expedited Work
For time-sensitive work that should start immediately and complete quickly, use expedited work. Expedited work runs with higher priority but must complete within a few minutes.
val expeditedWork = OneTimeWorkRequestBuilder<UrgentSyncWorker>()
.setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
.build()
// Worker must implement getForegroundInfo for expedited work
class UrgentSyncWorker(
appContext: Context,
workerParams: WorkerParameters
) : CoroutineWorker(appContext, workerParams) {
override suspend fun getForegroundInfo(): ForegroundInfo {
return ForegroundInfo(
NOTIFICATION_ID,
createNotification("Syncing...")
)
}
override suspend fun doWork(): Result {
// Urgent work here
return Result.success()
}
}Long-Running Work
Work that may take longer than ten minutes should run as a foreground service to avoid being terminated by the system.
class LongUploadWorker(
appContext: Context,
workerParams: WorkerParameters
) : CoroutineWorker(appContext, workerParams) {
override suspend fun doWork(): Result {
// Promote to foreground service
setForeground(getForegroundInfo())
// Long-running work
val files = getFilesToUpload()
files.forEachIndexed { index, file ->
uploadLargeFile(file)
// Update notification with progress
setForeground(
ForegroundInfo(
NOTIFICATION_ID,
createProgressNotification(index + 1, files.size)
)
)
}
return Result.success()
}
override suspend fun getForegroundInfo(): ForegroundInfo {
return ForegroundInfo(
NOTIFICATION_ID,
createNotification("Uploading files..."),
ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC
)
}
private fun createProgressNotification(current: Int, total: Int): Notification {
return NotificationCompat.Builder(applicationContext, CHANNEL_ID)
.setContentTitle("Uploading")
.setContentText("File $current of $total")
.setProgress(total, current, false)
.setSmallIcon(R.drawable.ic_upload)
.setOngoing(true)
.build()
}
}Testing Workers
WorkManager provides testing utilities for verifying worker behavior without executing in a real WorkManager context.
@RunWith(AndroidJUnit4::class)
class DataSyncWorkerTest {
private lateinit var context: Context
@Before
fun setup() {
context = ApplicationProvider.getApplicationContext()
}
@Test
fun `doWork returns success when sync completes`() = runTest {
// Arrange
val worker = TestListenableWorkerBuilder<DataSyncWorker>(context)
.setInputData(workDataOf("user_id" to "123"))
.build()
// Act
val result = worker.doWork()
// Assert
assertEquals(Result.success(), result)
}
@Test
fun `doWork returns retry on network error`() = runTest {
// Setup mock to throw network error
val worker = TestListenableWorkerBuilder<DataSyncWorker>(context)
.setRunAttemptCount(1)
.build()
val result = worker.doWork()
assertEquals(Result.retry(), result)
}
}
// Integration testing with WorkManagerTestInitHelper
@RunWith(AndroidJUnit4::class)
class WorkflowIntegrationTest {
@Before
fun setup() {
val config = Configuration.Builder()
.setMinimumLoggingLevel(Log.DEBUG)
.setExecutor(SynchronousExecutor())
.build()
WorkManagerTestInitHelper.initializeTestWorkManager(context, config)
}
@Test
fun `work chain completes in order`() {
val workManager = WorkManager.getInstance(context)
val testDriver = WorkManagerTestInitHelper.getTestDriver(context)!!
val work1 = OneTimeWorkRequestBuilder<FirstWorker>().build()
val work2 = OneTimeWorkRequestBuilder<SecondWorker>().build()
workManager.beginWith(work1).then(work2).enqueue()
// Drive constraints
testDriver.setAllConstraintsMet(work1.id)
val workInfo = workManager.getWorkInfoById(work2.id).get()
assertEquals(WorkInfo.State.SUCCEEDED, workInfo.state)
}
}Conclusion
WorkManager handles the complexity of guaranteed background execution across Android versions and device states. Its constraint system ensures work runs under appropriate conditions. Chaining enables complex workflows. Observation APIs provide visibility into work status.
At RyuPy, WorkManager is our standard solution for background processing. It reliably handles data synchronization, backup operations, and deferred processing while respecting system constraints and user battery life.
0 Comments