Manually executing tasks

Most of the time, our task-backed components can handle automatically executing and populating components with the output of a task or runbook. However, you might want to manually execute a task or runbook in the following situations:
  • When using a component that is not task backed (e.g. a Dialog or Typography).
  • When using a custom, non-Airplane component.
  • When you want to do something more custom with a task output than just populate a component. e.g. show different components depending on the output of a task.
To manually execute a task, we expose the useTaskQuery and useTaskMutation hooks. When you manually execute a task, you are in charge of populating components with data as well as handling loading and error states.

useTaskQuery

useTaskQuery should be used for tasks that query for data. It has intelligent behavior for queries like caching and automatically refetching to keep the task output fresh.

API

javascript
Copied
1
const { output, loading, error, refetch } = useTaskQuery({
2
slug,
3
params,
4
enabled,
5
executeOnMount,
6
executeOnWindowFocus,
7
executeOnReconnect,
8
refetchInterval,
9
onSuccess,
10
onError,
11
});

Options

  • slug: string
    • Required
    • The slug of the task to execute.
  • params: object
    • Optional
    • The params of the task to execute.
  • enabled: boolean
    • Optional
    • Defaults to true
    • By default, the task is executed automatically. If set to false, the task will not be executed automatically. To execute a disabled task, use the returned refetch function.
  • refetchInterval: number
    • Optional
    • If set, the task will be re-exeuted, or refetched, every refetchInterval milliseconds.
  • onSuccess: (output: TOutput) => void
    • Optional
    • Callback on successful task execution.
  • onError: (output: TOutput, error: Error) => void
    • Optional
    • Callback on failed task execution.
  • executeOnMount: boolean
    • Optional
    • Defaults to true
    • If set to true, the task will be executed on mount.
  • executeOnWindowFocus: boolean
    • Optional
    • Defaults to true
    • If set to true, the task will be executed on window focus.
  • executeOnReconnect: boolean
    • Optional
    • Defaults to true
    • If set to true, the task will be executed on reconnect.

Returns

  • output: TOutput
    • Defaults to undefined
    • The output of the last executed task.
  • loading: boolean
    • Defaults to undefined
    • Will be true when the task is currently executing
  • error: { message: string; type: "AIRPLANE_INTERNAL" | "FAILED" }
    • Defaults to undefined
    • The error message if the task failed to execute. The type indicates whether the error is due to Airplane failing to execute the task, or due to the task itself failing.
  • refetch: () => Promise<{ data: TOutput }>
    • Defaults to undefined
    • A function that refetches, or re-executes, the task. This function can also be used to execute a task manually after the component loads in conjunction with the enabled option.

useTaskMutation

useTaskMutation should be used for tasks that create, update, or delete data.

API

js
Copied
1
const { output, loading, error, mutate } = useTaskMutation({
2
slug,
3
params,
4
refetchTasks,
5
onSuccess,
6
onError,
7
});

Options

  • slug: string
    • Required
    • The slug of the task to execute.
  • params: object
    • Optional
    • The params of the task to execute.
  • refetchTasks: RefetchQuery | RefetchQuery[]
    • Optional
    • A RefetchQuery is either a task slug or an object of { slug: string; params: object } representing a task.
    • If set, the provided tasks will be refetched on success.
    • This can be useful if you expect the task mutation to invalidate data.
  • onSuccess: (output: TOutput) => void
    • Optional
    • Callback on successful task execution.
  • onError: (output: TOutput, error: Error) => void
    • Optional
    • Callback on failed task execution.

Returns

  • output: TOutput
    • Defaults to undefined
    • The output of the last executed task.
  • loading: boolean
    • Defaults to undefined
    • Will be true when the task is currently executing
  • error: { message: string; type: "AIRPLANE_INTERNAL" | "FAILED" }
    • Defaults to undefined
    • The error message if the task failed to execute. The type indicates whether the error is due to Airplane failing to execute the task, or due to the task itself failing.
  • mutate: () => void
    • A function that executes the task.

useRunbookMutation

Note that unlike tasks, runbooks do not have outputs.
useRunbookMutation works similarly to useTaskMutation, but is used for executing runbooks instead of tasks.

API

js
Copied
1
const { loading, error, mutate } = useRunbookMutation({
2
slug,
3
params,
4
refetchTasks,
5
onSuccess,
6
onError,
7
});

Options

  • slug: string
    • Required
    • The slug of the runbook to execute.
  • params: object
    • Optional
    • The params of the runbook to execute.
  • refetchTasks: RefetchQuery | RefetchQuery[]
    • Optional
    • A RefetchQuery is either a task slug or an object of { slug: string; params: object } representing a task.
    • If set, the provided tasks will be refetched on success.
    • This can be useful if you expect the runbook mutation to invalidate data.
  • onSuccess: () => void
    • Optional
    • Callback on successful runbook execution.
  • onError: (error: Error) => void
    • Optional
    • Callback on failed runbook execution.

Returns

  • loading: boolean
    • Defaults to undefined
    • Will be true when the runbook is currently executing
  • error: { message: string; type: "AIRPLANE_INTERNAL" | "FAILED" }
    • Defaults to undefined
    • The error message if the runbook failed to execute. The type indicates whether the error is due to Airplane failing to execute the runbook, or due to the runbook itself failing.
  • mutate: () => void
    • A function that executes the runbook.