Getting started with WorkManager

With WorkManager, you can easily set up a task and hand it off to the system to run under the conditions you specify. To learn more if WorkManager is the right solution for your task, check out the background processing guide.

In this guide you will learn how to:

• Add WorkManager to your Android project
• Create a background task
• Configure how and when to run the task
• Hand off your task to the system

For information about WorkManager features, like handling recurring work, creating chains of work and cancelling work, check out the how-to guides.

Add WorkManager to your Android project

Add the WorkManager dependency in Java or Kotlin to your Android project following the instructions in the WorkManager release notes.

Create a background task

A task is defined using the Worker class. The doWork() method is run synchronously on a background thread provided by WorkManager.

To create your background task, extend the Worker class and override the doWork() method. For example, to create a Worker that uploads images, you can do the following:

class UploadWorker(appContext: Context, workerParams: WorkerParameters)
    : Worker(appContext, workerParams) {

    override fun doWork(): Result {
        // Do the work here--in this case, upload the images.

        uploadImages()

        // Indicate whether the task finished successfully with the Result
        return Result.success()
    }
}

public class UploadWorker extends Worker {

    public UploadWorker(
        @NonNull Context context,
        @NonNull WorkerParameters params) {
        super(context, params);
    }

    @Override
    public Result doWork() {
      // Do the work here--in this case, upload the images.

      uploadImages()

      // Indicate whether the task finished successfully with the Result
      return Result.success()
    }
}

The Result returned from doWork() informs WorkManager whether the task:

• finished successfully via Result.success()
• failed via Result.failure()
• needs to be retried at a later time via Result.retry()

Configure how and when to run the task

While a Worker defines the unit of work, a WorkRequest defines how and when work should be run. Tasks may be one-off or periodic. For one-off WorkRequests, use OneTimeWorkRequest and for periodic work PeriodicTimeWorkRequest. For more information on scheduling recurring work, read the recurring work documentation.

In this case, the simplest example for building a WorkRequest for our UploadWorker is:

val uploadWorkRequest = OneTimeWorkRequestBuilder<UploadWorker>()
        .build()

OneTimeWorkRequest uploadWorkRequest = new OneTimeWorkRequest.Builder(UploadWorker.class)
        .build()

The WorkRequest can also include additional information, such as the constraints under which the task should run, input to the work, a delay, and backoff policy for retrying work. These options are explained in greater detail in the Defining Work guide.

Hand off your task to the system

Once you have defined your WorkRequest, you can now schedule it with WorkManager using the enqueue() method.

WorkManager.getInstance().enqueue(uploadWorkRequest)

WorkManager.getInstance().enqueue(uploadWorkRequest);

The exact time that the worker is going to be executed depends on the constraints that are used in your WorkRequest and on system optimizations. WorkManager is designed to give the best possible behavior under these restrictions.

Next steps

• See WorkManager in action in a simple image processing application
• Try the hands-on codelab in Kotlin, Java
• Learn how to add work constraints.