WorkManager — what it is, API and task scheduling

How does WorkManager work?

Architecture of WorkManager is built around three base classes: Worker, WorkRequest, and WorkManager. Worker contains the task logic, WorkRequest describes execution parameters, and WorkManager manages the queue and scheduling. The library uses an internal Room database to store the state of all tasks.

Worker and WorkRequest

Worker is an abstract class with a single method doWork that is called on a background thread. The method returns ListenableWorker.Result — SUCCESS, FAILURE, or RETRY. WorkRequest links the Worker with parameters: timeout, tag, initial delay, and constraints.

class SyncWorker(
    context: Context,
    params: WorkerParameters
) : Worker(context, params) {

    override fun doWork(): Result {
        return try {
            val api = RetrofitClient.api
            val response = api.syncData()
            Result.success()
        } catch (e: Exception) {
            Result.retry()
        }
    }
}

Scheduling via WorkManager

WorkManager uniformly schedules tasks regardless of Android version. When enqueue is called, the library saves the task to Room, evaluates current conditions, and selects the optimal execution time. Under the hood, it may use JobScheduler, AlarmManager, or its own scheduler — the developer does not need to worry about it.

val syncRequest = OneTimeWorkRequestBuilder<SyncWorker>()
    .setInitialDelay(15, TimeUnit.MINUTES)
    .addTag("sync")
    .build()

WorkManager.getInstance(context)
    .enqueue(syncRequest)

Types of WorkRequest

WorkManager supports two types of execution requests: one-time and periodic. The choice of type depends on the scenario: the task should run once or repeat at a given interval.

OneTimeWorkRequest

OneTimeWorkRequest is designed for tasks that should execute once. This can be log submission, data synchronization after authorization, configuration download on first launch. Delay is set via setInitialDelay, and constraints via setConstraints.

PeriodicWorkRequest

PeriodicWorkRequest is suitable for repeating tasks with a minimum interval of 15 minutes. The library guarantees that the interval between runs will not be less than specified, but may be longer due to device constraints. For tasks with frequency less than 15 minutes, use Handler or Timer in Foreground Service.

Setting Constraints and Task Chaining

Constraints in WorkManager allow you to set conditions under which a task can be launched: network connectivity (NetworkType), battery level (batteryNotLow), storage state (StorageNotLow), and idle mode (DeviceIdle). The task will not start until all constraints are met.

val constraints = Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresCharging(true)
    .setRequiresBatteryNotLow(true)
    .build()

val request = OneTimeWorkRequestBuilder<ImageUploadWorker>()
    .setConstraints(constraints)
    .build()

Chaining allows you to organize sequential or parallel task execution. beginWith starts a chain, then adds the next Worker that will execute after the successful completion of the previous one. For parallel execution, use workManager.enqueue(listOf(request1, request2)).

WorkManager.getInstance(context)
    .beginWith(compressWorker)
    .then(uploadWorker)
    .then(cleanupWorker)
    .enqueue()
    // compress -> upload -> cleanup sequentially

Migration from JobScheduler to WorkManager

JobScheduler was introduced in Android 5 (API 21) as a system service for scheduling background tasks. WorkManager came to replace it, offering a cross-platform API with automatic migration and additional capabilities: chaining, execution guarantee, tags, state observation via LiveData.

When migrating from JobScheduler to WorkManager, you need to convert JobService to Worker, replace JobInfo with WorkRequest, and Context.getSystemService with WorkManager API. WorkManager automatically handles compatibility issues and handles Doze Mode more correctly than a manual JobScheduler implementation. Migration steps: 1) create a Worker class, 2) build a WorkRequest with the same conditions, 3) remove JobService and JobInfo from code and manifest.

UniqueWork for Unique Tasks

WorkManager supports the concept of unique tasks through ExistingWorkPolicy. If a task with the specified name already exists, the policy determines the behavior: KEEP (do not create a new one), REPLACE (replace the existing one), APPEND (append to the end of the chain), and APPEND_OR_REPLACE. UniqueWorkRequest is convenient for tasks that should not be duplicated: database synchronization, configuration download, analytics batch submission.

WorkManager.getInstance(context)
    .enqueueUniqueWork(
        "sync_data",
        ExistingWorkPolicy.KEEP,
        syncRequest
    )

Progress and Intermediate Results Handling

CoroutineWorker supports the setProgress mechanism, allowing you to pass intermediate execution results. This is useful for long-running operations: large file download, batch image processing, database migration. The UI can subscribe to updates via getWorkInfosByTagLiveData and display real-time progress. The ForegroundInfo method is also available to run a Worker as a Foreground Service with a notification if the task should be visible to the user.

class ProgressWorker(
    context: Context,
    params: WorkerParameters
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        val total = 100
        for (i in 1..total) {
            setProgress(
                workDataOf("progress" to i)
            )
        }
        return Result.success()
    }
}

InputData and OutputData for Data Transfer

WorkManager supports data transfer between Workers via InputData and OutputData. InputData is created during WorkRequest construction via Data.Builder and is passed to the Worker through inputData. After execution, the Worker creates OutputData via workDataOf or Data.Builder and returns it together with Result.success(outputData). The next Worker in the chain receives the outputData of the previous one as its inputData. Data is stored in key-value format with support for basic types: String, Int, Long, Boolean, Double. The maximum Data size is 10 KB.

In practice, many projects use WorkManager as the sole background task scheduler. Google recommends migrating all existing JobService to WorkManager, especially in apps supporting Android 4.4 (API 19) and below, where JobScheduler is unavailable and WorkManager uses a fallback mechanism via AlarmManager and BroadcastReceiver. For testing, WorkManager provides TestListenableWorkerBuilder and TestWorkerBuilder, which allow testing Workers in JUnit tests without a real scheduler.