Migrate Runbooks to Tasks
Learn how Tasks compare to Runbooks
Since Runbooks were launched, a number of new Tasks features have
shipped that bring Tasks to parity with Runbooks. Any operation that can be expressed with a Runbook
can now be expressed with a Task!
Runbooks vs. Tasks
Runbooks vs. Tasks
Tasks are best optimized for developers since they can be used to express orchestration-heavy
processes as code. This offers a number of advantages:
- Control flow is expressed with familiar language constructs such as
if
statements,for
loops, and branches. Runbooks do not support looping and only support limited forms of branching through start conditions. - Tasks can be managed as code and automatically deployed.
- Tasks can make decisions dynamically, such as conditionally requiring approvals.
- Task code can be reused and executed from within other tasks.
To get started writing Runbook-like operations as Tasks, see the following guide:
While Tasks are optimized for developers who are familiar with programming, Runbooks are optimized
for quickly building operations from the Airplane UI. This is the area where Runbooks are an
improvement over Tasks. If that is what you are looking for, we recommend you continue to use
Runbooks!
How to migrate
How to migrate
The tooling for converting runbooks to tasks is currently in beta and currently only supports
generating JavaScript tasks. We'd love to hear any feedback or requests at
hello@airplane.dev.
The Airplane CLI provides a way to convert existing
runbooks to inline JavaScript Tasks.
Migrating runbook features to task features
Migrating runbook features to task features
You can convert a Runbook to a Task by running:
bashCopied1airplane tasks init --from-runbook MY_RUNBOOK_SLUG
The CLI will create a new Task and attempt to translate each Runbook block to its equivalent Task
code:
Runbooks | Tasks |
---|---|
Replace Task blocks... | ...with the Task execution SDK |
Replace Built-in blocks... | ...with Built-in SDK methods |
Replace Form blocks... | ...with Prompts |
Replace Note blocks... | ...with Text displays |
Replace Start conditions... | ...with native if statements |
These Runbook global variables can be
replaced with the following runtime environment variables:
Runbook Global | Task Environment Variable |
---|---|
Replace session.id | ...with process.ENV.AIRPLANE_RUN_ID |
Replace session.url | ...with process.ENV.AIRPLANE_RUN_URL |
Replace session.creator.id | ...with process.ENV.AIRPLANE_RUNNER_ID |
Replace session.creator.email | ...with process.ENV.AIRPLANE_RUNNER_EMAIL |
Replace session.creator.name | ...with process.ENV.AIRPLANE_RUNNER_NAME |
Replace runbook.id | ...with process.ENV.AIRPLANE_TASK_ID |
Replace runbook.url | ...with process.ENV.AIRPLANE_TASK_URL |
Replace runbook.name | ...with process.ENV.AIRPLANE_TASK_NAME |
Replace env.id | ...with process.ENV.AIRPLANE_ENV_ID |
Replace env.slug | ...with process.ENV.AIRPLANE_ENV_SLUG |
Replace env.name | ...with process.ENV.AIRPLANE_ENV_NAME |
Replace env.is_default | ...with process.ENV.AIRPLANE_ENV_IS_DEFAULT |
Example
Example
A Runbook that looks up a user in a database and sends a slack message based on the SQL results.


The equivalent task code:
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "lookup_user",6name: "Lookup user (task)",7parameters: { email: { name: "Email", slug: "email", type: "shorttext" } },8resources: ["demo"],9},10async (params) => {11const lookup = await airplane.sql.query<any>(12"demo",13"select id, name, email from users where email like :email;",14{15args: { email: `%${params.email}%` },16},17);1819if (lookup.output.Q1.length > 0) {20await airplane.slack.message(21"test-noise",22`Found user: *${lookup.output.Q1[0].name}* who can be reached at *${lookup.output.Q1[0].email}*.`,23);24} else {25console.log("Skipping over 'slack_found' because startCondition is false");26}2728if (lookup.output.Q1.length === 0) {29await airplane.slack.message(30"test-noise",31`Searched for a user named ${params.name} No user found.`,32);33} else {34console.log("Skipping over 'slack_not_found' because startCondition is false");35}36},37);
Limitations
Limitations
- Only inline JavaScript Tasks are supported
- Config and file parameter types in code are still under development