Core Development Concepts > Background Tasks

Background Task Management

You will learn about Background Tasks, how to create new definitions, how to trigger them and how to handle the task run.

Use with caution!

This feature is experimental and is subject to change in future releases.

Can I use this?

This feature is available since Webiny v5.39.0.

What you’ll learn

how to use Background Tasks GraphQL API
how to use programmatic API

GraphQL API

The Background Tasks do not have a section in the Admin UI yet, so they are accessible only via the GraphQL API.

Queries

List All Background Task Definitions

query ListTaskDefinitions {
  backgroundTasks {
    listDefinitions {
      data {
        id
        title
        description
      }
      error {
        message
        code
        data
        stack
      }
    }
  }
}

List All Background Task Runs

query ListTasks {
  backgroundTasks {
    listTasks {
      data {
        id
        startedOn
        finishedOn
        name
        definitionId
        iterations
        parentId
        executionName
        eventResponse
        taskStatus
        input
        output
        # ...more fields available
      }
      error {
        message
        code
        data
        stack
      }
    }
  }
}

List Background Task Logs

query ListBackgroundTaskLogs {
  backgroundTasks {
    listLogs(where: {
    # you can list logs from a certain task if you like
    task: "yourTaskId"
  }) {
      data {
        id
        createdOn
        executionName
        iteration
        items {
          message
          createdOn
          type
          data
          error
        }
      }
    }
  }
}

Mutations

Trigger a Background Task

mutation TriggerATask {
  backgroundTasks {
    triggerTask(definition: testingRun, input: {
      someVariableForTestingRunTaskToReceive: "someValue",
      yetAnotherVariableForTestingRunTaskToReceive: "anotherValue"
    }) {
      data {
        id
        definitionId
        executionName
        eventResponse
        taskStatus
        input
        # ... more fields available
      }
      error {
        message
        code
        data
        stack
      }
    }
  }
}

Abort a Background Task

mutation AbortATask {
  backgroundTasks {
    # message is optional
    abortTask(id: "yourTaskId", message: "My Reason for aborting the task") {
      data {
        id
        createdOn
        savedOn
        startedOn
        finishedOn
        definitionId
        iterations
        name
        input
        output
        # ... more fields available
      }
      error {
        message
        code
        data
        stack
      }
    }
  }
}

Permissions

To execute the mutations and queries for the Background Tasks, the user must have a Full Access. In future releases we will fine grain the permissions.

Code API

For examples, we will assume you are somewhere in the code where you have access to the Webiny context object.

List All Background Task Definitions

const results = await context.tasks.listDefinitions();

List All Background Task Runs

const results = await context.tasks.listTasks({
    // all properties are optional
    where: {},
    sort: [],
    limit: 100,
    after: null
});

Trigger a Background Task

const result = await context.tasks.trigger({
    definition: "myTaskDefinition",
    // optional input for the task run
    input: {
        variableToPassAsInput: "someValue"
    },
    // optional name for the task run
    name: "My Custom Task Name"
});

Abort a Background Task

const result = await context.tasks.trigger({
    id: "yourTaskId",
    // optional message
    message: "My Reason for aborting the task"
});

List Background Task Logs

const results = await context.tasks.listLogs({
    // all properties are optional
    where: {},
    sort: [],
    limit: 100,
    after: null
});