JavaScript task configuration
Configure a task's metadata as code
Task configuration defines the core metadata of an Airplane task; this includes all information like
the task name and parameters aside from the actual code that is executed when the task is run.
While tasks can be initially configured in the Airplane UI, defining tasks as code is advantageous
because it allows you to reap the benefits of version control; you can view the current state of
a task and its history, subject tasks to the same code review and deploy mechanisms as the rest of
your codebase, or roll back a task to a previous commit.
If you do edit the task configuration through the UI, you can run
airplane tasks init --from your_task_slug
to sync changes back to your code configuration.Task configuration was previously accomplished using a yaml-based
task definition. This new, inline task configuration allows tasks to
be configured and developed in the same JavaScript file.
To migrate from a task definition to a single-file task configuration, run
airplane tasks init --from=my_slug
and then copy/paste the code body into the newly created
.airplane.ts
file.Writing tasks
To define a task, the JavaScript SDK provides a function
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);
Deploying this task creates an Airplane task that prints
Hello World!
when you run it.All exported calls to
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 will only discover tasks that are exported from files ending in
.airplane.js
,
.airplane.ts
, .airplane.jsx
, or .airplane.tsx
.typescriptCopied1// myTasks.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 Airplane17const mySecondTask = airplane.task(18{...},19async (params) => {...}20);
Parameters
Parameters are specified in the task configuration as objects, where the
key is the parameter
slug
and the value is the parameter configuration.typescriptCopied1parameters: {2id: {3type: "shorttext",4name: "The team's ID",5},6}
You can also shorthand parameter configuration by setting the value to the parameter type. This
defines a required parameter with
slug
and name
equal to the key.typescriptCopied1parameters: {2// The slug and name of the parater are "id".3id: "shorttext",4}
When you add parameters, you must change your implementation function to accept a
params
object.
If you are using TypeScript, The params
object is automatically typed based on your configuration!The following is a full example of an inline task with parameters:
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);
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
Field | Type | Default | Description |
---|---|---|---|
slug | string | Required | A unique identifier that ties this configuration to a task in Airplane. This cannot be changed (a different slug will end up creating a new task). Slugs must:
|
name | string | Same value as slug | A user-facing name for the task. This can be changed. |
description | string | null | A user-facing description for the task. Supports markdown. |
parameters | Parameter[] | null | Tasks can be configured with parameters that will be requested from users before they execute the task. Parameters are expressed as a mapping of slug to parameter. The values will be passed to your function as an object that maps the parameter slug to the corresponding value. For more information, see Parameter configuration. |
requireRequests | boolean | false | If true, a task must be requested before it can start executing. This disables direct execution, including schedules. |
allowSelfApprovals | boolean | true | If true, a request can be approved by the requestor. |
timeout | number (in seconds) | 3600 (1 hour) | Limits how long a task can run before it is automatically cancelled. For more information, see timeouts. |
constraints | Record<string, string> | null | Restricts this task to run only on agents with matching labels. For more information, see Run constraints. |
schedules | Record<string, Schedule> | null | A map from schedule slug to a schedule that automatically runs the task on a recurring cadence. For more information, see Schedule configuration. |
resources | string[] | Record<string, string> | null | A list of resources to attach to this task. Once attached, a resource can be used to call Built-ins. The resource's fields can also be accessed via the AIRPLANE_RESOURCES environment variable. For more information, see resource attachments. |
runtime | "standard" | "workflow" | standard | The runtime that the task is executed with. The workflow runtime is currently only supported by JavaScript tasks. For more information, see Runtimes. |
envVars | Record<string, string> | Record<string, {config: string}> | Record<string, {value: string}> | null | Environment variables that will be passed into the task. For secrets or values that are shared across multiple tasks, environment variables can load their value from config variables. |
Parameter configuration
Field | Type | Default | Description |
---|---|---|---|
type | shorttext | longtext | sql | boolean | integer | float | date | datetime | Required | Parameter type. |
name | string | Parameter slug | A human-readable name that identifies this parameter. |
description | string | null | A description that renders underneath the parameter. |
required | boolean | true | Whether a non-empty value must be provided. |
default | string | null | The initial value shown to users, also serves as the fallback if no value is provided. |
regex | RegExp | null | A regular expression to validate the provided string value. Only valid for shorttext and longtext parameters. |
options | string[] | {label: string, value: string}[] | null | If included, only values from the provided list will be accepted. An optional 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. |
Schedule configuration
Field | Type | Default | Description |
---|---|---|---|
cron | string | Required | Cron string of the schedule. To see acceptable formats, see Cron syntax. |
name | string | Schedule slug | Name of the schedule. |
description | string | null | Description of the schedule. |
paramValues | Record<string, value> | null | Map of param slug to value to pass to the task on each run. |
YAML reference (deprecated)
Task configuration was previously accomplished using a yaml-based task definition. We recommend
migrating to the new, inline task configuration allows tasks to be configured and developed in the
same JavaScript file.
To migrate from a task definition to a single-file task configuration, run
airplane tasks init --from=my_slug
and then copy/paste the code body into the newly created
.airplane.ts
file.Standard fields
The fields below apply to all task definitions, regardless of the type of task.
A unique identifier that ties this definition file to a task in Airplane. This cannot be changed (a
different slug will end up creating a new task).
Slugs must:
- Be fewer than 50 characters long
- Use only lowercase letters, numbers, and underscores
- Start with a lowercase letter
User-facing name for the task. This can be changed.
User-facing description for the task. This can be changed.
A list of parameters. Each parameter is a user-facing field to input data into the task.
Example:
yamlCopied1parameters:2- slug: name3name: Name4type: shorttext5description: The user's name.6default: Alfred Pennyworth7required: false8options:9- Alfred Pennyworth10- Bruce Wayne11regex: "^[a-zA-Z ]+$"
Unique identifier for the parameter. This is the identifier you'll use to interpolate
parameters into arguments, pass them when calling from the CLI, etc.
User-facing name for the parameter.
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 |
The type of the parameter. See Parameter types for more information.
User-facing description of the parameter.
Whether the parameter is required.
The default value of the parameter. The type depends on the type of the parameter.
Constrains the value of parameter to a list of options.
The type depends on the type of the parameter.
You can optionally add a label to each option. Labels are shown to the user instead of the value.
To add a label, the option should be an object with fields
label
and value
.Example:
yamlCopied1options:2- Alfred Pennyworth3- Bruce Wayne4- label: BW5value: Bruce Wayne
For more information, see Select options.
Allows you to more dynamically control what values are permitted.
For more information, see Regular expressions.
If true, a task must be requested before it can start executing. This disables direct execution,
including schedules.
Requiring requests will disable schedules. Any existing schedules will be paused on the next
attempted execution.
If true, a request can be approved by the requestor.
Limits how long a task can run before it is automatically cancelled.
Maximum of
43200
(12 hours)For more information, see timeouts.
Restricts this task to run only on agents with matching labels.
Example:
yamlCopied1constraints:2aws-region: us-west-2
For more information, see Run constraints.
Mapping of unique identifiers to schedules that should be deployed with the task.
For more information, see Schedules.
Example:
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
The unique identifier is used to add, update and remove schedules as changes
are made to the task definition file. Adding a new entry will create a new schedule,
modifying an entry will update the schedule and removing an entry will pause the
schedule.
The unique identifier must adhere to the slug format.
Cron string of the schedule. To see acceptable formats, see
Cron syntax.
Name of the schedule.
Description of the schedule.
Map of param slugs and values to pass to the task on each run.
Mapping of resource aliases to resource slugs. Slugs for your resource can be found in the
resource settings.
For more information on resource attachments, see resource attachments.
Example:
yamlCopied1resources:2db: prod_postgres_db
If you would like to use the resource slug as the alias for all resources passed into this task, you can also use a list shorthand:
yamlCopied1resources:2- prod_postgres_db3- prod_rest_api
Possible Values |
standard |
workflow |
The runtime that the task will execute within. Defaults to
standard
.The workflow runtime is currently only supported by JavaScript tasks. For more information, see Runtimes.
JavaScript
Marks the task as a JavaScript task.
Example:
yamlCopied1node:2entrypoint: my_task.ts3nodeVersion: "18"
The path to the
.ts
or .js
file containing the logic for this task. This
can be absolute or relative to the location of the definition file.Examples:
yamlCopied1entrypoint: my_folder/my_task.ts
Possible Values |
14 |
16 |
18 |
The version of Node.js that the task should be executed with.
This field has no effect on tasks that use the workflow runtime. For more information, see Runtimes.
Environment variables that will be passed into the task.
Environment variables can be entered directly ("from value"), or you can reference
Config variables ("from config variable"). Use config variables for secrets and/or
values you want to share across multiple tasks.
Example:
yamlCopied1envVars:2# From value3NODE_ENV:4value: production5# From config variable6MY_SECRET:7config: MY_SECRET_CONFIG_VAR