WorkManager | Android Developers

The WorkManager API makes it easy to specify deferrable, asynchronous tasks and when they should run. These APIs let you create a task and hand it off to WorkManager to run immediately or at an appropriate time. See the reference docs for more information.

Declaring dependencies

To add a dependency on WorkManager, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

dependencies {
    def work_version = "1.0.0-rc01"

    implementation "android.arch.work:work-runtime:$work_version" // For Kotlin+Coroutines use work-runtime-ktx

    // optional - RxJava2 support
    implementation "android.arch.work:work-rxjava2:$work_version"

    // optional - Test helpers
    androidTestImplementation "android.arch.work:work-testing:$work_version"
}

For information on using Kotlin extensions, see ktx documentation.

For more information about dependencies, see Add Build Dependencies.

Version 1.0.0-rc01

February 14, 2019

This is a release candidate for WorkManager's 1.0.0 stable release. This release contains one bug fix.

Bug Fixes

The AlarmManager based implementation now correctly respects flex windows for PeriodicWorkRequsts. b/124274584

Version 1.0.0-beta05

February 6, 2019

This release contains some bug fixes.

Bug Fixes

Fixed a case where JobScheduler.getPendingJob(...) was used on API 23. b/123893059
Fixed a NullPointerException on devices running Android 5.1 (API level 22) or lower. b/123835104

Version 1.0.0-beta04

February 4, 2019

This release contains some bug fixes.

Bug Fixes

Improved scheduling of PeriodicWork for the AlarmManager based implementation.
Fixed a case where WorkManager failed to correctly track constraints when using the AlarmManager based implementation. b/123379508
Fixed a case when WorkManager failed to retry work on process death when using the AlarmManager based implementation. b/123329850
Fixed a case which would cause WorkManager to leak Wakelocks when using the AlarmManager based implementation.

Version 1.0.0-beta03

January 25, 2019

This release contains some bug fixes.

Bug Fixes

We introduced a regression 1.0.0-beta02 that was causing work to not execute properly in some situations. b/123211993
Fixed a case where work wasn't properly honoring backoff timing. b/122881597
Fixed a ConcurrentModificationException on devices running Android 5.1 (API or) or lower. This is a continuation of the fix in 1.0.0-beta02. b/121345393
Added exported=false for some components in our manifest that were missing this annotation.
Included information about how WorkManager interacts with the OS in the package-level documentation.

Version 1.0.0-beta02

January 15, 2019

This release contains some bug fixes.

Bug Fixes

Fixed an edge case where periodic work could run more than once per interval on devices running Android 6.0 (API level 23). b/121998363
Fixed a ConcurrentModificationException on devices running Android 5.1 (API level 22) or lower. b/121345393
Fixed erroneous execution of work when Constraints aren't met on devices running Android 5.1 (API level 22) or lower. b/122578012
Optimized work completion handling to be faster in some edge cases. b/122358129
Added a change to address potential race conditions among multiple instances of LiveData that WorkManager uses.
Moved to use Room dependency 1.1.1 instead of 1.1.1-rc01; these versions are identical. b/122578011

Version 1.0.0-beta01

December 19, 2018

This release contains no API changes; moving forward, WorkManager is expected to stay API stable until the next version unless there is a critical problem. This release contains some bug fixes.

Bug Fixes

Previously-cancelled children of successfully completed parent work will no longer run. b/120811767
Properly initialized logging classes (primarily surfaced during tests).

Version 1.0.0-alpha13

December 12, 2018

This release contains a minor API change that will be helpful for some Kotlin users.

API Changes

androidx.work.Result has been moved to be an inner class of ListenableWorker. This prevents refactoring conflicts with Kotlin's top-level Result class. This is a breaking API change. b/120564418

Breaking API Changes

androidx.work.Result has been moved to be an inner class of ListenableWorker.

Version 1.0.0-alpha12

December 5, 2018

This release contains some breaking API changes; please see the Breaking API Changes section below. This version is likely to be released as our first beta. alpha12 also contains extensive documentation updates.

API Changes

A new artifact, work-rxjava2, introduces RxWorker. This is a ListenableWorker that expects a Single<Payload>.
Support for Firebase JobDispatcher has been removed because of its impending deprecation. This means that the work-firebase artifact will no longer be updated as we head into beta. We will be looking into adding an alternative in the future.
Combined Payload into Result. Result is now a "sealed class" with three concrete implementations, which you can obtain via Result.success() (or Result.success(Data)), Result.failure() (or Result.failure(Data)), and Result.retry(). Your ListenableFutures now result Result instead of Payload. Workers don't have getter and setter methods for output Data. This is a breaking change.
Added Constraints.Builder.setTriggerContentMaxDelay(long, TimeUnit) and Constraints.Builder.setTriggerContentUpdateDelay(long, TimeUnit) and variants to better support slow triggering content URIs. b/119919774
Added WorkRequest.Builder.setBackoffCriteria(BackoffPolicy, Duration) variant. This method requires API 26.
Added Operation.await() and ListenableFuture.await() Kotlin extension methods.
Renamed Operation.getException() to Operation.getThrowable(). This is a breaking change.
The ContentUriTriggers class and methods referencing it are no longer available for public usage. This is a breaking change.
Removed the rest of the varargs methods in WorkManager, WorkContinuation, and OneTimeWorkRequest to streamline the API. To fix any build problems, you can wrap your existing varargs with Arrays.asList(...). We still include single-argument versions of each method. This is a breaking change.
Removed WorkContinuation.combine(OneTimeWorkRequest, *) variants. They were presenting a confusing API; the existing combine methods are more understandable. This is a breaking change.

Bug Fixes

Pre-Marshmallow implementations are now more reliable in recovering from process death of an already-executing task.
LiveData that is observed via observeForever is tracked via WorkManager. This is a backport of a Room library fix. b/74477406
Data.Builder.build() now throws an exception if the serialized object exceeds its maximum size. This previously would only happen on a background thread where you couldn't properly handle it.
Further distinguished stopped vs. cancelled work; getWorkInfoById() will return a WorkInfo with the CANCELLED State during ListenableWorker.onStopped().
Treat null Results as failures in ListenableWorker. b/120362353
Speculative fix for Shield Tablets running API 24 that sometimes threw an IllegalArgumentException. b/119484416

Breaking API Changes

Support for Firebase JobDispatcher has been removed because of its impending deprecation. This means that the work-firebase artifact will no longer be updated as we head into beta. We will be looking into adding an alternative in the future.
Combined Payload into Result. Result is now a "sealed class" with three concrete implementations, which you can obtain via Result.success() (or Result.success(Data)), Result.failure() (or Result.failure(Data)), and Result.retry(). Your ListenableFutures now result Result instead of Payload. Workers don't have getter and setter methods for output Data.
Added Operation.await() and ListenableFuture.await() Kotlin extension methods.
Renamed Operation.getException() to Operation.getThrowable().
The ContentUriTriggers class and methods referencing it are no longer available for public usage.
Removed the rest of the varargs methods in WorkManager, WorkContinuation, and OneTimeWorkRequest to streamline the API. To fix any build problems, you can wrap your existing varargs with Arrays.asList(...). We still include single-argument versions of each method.
Removed WorkContinuation.combine(OneTimeWorkRequest, *) variants. They were presenting a confusing API; the existing combine methods are more understandable.

Version 1.0.0-alpha11

November 8, 2018

This release contains many changes that will become stable API at beta. There are breaking API changes in this release; please see the Breaking API Changes section below.

API Changes

work-runtime-ktx introduces a new CoroutineWorker.
WorkStatus has been renamed to WorkInfo. All corresponding getStatus method variants have been renamed to the corresponding getWorkInfo variants. This is a breaking change.
ListenableWorker.onStopped() no longer accepts has a boolean argument representing if the WorkRequest was cancelled. WorkManager no longer makes this distinction. This is a breaking change.
androidx.work.test package has been renamed to androidx.work.testing package. This is a breaking change.
Setters on Constraints are no longer a part of the public API. This is a breaking change.
WorkerParameters.getTriggeredContentUris() and WorkerParameters.getTriggeredContentAuthorities() previously returned arrays. Now these methods return Collections. This is a breaking change.
ListenableWorker.onStartWork() is renamed to ListenableWorker.startWork(). This is a breaking change.
The constructor for WorkStatus is no longer a part of the public API. This is a breaking change.
Configuration.getMaxJobSchedulerID() and Configuration.getMinJobSchedulerID() are renamed to Configuration.getMinJobSchedulerId() and Configuration.getMaxJobSchedulerId() respectively. This is a breaking change.
Added a lot of @NonNull annotations to the public API to improve ergonomics of the API.
Add WorkManager.enqueueUniqueWork() API to enqueue unique OneTimeWorkRequests without having to create a WorkContinuation.
All variants of enqueue and cancel methods on WorkManager now return a new Operation type. This is a breaking change.
All variants of enqueue no longer accept varargs for WorkRequests. This is a breaking change. Use Collections instead. You can use Arrays.asList() to modify existing code. We did this to reduce the API surface and method count.
Attempting to initialize WorkManager more than once per process will now result in an IllegalStateException. This is a breaking change.

Bug Fixes

WorkRequest.Builders in the work-runtime-ktx artifact now use ListenableWorkers. Fixes b/117666259
Ensure the next run time for PeriodicWork is in the future. Fixes b/118204399
Remove potential disk I/O when using WorkManager on app startup. Fixes b/117796731
Fix a race condition in WorkConstraintsTracker. Fixes android-workmanager/issues/56

Breaking API Changes

WorkStatus has been renamed to WorkInfo. All corresponding getStatus method variants have been renamed to the corresponding getWorkInfo variants.
ListenableWorker.onStopped() no longer accepts has a boolean argument representing if the WorkRequest was cancelled. WorkManager no longer makes this distinction.
androidx.work.test package has been renamed to androidx.work.testing package.
Setters on Constraints are no longer a part of the public API.
WorkerParameters.getTriggeredContentUris() and WorkerParameters.getTriggeredContentAuthorities() previously returned arrays. Now these methods return Collections.
ListenableWorker.onStartWork() is renamed to ListenableWorker.startWork().
The constructor for WorkStatus is no longer a part of the public API.
Configuration.getMaxJobSchedulerID() and Configuration.getMinJobSchedulerID() are renamed to Configuration.getMinJobSchedulerId() and Configuration.getMaxJobSchedulerId() respectively.
All variants ofenqueue and cancel methods on WorkManager now return a new Operation type.
All variants of enqueue no longer accept varargs for WorkRequests.
Attempting to initialize WorkManager more than once per process will now result in an IllegalStateException.

Version 1.0.0-alpha10

October 11, 2018

This release supports developer-controlled asynchronous work. There are breaking API changes in this release; please see the Breaking API Changes section below.

We anticipate that WorkManager is entering the final phases of its alpha period. We expect to be API stable in beta, so please take some time to file your feedback on our issue tracker.

API Changes

Removed all previously deprecated methods and classes, notably the default Worker constructor. This is a breaking API change.
Renamed NonBlockingWorker to ListenableWorker, which is now an unhidden public class and ready for usage.
- ListenableWorker provides access to one abstract method, ListenableFuture<Payload> onStartWork() which is called on the main thread. It is up to you to start and process work asynchronously. When finished, you should update the ListenableFuture appropriately. Reference implementations of ListenableFutures are provided in the Futures package in alpha02 (see below the WorkManager section).
- Worker extends ListenableWorker and still operates as before, with an abstract Result doWork() method.
- Shuffled some methods and members from Worker to ListenableWorker.
- We shall soon provide reference implementations for ListenableWorkers that use Kotlin coroutines (once the stable versions are released) and RxJava2.
The interface WorkerFactory and the concrete implementation DefaultWorkerFactory have been merged into an abstract class called WorkerFactory. The implementation ensures that the default reflection-based behavior is called as a last-ditch effort for any user-created WorkerFactory instances. This is a breaking change.
Removed WorkManager.synchronous() and WorkContinuation.synchronous() and all related methods. Added ListenableFuture<Void> as the return type of many methods in the API. This is a breaking API change.
- You can now synchronously get and observe by using ListenableFutures. For example, WorkManager.enqueue() used to return void; it now returns a ListenableFuture<Void>. You can call ListenableFuture.addListener(Runnable, Executor) or ListenableFuture.get() to run code once the operation is complete.
- Note that these ListenableFutures do not tell you if the operation succeeded or failed; only that they finished. You will still need to chain WorkManager methods to find out this information.
- We ignore cancel() calls on these objects, as they are confusing and hard to reason about (are you cancelling the operation or the resulting work?). This is within the Futures contract.
- To maintain parity with the synchronous getStatus* methods, we have provided ListenableFuture variants, and renamed the existing ones that returned LiveData to explicitly have "LiveData" as part of the name (for example, getStatusesByIdLiveData(UUID)). This is a breaking API change.

Bug Fixes

Fixed the known issue from alpha09 regarding duplicate androidx-annotations.pro files. You may remove the workaround from the previous release notes by deleting exclude 'META-INF/proguard/androidx-annotations.pro' from your gradle file.
Added proguard configurations to keep new Worker constructor. b/116296569
Fix potential NullPointerException in a race condition where work was REPLACEd. b/116253486 and b/116677275
WorkContinuation.combine() now accepts one or more WorkContinuations instead of two or more. b/117266752

Breaking API Changes

Removed all previously deprecated methods and classes, notably the default Worker constructor.
The interface WorkerFactory and the concrete implementation DefaultWorkerFactory have been merged into an abstract class called WorkerFactory.
Removed WorkManager.synchronous() and WorkContinuation.synchronous().
WorkManager.getStatus*() methods now return ListenableFutures. WorkManager.getStatus*LiveData() return LiveDatas.

Version 1.0.0-alpha09

September 19, 2018

Known Issue

If you run into the following issue: "More than one file was found with OS independent path 'META-INF/proguard/androidx-annotations.pro'", please put the following in your gradle file as a temporary workaround while we fix the issue in alpha10:

    android {
        packagingOptions {
            exclude 'META-INF/proguard/androidx-annotations.pro'
        }
    }

Bug Fixes

Added another fix that was needed for the "100 jobs" error. b/115560696
Added some fixes for foreign key constraint errors due to race conditions. b/114705286
Delegated ConstraintTrackingWorker.onStopped(boolean) calls to the underlying Worker. b/114125093
Enforce correct minimum backoff delay for Firebase JobDispatcher. b/113304626
Improved threading guarantees internal to the library.
Correct potential issue with deduping of LiveData internally.

API Changes

You can now create your own Worker instances at runtime by specifying a WorkerFactory as part of the WorkManager.Configuration. The fallback factory is DefaultWorkerFactory, which matches behavior of previous versions of WorkManager.
- The default constructors for Worker and NonBlockingWorker are now marked as deprecated. Please use the new constructor (Worker(Context, WorkerParameters)) and call super(Context, WorkerParameters); future versions of WorkManager will remove the default constructor.
We have started using the new ListenableFuture artifact internally (free of Guava dependencies). We will introduce ListenableFutures to the API in upcoming releases. This change will support the eventual unhiding of NonBlockingWorker.
Add ability to trigger timed work in TestDriver via TestDriver.setInitialDelayMet(UUID) and TestDriver.setPeriodDelayMet(UUID). b/113360060

Breaking Changes

The default Worker and NonBlockingWorker constructors are deprecated. Please migrate to the new constructor ASAP. Future versions will remove the default constructor.

Version 1.0.0-alpha08

August 27, 2018

Bug Fixes

Explicitly labelled WorkManager components as direct boot unaware so they don't fire up during direct boot. In the future, we will provide a version of WorkManager that is direct boot-aware. b/112665532
Fixed an issue where retried work was not running. b/112604021
Fixed periodic work not executing repeatedly (related to the above issue). b/112859683
Honored backoff policies when the app process is already running.
Corrected exception messages in Data to indicate the limit is 10KB.
Lowered maximum value of Configuration.setMaxSchedulerLimit(int) to 50 to account for some latency in JobScheduler processing completion. b/112817355

Version 1.0.0-alpha07

August 16, 2018

Bug Fixes

Fixed a potential SQL query with negative limits that could return an unbounded number of results.
Work that has finished execution now correctly cancels all pending copies of that work in other Schedulers. This led to exceeding the JobScheduler jobs limit. b/111569265
Fixed a ConcurrentModificationException in ConstraintTracker. b/112272753
Changed return type annotations of Data.getBooleanArray(String) and Data.getIntArray(String) to @Nullable instead of @NonNull. b/112275229

API Changes

Worker now extends a new class, NonBlockingWorker. This does not affect any current usage. In the future, NonBlockingWorker will become a fully supported entity for custom threading solutions.
Changed return type annotations of Data.getBooleanArray(String) and Data.getIntArray(String) to @Nullable instead of @NonNull. b/112275229
Kotlin extensions: deprecated Map.toWorkData() and added a top-level workDataOf(vararg Pair<String, Any?>) to be more consistent with existing APIs.

Version 1.0.0-alpha06

August 1, 2018

Bug Fixes

Prevent a database lock when scheduling work. b/111801342
Fix a bug which causes PeriodicWork to not run on schedule when in Doze mode. b/111469837
Fix a race condition when tracking constraints which causes WorkManager to crash. googlecodelabs/android-workmanager/issues/56
Create unique WorkRequests when using WorkRequest.Builder#build(). b/111408337
Enable the use of RescheduleReceiver only when there are WorkRequests that need it. b/111765853

Version 1.0.0-alpha05

July 24, 2018

API Changes

WorkManager.getInstance() is now annotated with @NonNull instead of @Nullable. Instead, if the singleton isn't properly initialized in cases of manual initialization, the method will throw an IllegalStateException. This is a breaking API change.
Added a new API, Configuration.Builder.setMinimumLoggingLevel(int), which can control WorkManager verbosity. By default, WorkManager logs Log.INFO and above.
Changed signature of Data.getString() so it no longer takes a default value (it is implicitly null). This is a breaking API change.
Marked some methods needed only for internal usage as @hide. This includes the Constraints constructor, Data.toByteArray(), and Data.fromByteArray(byte[]). This is a breaking API change.

Bug Fixes

WorkManager no longer executes work during known cases of auto-backup. This could have resulted in a crash. b/110564377
Fixed double-scheduling of PeriodicWorkRequests when using JobScheduler. b/110798652
Fixed an issue with PeriodicWorkRequests not executing correctly after device doze. b/111469837
Fixed an issue with initial delays when using Firebase JobDispatcher. b/111141023
Fixed some potential race conditions and timing issues.
Correctly freed up BroadcastReceivers that were no longer needed.
Optimized rescheduling performance when apps restart after being force closed.
Allowed TestScheduler.setAllConstraintsMet(UUID) to be called before or after enqueuing the given WorkRequest. b/111238024

Breaking Changes

WorkManager.getInstance() is now annotated with @NonNull instead of @Nullable.
Changed signature of Data.getString() so it no longer takes a default value (it is implicitly null).
Marked some methods needed only for internal usage as @hide. This includes the Constraints constructor, Data.toByteArray(), and Data.fromByteArray(byte[]).

Version 1.0.0-alpha04

June 26, 2018

Bug Fixes

PeriodicWorkRequests are now correctly rescheduled when using the AlarmManager based implementation.
Fixed a potential ANR when rescheduling all workers after a force stop or a reboot. b/110507716
Added nullability annotations to various WorkManager APIs. b/110344065
Log uncaught exceptions that occur during Worker execution. b/109900862
Allowed destructive database migrations in case you decide to roll back to an older version of WorkManager. b/74633270
Fixed a migration crash if creating duplicate implicit tags. This is a very rare issue that occurred only if you used the same implicit tag format yourself.

Version 1.0.0-alpha03

June 19, 2018

Bug Fixes

Fixed a race condition in the AlarmManager based implementation. b/80346526.
Fixed duplicate jobs when using JobScheduler after a device reboot.
Jobs with Content URI triggers now persist across reboots. b/80234744
Documentation updates. b/109827628, b/109758949, b/80230748
Fixed a crash when re-enqueuing a WorkRequest. b/109572353.
Fixed Kotlin compiler warnings when using the work-runtime-ktx dependency.
WorkManager now uses Room version 1.1.1-rc1.

API Changes

Added getStatusesSync(), the synchronous version of WorkContinuation.getStatuses().
Worker has the ability to distinguish between user-initiated cancellation and temporary os-requested stopping. Worker.isStopped() returns true if any kind of stop has been requested. Worker.isCancelled() returns true when the work has been explicitly cancelled. b/79632247
Add support for JobParameters#getNetwork() on API 28. This is exposed via Worker.getNetwork().
Added Configuration.Builder.setMaxSchedulerLimit(int maxSchedulerLimit) so you can enforce how many jobs can be sent to JobScheduler or AlarmManager. This helps prevent WorkManager from taking all your available JobScheduler slots.
Added Configuration.setJobSchedulerJobIdRange(int minJobSchedulerId, int maxJobSchedulerId) which helps define a range of JobScheduler job ids safe for WorkManager to use. b/79996760
Worker.getRunAttemptCount() returns the current run count for a given Worker. b/79716516
WorkManager.enqueueUniquePeriodicWork(String uniqueWorkName, ExistingPeriodicWorkPolicy existingPeriodicWorkPolicy, PeriodicWorkRequest periodicWork) allows you to enqueue a unique PeriodicWorkRequests. b/79600647
WorkManager.cancelAllWork() cancels all Workers. Libraries that depend on WorkManager can query when this method was called last by using WorkManager.getLastCancelAllTimeMillis() for additional cleanup of internal state.
Added WorkManager.pruneWork() to remove completed jobs from the internal database. b/79950952, b/109710758

Behavior Changes

Added an implicit tag for all WorkRequests, which is the fully qualified class name for the Worker. This allows the ability to remove WorkRequests without tags or when the id is not available. b/109572351

Breaking Changes

Renamed Worker.WorkerResult to Worker.Result.
Worker.onStopped now has an additional isCancelled parameter which is set totrue when the Worker has explicitly been cancelled.

Version 1.0.0-alpha02

May 24, 2018

Bug Fixes

Fixed a NullPointerException on State.isFinished(). b/79550068
Fixed an issue which caused Workers to be rescheduled on Application.onCreate(). b/79660657
Fixed an issue where you could schedule more work than is allowed by the OS. b/79497378
Moved cleanup of wake locks associated with Workers to the background thread.
The AlarmManager implementation now correctly cleans up when all pending work is complete.
Fixed cleanup SQL queries which affected non-English locales. b/80065360
Added support for floats in Data. b/79443878
Data.Builder.putAll() now returns an instance of the Builder. b/79699162
More javadoc and fixes in documentation. b/79691663

API Changes

Workers can react to being stopped. Worker.isStopped() can be used to check if a Worker has been stopped. Worker.onStopped() can be used to perform lightweight cleanup operations.
Worker.getTags() API returns a Set of tags associated with the Worker.
Added javax.time.Duration overloads for APIs which take a combination of duration and TimeUnits. This is guarded by @RequiresApi(26).
WorkManager extensions have moved from the androidx.work.ktx package to the androix.work package. The old extensions are deprecated and will be removed in a future version.
Configuration.withExecutor() is deprecated. Use Configuration.setExecutor() instead.

Version 1.0.0-alpha01

May 8, 2018

WorkManager simplifies scheduling and execution of guaranteed, constraint-aware background work. This initial release is 1.0.0-alpha01.