WorkManager

What WorkManager Does

WorkManager is for work that must run eventually — even if the app exits or the device restarts. It is not for immediate work; use coroutines for that. WorkManager handles:

• Guaranteed execution: work persists and runs when constraints are met
• Backward compatibility: uses JobScheduler on API 23+, AlarmManager + BroadcastReceiver on older APIs
• Observable work: track status, progress, and results

Defining a Worker

class SyncWorker(
    context: Context,
    workerParams: WorkerParameters
) : CoroutineWorker(context, workerParams) {

    override suspend fun doWork(): Result {
        val userId = inputData.getString("userId") ?: return Result.failure()

        return try {
            repository.syncUserData(userId)
            Result.success()
        } catch (e: Exception) {
            Result.retry()
        }
    }
}

CoroutineWorker gives you a suspend context. doWork() returns:

• Result.success() — work completed
• Result.failure() — permanent failure
• Result.retry() — reschedule with backoff

Enqueueing Work

val syncRequest = OneTimeWorkRequestBuilder<SyncWorker>()
    .setInputData(workDataOf("userId" to "user_123"))
    .setConstraints(
        Constraints.Builder()
            .setRequiredNetworkType(NetworkType.CONNECTED)
            .setRequiresBatteryNotLow(true)
            .build()
    )
    .setBackoffCriteria(
        BackoffPolicy.EXPONENTIAL,
        WorkRequest.MIN_BACKOFF_MILLIS,
        TimeUnit.MILLISECONDS
    )
    .build()

WorkManager.getInstance(context).enqueue(syncRequest)

Periodic Work

For recurring tasks like daily sync:

val periodicSync = PeriodicWorkRequestBuilder<DailySyncWorker>(
    1, TimeUnit.HOURS,  // repeat interval
    15, TimeUnit.MINUTES // flex interval
).build()

WorkManager.getInstance(context)
    .enqueueUniquePeriodicWork(
        "daily_sync",
        ExistingPeriodicWorkPolicy.KEEP,
        periodicSync
    )

The flex interval defines when the work can run within the repeat interval. Work runs once during the last 15 minutes of each hour.

Work Chaining

Chain work to run sequentially. Each worker receives the output of the previous one as input:

WorkManager.getInstance(context)
    .beginWith(downloadWork)
    .then(processWork)
    .then(uploadWork)
    .enqueue()

For parallel branches that converge:

val parallelWork = WorkManager.getInstance(context)
    .beginWith(downloadImages)
    .then(downloadVideos)
    .enqueue()

WorkManager.getInstance(context)
    .beginWith(parallelWork)
    .then(mergeWork)
    .enqueue()

Tags

Tag work for bulk operations:

val uploadWork = OneTimeWorkRequestBuilder<UploadWorker>()
    .addTag("upload")
    .addTag("media")
    .build()

// Cancel all work with a tag
WorkManager.getInstance(context).cancelAllWorkByTag("upload")

// Observe all work with a tag
WorkManager.getInstance(context)
    .getWorkInfosByTagLiveData("upload")
    .observe(lifecycleOwner) { workList ->
        val running = workList.any { it.state == WorkInfo.State.RUNNING }
    }

Observing Work Status

WorkManager.getInstance(context)
    .getWorkInfoByIdLiveData(syncRequest.id)
    .observe(lifecycleOwner) { workInfo ->
        when (workInfo?.state) {
            WorkInfo.State.ENQUEUED -> { /* waiting */ }
            WorkInfo.State.RUNNING -> { /* executing */ }
            WorkInfo.State.SUCCEEDED -> {
                val result = workInfo.outputData.getString("result")
            }
            WorkInfo.State.FAILED -> { /* permanent failure */ }
            WorkInfo.State.CANCELLED -> { /* cancelled */ }
            else -> {}
        }
    }

Unique Work

Prevent duplicate work by name:

// Only one sync can run at a time
WorkManager.getInstance(context)
    .enqueueUniqueWork(
        "user_sync",
        ExistingWorkPolicy.REPLACE,  // cancel previous, run new
        syncRequest
    )

// Options: KEEP (skip new), REPLACE (cancel old), APPEND (queue after)

Input and Output Data

Workers communicate through Data objects (key-value pairs limited to primitives):

class ProcessWorker(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) {
    override suspend fun doWork(): Result {
        val inputUrl = inputData.getString("url") ?: return Result.failure()
        val processed = processUrl(inputUrl)
        val outputData = workDataOf("filePath" to processed)
        return Result.success(outputData)
    }
}

Chained workers automatically pass output as input to the next worker.