Background Tasks

Overview

Tasks allow you to run long operations asynchronously without blocking your application. You can process batches, migrate data, or perform bulk operations in the background.

To create a background task, you implement the TaskDefinition.Interface and register it using TaskDefinition.createImplementation().

Example

Available Methods

When creating a background task, you implement the following methods:

Core Methods

• run() - The main method where your task logic executes. Required.
• createInputValidation() - Validates the input data before the task runs. Optional.

Lifecycle Hooks

These hooks are called at different stages of task execution:

• onBeforeTrigger() - Called before the task is triggered.
• onDone() - Called when the task completes successfully.
• onError() - Called when the task fails with an error.
• onAbort() - Called when the task is manually aborted.
• onMaxIterations() - Called when the task reaches the maximum iteration limit.

Task Responses

Inside the run() method, you receive a controller object that helps you control task execution. You use it to return different responses:

• controller.response.done() - Task completed successfully.
• controller.response.continue() - Task needs more time, will resume in the next iteration.
• controller.response.error() - Task encountered an error and should stop.
• controller.response.aborted() - Task was manually stopped.

Controller Runtime Methods

The controller also provides runtime methods to check the task’s execution state:

• controller.runtime.isAborted() - Returns true if the task was manually aborted.
• controller.runtime.isCloseToTimeout() - Returns true if the task is running out of time. Use this to return continue() and preserve your progress.

Managing Tasks via GraphQL

List Available Task Definitions

Use this query to see all registered background tasks in your system. Each definition includes the task ID, title, and description you defined when creating the task.

List All Task Runs

Use this query to see all task executions. Each task run includes its status, timestamps, iterations, input/output data, and more. This helps you monitor task progress and troubleshoot issues.

List All Task Logs

Use this query to view detailed execution logs for debugging. You can filter logs by task ID to see what happened during a specific task execution. Logs include messages, timestamps, types, and error details.

Trigger a Task

Use this mutation to start a task execution with custom input parameters. The task will be queued and executed asynchronously. You can track its progress using the task ID returned in the response.

Abort a Task

Use this mutation to stop a running task. Provide the task ID and optionally a message explaining why the task is being aborted. The task will stop at the next safe checkpoint.

Managing Tasks via Code

Triggering a Task Programmatically

Use the TaskService to trigger tasks directly from your backend code. This is useful when you need to start background tasks as part of your application logic, such as after a user action or during a scheduled process. You can specify the task definition ID, custom input data, delay, parent task relationship, and a display name.

Aborting a Task Programmatically

Use the TaskService to abort a running task from your backend code. This is useful when you need to stop tasks programmatically based on application state or business logic. Provide the task ID and optionally a message explaining why the task is being aborted.