Overview

WorkManager the recommended library for persistent work. Scheduled work is guaranteed to execute sometime after its Constraints are met. WorkManager allows observation of work status and the ability to create complex chains of work.

WorkManager uses an underlying job dispatching service when available based on the following criteria:

• Uses JobScheduler for API 23+
• Uses a custom AlarmManager + BroadcastReceiver implementation for API 14-22

All work must be done in a ListenableWorker class. A simple implementation, Worker, is recommended as the starting point for most developers. With the optional dependencies, you can also use CoroutineWorker or RxWorker. All background work is given a maximum of ten minutes to finish its execution. After this time has expired, the worker will be signalled to stop.

There are two types of work supported by WorkManager: OneTimeWorkRequest and PeriodicWorkRequest. OneTimeWorkRequests can be chained together into acyclic graphs. Work is eligible for execution when all of its prerequisites are complete. If any of its prerequisites fail or are cancelled, the work will never run.

WorkRequests can accept Constraints, inputs (see Data), and backoff criteria. WorkRequests can be tagged with human-readable Strings (see WorkRequest.Builder.addTag(String)), and chains of work can be given a uniquely-identifiable name with conflict policies. *

Initializing WorkManager

By default, WorkManager is initialized using a ContentProvider with a default Configuration. ContentProviders are created and run before the Application object, so this allows the WorkManager singleton to be setup before your code can run in most cases. This is suitable for most developers. However, you can provide a custom Configuration by using Configuration.Provider or WorkManager.

WorkManager and its Interactions with the OS

WorkManager uses BroadcastReceivers to monitor Constraints on devices before API 23. The BroadcastReceivers are disabled on API 23 and up. In particular, WorkManager listens to the following Intents:

• android.intent.action.ACTION_POWER_CONNECTED
• android.intent.action.ACTION_POWER_DISCONNECTED
• android.intent.action.BATTERY_OKAY
• android.intent.action.BATTERY_LOW
• android.intent.action.DEVICE_STORAGE_LOW
• android.intent.action.DEVICE_STORAGE_OK
• android.net.conn.CONNECTIVITY_CHANGE

In addition, WorkManager listens to system time changes and reboots to properly reschedule work in certain situations. For this, it listens to the following Intents:

• android.intent.action.BOOT_COMPLETED
• android.intent.action.TIME_SET
• android.intent.action.TIMEZONE_CHANGED

WorkManager uses the following permissions:

• android.permission.WAKE_LOCK to make it can keep the device awake to complete work before API 23
• android.permission.ACCESS_NETWORK_STATE to listen to network changes before API 23 and monitor network Constraints
• android.permission.RECEIVE_BOOT_COMPLETED to listen to reboots and reschedule work properly.

Note that WorkManager may enable or disable some of its BroadcastReceivers at runtime as needed. This has the side-effect of the system sending ACTION_PACKAGE_CHANGED broadcasts to your app. Please be aware of this use case and architect your app appropriately (especially if you are using widgets - see https://issuetracker.google.com/115575872).

Interfaces

Clock	The interface WorkManager uses to access to the current time.
Configuration.Provider	A class that can provide the Configuration for WorkManager and allow for on-demand initialization of WorkManager.
ForegroundUpdater	Manages updating android.app.Notifications when a ListenableWorker transitions to running in the context of a foreground .
InitializationExceptionHandler	An Exception Handler that can be used to determine if there were issues when trying to initialize WorkManager.
Operation	An object that provides information about the execution of an asynchronous command being performed by WorkManager.
ProgressUpdater	Updates progress for a ListenableWorker.
RunnableScheduler	Can be used to schedule java.lang.Runnables after a delay in milliseconds.

Classes

ArrayCreatingInputMerger	An InputMerger that attempts to merge the inputs, creating arrays when necessary.
Configuration	The Configuration object used to customize WorkManager upon initialization.
Configuration.Builder	A Builder for Configurations.
Constraints	A specification of the requirements that need to be met before a WorkRequest can run.
Constraints.Builder	A Builder for a Constraints object.
ContentUriTriggers	A container for ContentUriTriggers.Triggers that caused a worker's Constraints to be met.
ContentUriTriggers.Trigger	Defines a content trigger for a WorkRequest.
Data	A persistable set of key/value pairs which are used as inputs and outputs for ListenableWorkers.
Data.Builder	A builder for Data objects.
DelegatingWorkerFactory	A WorkerFactory which delegates to other factories.
ForegroundInfo	The information required when a ListenableWorker runs in the context of a foreground service.
InputMerger	An abstract class that allows the user to define how to merge a list of inputs to a ListenableWorker.
InputMergerFactory	A factory object that creates InputMerger instances.
ListenableWorker	A class that can perform work asynchronously in WorkManager.
ListenableWorker.Result	The result of a ListenableWorker's computation.
ListenableWorker.Result.Failure	Used to indicate that the work completed with a permanent failure.
ListenableWorker.Result.Retry	Used to indicate that the work encountered a transient failure and should be retried with backoff specified in WorkRequest.Builder.setBackoffCriteria(BackoffPolicy, long, TimeUnit).
ListenableWorker.Result.Success	Used to indicate that the work completed successfully.
Logger	The class that handles logging requests for WorkManager.
Logger.LogcatLogger	The default Logger implementation that writes to logcat when the requests meet or exceed the loggingLevel specified in the constructor.
OneTimeWorkRequest	A WorkRequest for non-repeating work.
OneTimeWorkRequest.Builder	Builder for OneTimeWorkRequests.
Operation.State	The lifecycle state of an Operation.
Operation.State.FAILURE	This represents an Operation which has failed.
Operation.State.IN_PROGRESS	This represents an Operation which is in progress.
Operation.State.SUCCESS	This represents an Operation which is successful.
OverwritingInputMerger	An InputMerger that attempts to add all keys from all inputs to the output.
PeriodicWorkRequest	A WorkRequest for repeating work.
PeriodicWorkRequest.Builder	Builder for PeriodicWorkRequests.
RxWorker	RxJava2 interoperability Worker implementation.
SystemClock	A default clock that returns the real time from the Java System clock.
WorkContinuation	A class that allows you to chain together OneTimeWorkRequests.
Worker	A class that performs work synchronously on a background thread provided by WorkManager.
WorkerFactory	A factory object that creates ListenableWorker instances.
WorkerParameters	Setup parameters for a ListenableWorker.
WorkerParameters.RuntimeExtras	Extra runtime information for Workers.
WorkInfo	Information about a particular WorkRequest containing the id of the WorkRequest, its current WorkInfo.State, output, tags, and run attempt count.
WorkManager	WorkManager the recommended library for persistent work.
WorkManagerInitializer	Initializes WorkManager using androidx.startup.
WorkQuery	A specification for querying WorkRequests.
WorkQuery.Builder	A builder for WorkQuery.
WorkRequest	The base class for specifying parameters for work that should be enqueued in WorkManager.
WorkRequest.Builder<B, W>	A builder for WorkRequests.

Enums

BackoffPolicy	An enumeration of backoff policies when retrying work.
ExistingPeriodicWorkPolicy	An enumeration of the conflict resolution policies available to unique PeriodicWorkRequests in case of a collision.
ExistingWorkPolicy	An enumeration of the conflict resolution policies available to unique OneTimeWorkRequests in case of a collision.
NetworkType	An enumeration of various network types that can be used as Constraints for work.
OutOfQuotaPolicy	An enumeration of policies that help determine out of quota behavior for expedited jobs.
WorkInfo.State	The current lifecycle state of a WorkRequest.