Job Scheduling in Android

Immediate tasks

For tasks that should be executed immediately and need continued processing, even if the user puts the application in background or the device restarts, WorkManager is recommended since its support for long-running tasks.

Deferred tasks

Every task that is not directly connected to a user interaction and can run at any time in the future can be deferred. The recommended solution for deferred tasks is WorkManager.

Exact tasks

A task that needs to be executed at an exact point in time can use AlarmManager.

  • Periodically syncing application data with a server
class UploadWorker(appContext: Context, workerParams: WorkerParameters):
Worker(appContext, workerParams) {
override fun doWork(): Result {
// Do the work here--in this case, upload the images.
// Indicate whether the work finished successfully with the Result
return Result.success()
val uploadWorkRequest: WorkRequest =
  • Result.failure(): The work failed.
  • Result.retry(): The work failed and should be tried at another time according to its retry policy.

One-time work states

In the ENQUEUED state, your work is eligible to run as soon as its Constraints and initial delay timing requirements are met. From there it moves to a RUNNING state and then depending on the outcome of the work it may move to SUCCEEDED, FAILED, or possibly back to ENQUEUED if the result is retry. At any point in the process, work can be cancelled, at which point it will move to the CANCELLED state.

Periodic work states

val saveRequest =
PeriodicWorkRequestBuilder<SaveImageToFileWorker>(1, TimeUnit.HOURS)
// Additional configuration
val myUploadWork = PeriodicWorkRequestBuilder<SaveImageToFileWorker>(
1, TimeUnit.HOURS, // repeatInterval (the period cycle)
15, TimeUnit.MINUTES) // flexInterval
val constraints = Constraints.Builder().setRequiredNetworkType(NetworkType.UNMETERED).setRequiresCharging(true).setBatteryNotLow(true).setDeviceIdle(true).setStorageNotLow(true).build()val myWorkRequest: WorkRequest =OneTimeWorkRequestBuilder<MyWork>().setConstraints(constraints).setBackoffCriteria(BackoffPolicy.LINEAR, // or EXPONENTIALOneTimeWorkRequest.MIN_BACKOFF_MILLIS, // min 10 secTimeUnit.MILLISECONDS).setInitialDelay(10, TimeUnit.MINUTES)//First time Initial Delay if Periodic Job.addTag("cleanup") // used to identify job by tag.setInputData(workDataOf("IMAGE_URI" to "http://..."
))// Used to send Input data once job started
class UploadWork(appContext: Context, workerParams: WorkerParameters)
: Worker(appContext, workerParams) {
override fun doWork(): Result {
val imageUriInput =
inputData.getString("IMAGE_URI") ?: return Result.failure()
return Result.success()
val myWork: WorkRequest = // ... OneTime or PeriodicWork
  • KEEP existing work and ignore the new work.
  • APPEND the new work to the end of the existing work. This policy will cause your new work to be chained to the existing work, running after the existing work finishes.

Observing your work

At any point after enqueuing work, you can check its status by querying WorkManager by its name, id or by a tag associated with it.

// by id
workManager.getWorkInfoById( // ListenableFuture<WorkInfo>
// by name
workManager.getWorkInfosForUniqueWork("sync") // ListenableFuture<List<WorkInfo>>
// by tag
workManager.getWorkInfosByTag("syncTag") // ListenableFuture<List<WorkInfo>>
.observe(viewLifecycleOwner) { workInfo ->
if(workInfo?.state == WorkInfo.State.SUCCEEDED) {
R.string.work_completed, Snackbar.LENGTH_SHORT)
val workQuery = WorkQuery.Builder
.addStates(listOf(WorkInfo.State.FAILED, WorkInfo.State.CANCELLED))
.addUniqueWorkNames(listOf("preProcess", "sync")
val workInfos: ListenableFuture<List<WorkInfo>> = workManager.getWorkInfos(workQuery)
// by id
// by name
// by tag
  • In the case of unique work, you explicitly enqueued a new WorkRequest with an ExistingWorkPolicy of REPLACE. The old WorkRequest is immediately considered cancelled.
  • Your work’s constraints are no longer met.
  • The system instructed your app to stop your work for some reason. This can happen if you exceed the execution deadline of 10 minutes. The work is scheduled for retry at a later time.

Updating Progress

import android.content.Context
import kotlinx.coroutines.delay
class ProgressWorker(context: Context, parameters: WorkerParameters) :
CoroutineWorker(context, parameters) {
companion object {
const val Progress = "Progress"
private const val delayDuration = 1L
override suspend fun doWork(): Result {
val firstUpdate = workDataOf(Progress to 0)
val lastUpdate = workDataOf(Progress to 100)
return Result.success()
// requestId is the WorkRequest id
.observe(observer, Observer { workInfo: WorkInfo? ->
if (workInfo != null) {
val progress = workInfo.progress
val value = progress.getInt(Progress, 0)
// Do something with progress information
// Candidates to run in parallel
.beginWith(listOf(filter1, filter2, filter3))
// Dependent work (only runs after all previous work in chain)
// Don't forget to enqueue()

Input Mergers

When using chains of OneTimeWorkRequests, the output of parent OneTimeWorkRequests are passed in as inputs to the children. So in the above example, the outputs of filter1, filter2 and filter3 would be passed in as inputs to the compress request.

val compress: OneTimeWorkRequest = OneTimeWorkRequestBuilder<CompressWorker>()
// Define the parameter keys:
const val KEY_X_ARG = "X"
const val KEY_Y_ARG = "Y"
const val KEY_Z_ARG = "Z"
// ...and the result key:
const val KEY_RESULT = "result"
// Define the Worker class:
class MathWorker(context : Context, params : WorkerParameters)
: Worker(context, params) {
override fun doWork(): Result {
val x = inputData.getInt(KEY_X_ARG, 0)
val y = inputData.getInt(KEY_Y_ARG, 0)
val z = inputData.getInt(KEY_Z_ARG, 0)
// the math...
val result = myLongCalculation(x, y, z);
//...set the output, and we're done!
val output: Data = workDataOf(KEY_RESULT to result)
return Result.success(output)
val myData: Data = workDataOf("KEY_X_ARG" to 42,
"KEY_Y_ARG" to 421,
"KEY_Z_ARG" to 8675309)
// ...then create and enqueue a OneTimeWorkRequest that uses those arguments
val mathWork = OneTimeWorkRequestBuilder<MathWorker>()
.observe(this, Observer { info ->
if (info != null && info.state.isFinished) {
val myResult = info.outputData.getInt(KEY_RESULT,
// ... do something with the result ...

Chaining and Work Statuses

There are a couple of things to keep in mind when creating chains of OneTimeWorkRequests.

  • When any parent OneTimeWorkRequest fails (returns a Result.failure(), then all dependent OneTimeWorkRequests are also marked as FAILED.
  • When any parent OneTimeWorkRequest is cancelled, all dependent OneTimeWorkRequests are also marked as CANCELLED.
val chain1 = WorkManager.getInstance(myContext)
val chain2 = WorkManager.getInstance(myContext)
val chain3 = WorkContinuation
.combine(Arrays.asList(chain1, chain2))
tools:node="remove" />
class MyApplication() : Application(), Configuration.Provider {
override fun getWorkManagerConfiguration() =
// initialize WorkManager
WorkManager.initialize(context, myConfig)
class CoroutineDownloadWorker(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) {    override val coroutineContext = Dispatchers.IO    override suspend fun doWork(): Result = coroutineScope {
val jobs = (0 until 100).map {
async {
// awaitAll will throw an exception if a download fails, which CoroutineWorker will treat as a failure
public class CallbackWorker extends ListenableWorker {    public CallbackWorker(Context context, WorkerParameters params) {
super(context, params);
public ListenableFuture<Result> startWork() {
return CallbackToFutureAdapter.getFuture(completer -> {
Callback callback = new Callback() {
int successes = 0;
public void onFailure(Call call, IOException e) {
public void onResponse(Call call, Response response) {
if (successes == 100) {
completer.addCancellationListener(cancelDownloadsRunnable, executor); for (int i = 0; i < 100; ++i) {
downloadAsynchronously("", callback);
return callback;
class DownloadWorker(context: Context, parameters: WorkerParameters) :
CoroutineWorker(context, parameters) {
private val notificationManager =
context.getSystemService(Context.NOTIFICATION_SERVICE) as
override suspend fun doWork(): Result {
val inputUrl = inputData.getString(KEY_INPUT_URL)
?: return Result.failure()
val outputFile = inputData.getString(KEY_OUTPUT_FILE_NAME)
?: return Result.failure()
// Mark the Worker as important
val progress = "Starting Download"
download(inputUrl, outputFile)
return Result.success()
private fun download(inputUrl: String, outputFile: String) {
// Downloads a file and updates bytes read
// Calls setForegroundInfo() periodically when it needs to update
// the ongoing Notification
// Creates an instance of ForegroundInfo which can be used to update the
// ongoing notification.
private fun createForegroundInfo(progress: String): ForegroundInfo {
val id = applicationContext.getString(R.string.notification_channel_id)
val title = applicationContext.getString(R.string.notification_title)
val cancel = applicationContext.getString(R.string.cancel_download)
// This PendingIntent can be used to cancel the worker
val intent = WorkManager.getInstance(applicationContext)
// Create a Notification channel if necessary
val notification = NotificationCompat.Builder(applicationContext, id)
// Add the cancel action to the notification which can
// be used to cancel the worker
.addAction(android.R.drawable.ic_delete, cancel, intent)
return ForegroundInfo(notification)
private fun createChannel() {
// Create a Notification channel
companion object {
tools:node="merge" />
// Updates the example worker to specify a foreground service type of
// "location".
private fun createForegroundInfo(progress: String): ForegroundInfo {
// ...
// You don't need to make any changes to the notification object.
return ForegroundInfo(NOTIFICATION_ID, notification,
val testDriver = WorkManagerTestInitHelper.getTestDriver()



Principal Software Engineer , Mobile Engineering

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store