JavaScript task configuration
airplane tasks init --from=my_slug
and then copy/paste the code body into the newly created
.airplane.ts
file.Writing tasks
airplane.task(...)
, which takes two parameters: the task configuration and the task
implementation.typescriptCopied1// my_task.airplane.ts2import airplane from "airplane";34export default airplane.task(5// Task configuration6{7slug: "my_task",8name: "My Task",9description: "This is my task defined entirely in TypeScript!",10},11// Task implementation12async () => {13console.log("Hello World!");14},15);
Hello World!
when you run it.airplane.task(...)
will be discovered as tasks. You can even define multiple
tasks in the same file by using either the default or named exports for each of your tasks..airplane.js
,
.airplane.ts
, .airplane.jsx
, or .airplane.tsx
.typescriptCopied1// my_tasks.airplane.ts2import airplane from "airplane";34// Discoverable by Airplane5export default airplane.task(6{...},7async (params) => {...}8);910// Discoverable by Airplane11export const mySecondTask = airplane.task(12{...},13async (params) => {...}14);1516// NOT discoverable by Airplane because it isn't exported.17const mySecondTask = airplane.task(18{...},19async (params) => {...}20);
airplane deploy
, Airplane imports your task files to discover tasks. If you have any
code outside of the task implementation function (including code that is imported), this code will
also be executed. This allows you to define helper functions, constants, or other code that is
shared across tasks, but may also cause unexpected behavior if the code has side effects.typescriptCopied1// my_tasks.airplane.ts2import airplane from "airplane";34// You can share code between tasks by defining it outside of the task implementation function.5const getAirplaneTaskName = (slug) => `Airplane task ${slug}`;67// But be careful! This code will be executed when you run `airplane deploy`.8makeApiCall();910export default airplane.task(11{ slug: "my_task", name: getAirplaneTaskName("my_task") },12// Task implementation13async () => {14console.log("Hello World!");15},16);
Parameters
slug
and the value is the parameter configuration.typescriptCopied1parameters: {2id: {3type: "shorttext",4name: "The team's ID",5},6}
slug
and name
equal to the key.typescriptCopied1parameters: {2// The slug and name of the parater are "id".3id: "shorttext",4}
params
object.
If you are using TypeScript, The params
object is automatically typed based on your configuration!typescriptCopied1// my_task.airplane.ts2import airplane from "airplane";34export default airplane.task(5// Task configuration6{7slug: "my_task",8name: "My Task",9description: "This is my task defined entirely in JavaScript!",10parameters: {11// Required integer param with slug "my_int_param" and name "my_int_param"12my_int_param: "integer",13// Optional shorttext param with slug "my_optional_text_param" that defaults to "Hello!"14my_optional_text_param: {15type: "shorttext",16name: "My optional text param",17required: false,18default: "Hello!",19options: ["Hello!", "Good morning!"],20},21},22},23// The function takes a single argument, `params`, which is an object with the two params.24// e.g. { my_int_param: 3, my_optional_text_param: "Hello!" }25async (params) => {26console.log(`${params.my_optional_text_param}, ${params.my_int_param}`);27},28);
Examples
Attach a resource to a task and create a schedule
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "my_task",6parameters: {7text: "shorttext"8},9resources: {10// Attach the resource with slug "backend_db" under the alias "db"11db: "backend_db"12},13schedules: {14// Create a schedule for this task that runs at midnight each day15midnight_daily: {16cron: "0 0 * * *",17name: "Midnight daily",18description: "Runs at midnight each day",19paramValues: {20text: "text param value"21}22}23}24},25async (params) => {...}26);
Manage granular task permissions in code
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "my_task",6permissions: {7viewers: { groups: ["support"] },8executers: { users: ["jordan@airplane.dev"] },9},10},11async (params) => {...}12);
Pass environment variables to a task and set label constraints for self-hosted agents
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "my_task",6envVars: {7// Pass an env var with a value8MY_ENV_VAR: "MY_ENV_VAR_VALUE",9// Pass an env var from a defined config var10MY_CONFIG_ENV_VAR: {config: "MY_CONFIG_ENV_VAR_VALUE"}11},12// Run only on agents with label "region:us-west-2"13constraints: {14region: "us-west-2"15}16},17async () => {...}18);
Require requests for task execution and set a custom timeout
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "my_task",6// Set a timeout of 200 seconds7timeout: 200,8// Require requests to execute9requireRequests: true,10allowSelfApprovals: false11},12async () => {...}13);
Reference
Task configuration
- Be fewer than 50 characters long.
- Use only lowercase letters, numbers and underscores.
- Start with a lowercase later.
A user-facing name for the task. This can be changed.
A user-facing description for the task. Supports markdown.
If true, a task must be requested before it can start executing. This disables direct execution, including schedules.
If true, a request can be approved by the requestor.
The restrict callers execute rule disables direct execution of a task in the web UI and hides the task in the library. This rule can be configured to allow the task to be called from other tasks/runbooks and views.
AIRPLANE_RESOURCES
environment variable. For more information, see resource attachments.The implementation of the task.
Parameter configuration
A human-readable name that identifies this parameter.
A description that renders underneath the parameter.
Whether a non-empty value must be provided.
If a value is not provided for this parameter, the default value will be used instead.
shorttext
and longtext
parameters.A validation function that returns a string if the value is invalid, or null
if the value is valid. The function is evaluated as a JS template and can refer to other parameters by using the params
keyword.
label
can be provided for each option to override how these options are rendered in forms. Only valid for shorttext
, longtext
, sql
, integer
, float
, date
, and datetime
parameters. The values can either be hardcoded, or can be dynamically generated by a task by providing a slug
and optional params
. For more information, See Task-backed select options for more information.An expression that hides the param if it evaluates to a truthy value. The expression is evaluated as a JS template and can refer to other parameters by using the params
keyword.
Schedule configuration
Name of the schedule.
Description of the schedule.
Map of param slug to value to pass to the task on each run.
Permissions configuration
Groups and users who can see task information, but can't request or execute tasks.
Groups and users who have all the permission of viewers, and can also request tasks.
Groups and users who have all the permissions of requesters, and can also execute tasks and other's requests.
Groups and users who have full access to the task, and can change task configurations and permissions.
Output display configuration
Code
Code is a syntax-highlighted code block.
Indicates that the output should be displayed as a code block.
Language to use for syntax highlighting.
Description list
Description list is a list of term and description pairs (aka key and value pairs).
Indicates that the output should be displayed as a description list.
Value of the display.
The value should be a JST that evaluates to the expected format of a description list, which is a list of objects with term
anddescription
fields. The JST can reference the output of the task.
File
File is a file preview. File requires the output to be an Airplane file.
Indicates that the output should be displayed as a file preview.
JSON
JSON is a syntax-highlighted JSON block.
Indicates that the output should be displayed as a JSON block.
Statistic
Statistic is a simple display designed to prominently display quantifiable metrics so that users can easily discern key information at a glance.
Indicates that the output should be displayed as a statistic block.
Value of the display.
The value can be a JST that can reference the output of the task. If not set, the value will be the output of the task.
Label of the display.
The label can be a JST that can reference the output of the task.
Sublabel of the display.
The sublabel can be a JST that can reference the output of the task.
Table
Table is a rich, interactive table.
Indicates that the output should be displayed as a table.
Value of the display.
The value should be a JST that evaluates to the expected format of a table, which is a list of objects with fields corresponding to the columns. The JST can reference the output of the task. If not set, the value will be the output of the task.
Columns of the table.
label
is what's displayed as the column header. accessor
indicates which field of the table value should be used for this column. If not set, the columns will be inferred from the output of the task.
Text
Text is component that displays plain text. Text also supports Markdown formatting.
Indicates that the output should be displayed as text.
Value of the display.
The value can be a JST that can reference the output of the task. If not set, the value will be the output of the task.
YAML reference (deprecated)
airplane tasks init --from=my_slug
and then copy/paste the code body into the newly created
.airplane.ts
file.Standard fields
- Be fewer than 50 characters long
- Use only lowercase letters, numbers, and underscores
- Start with a lowercase letter
yamlCopied1parameters:2- slug: name3name: Name4type: shorttext5description: The user's name.6default: Alfred Pennyworth7required: false8options:9- Alfred Pennyworth10- Bruce Wayne11regex: "^[a-zA-Z ]+$"
Possible Values |
shorttextYour commonly used string input |
longtextA string, but with a larger input box for users |
sqlSimilar to Long Text inputs but offer SQL syntax highlighting |
booleanPresented as on/off toggles |
uploadAllows users to upload a file |
Show more |
label
and value
.yamlCopied1options:2- Alfred Pennyworth3- Bruce Wayne4- label: BW5value: Bruce Wayne
43200
(12 hours)yamlCopied1constraints:2aws-region: us-west-2
yamlCopied1schedules:2my_first_schedule:3cron: 0 0 * * *4name: My First Schedule5description: This is my first daily midnight UTC schedule!6paramValues:7my_first_param: my_first_param_value
yamlCopied1resources:2db: prod_postgres_db
yamlCopied1resources:2- prod_postgres_db3- prod_rest_api
Possible Values |
standard |
workflow |
standard
.yamlCopied1permissions: "team_access"
yamlCopied1permissions:2viewers:3groups:4- customer_success5users:6- success@airplane.dev7requesters:8groups:9- support10users:11- support@airplane.dev12executers:13groups:14- devs15admins:16groups:17- team_admins
Possible Values |
task-viewersAnyone who can view the task can also view the run. |
task-participantsCan only be viewed by those who execute, request, or approve the run. |
JavaScript
yamlCopied1node:2entrypoint: my_task.ts3nodeVersion: "18"
.ts
or .js
file containing the logic for this task. This
can be absolute or relative to the location of the definition file.yamlCopied1entrypoint: my_folder/my_task.ts
Possible Values |
14 |
16 |
18 |
20 |
yamlCopied1envVars:2# From value3NODE_ENV:4value: production5# From config variable6MY_SECRET:7config: MY_SECRET_CONFIG_VAR