Calling tasks with React hooks

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 directly 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.
We allow direct task execution through the useTaskQuery and useTaskMutation hooks. When you use these hooks, you are in charge of populating components with data as well as handling loading and error states.

Usage
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.
If you want to control when useTaskQuery executes its task, set enabled to false and call the task using the returned refetch function.
useTaskMutation should be used for tasks that create, update, or delete data.
useRunbookMutation works similarly to useTaskMutation, but is used for executing runbooks instead of tasks.
If a task doesn't require any parameters or special options, you can just pass the task slug: useTaskQuery("my_task") or an AirplaneFunc—the return value of airplane.task(): useTaskMutation(myTask).

API Reference

useTaskQuery

Options
  • fn: AirplaneFunc
    • One of fn or slug are required
    • The task to execute. This is the return value of airplane.task().
    • Example: useTaskQuery({ fn: MyTask })
  • slug: string
    • One of fn or slug are 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, runID: string) => void
    • Optional
    • Callback on successful task execution.
  • onError: (output: TOutput | undefined, error: ExecuteError, runID?: string) => 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

Options
  • fn: AirplaneFunc
    • One of fn or slug are required
    • The task to execute. This is the return value of airplane.task().
    • Example: useTaskQuery({ fn: MyTask })
  • slug: string
    • One of fn or slug are 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, an AirplaneFunc or an object of { slug?: string; fn: AirplaneFunc?; 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.
    • See refetchTasks on a mutaiton for more information.
  • onSuccess: (output: TOutput, runID: string) => void
    • Optional
    • Callback on successful task execution.
  • onError: (output: TOutput | undefined, error: ExecuteError, runID?: string) => 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

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: (sessionID: string) => void
    • Optional
    • Callback on successful runbook execution.
  • onError: (error: ExecuteError, sessionID?: string) => 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.
Note that unlike tasks, runbooks do not have outputs.
PrivacyTermsSupport