Prompts

Wait for a response from an operator before continuing
Tasks can easily gather input from operators using prompts. Each prompt contains a parameter form, similar to what you see when executing a task or runbook. When a prompt is created, a run will wait for a response before continuing. Prompts allow you to specify reviewers with with Approvals to build dynamic approval flows.
Prompts are automatically cancelled when their containing task times out which occurs after 1 hour by default.
For prompts that may take longer than 1 hour to respond to, you can extend the timeout of a standard-runtime task up to 12 hours or a workflow runtime task up to 60 days.
See Timeouts for more information.

Example: dry runs
A common use case for prompts is to perform dry-runs. Let's look at an example:
typescript
Copied
1
import airplane from "airplane";
2


3
export default airplane.task(
4
  {
5
    slug: "task_dryrun",
6
  },
7
  async () => {
8
    // Perform a dry-run and show the output to the operator with a display.
9
    const dryRun = await airplane.execute("my_task_slug", {
10
      dry_run: true,
11
    });
12
    await airplane.display.json(dryRun.output);
13


14
    // Ask the operator if we should continue.
15
    const { ok } = await airplane.prompt(
16
      { ok: "boolean" },
17
      {
18
        description: `Review the dry-run output above. If it looks correct, select OK to apply the changes.`,
19
      }
20
    );
21
    if (!ok) {
22
      await airplane.display.text("Exiting due to bad dryrun");
23
      return;
24
    }
25


26
    // If confirmed, we can re-run:
27
    const run = await airplane.execute("my_task_slug", {
28
      dry_run: false,
29
    });
30


31
    return run.output;
32
  }
33
);
If you've done UNIX scripting before, you have likely seen this pattern using the read command -- e.g.
bash
Copied
1
# perform a dry-run...
2


3
read -p "Continue? [yN] " -n 1 -r
4
echo
5
if [[ $REPLY =~ ^[Yy]$ ]]
6
then
7
    # apply!
8
fi
Compared to the classic shell script, prompts offer a few compelling advantages:
  • Notifications: Users are automatically notified when prompted.
  • Parameters: Prompts can ask for arbitrary parameters with validation.
  • Slack: Prompts can be responded to directly from Slack.

Parameters
Prompt parameters support the same configuration options as task parameters e.g. default values, descriptions, constraints, and more! See Parameters for more information about Airplane parameters.

Short text
Creates a prompt for a short text input.
typescript
Copied
1
const { email } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { email: "shorttext" }
4
);
5
// or
6
const { email } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  email: {
9
    type: "shorttext",
10
    name: "Email address",
11
    // ...
12
  },
13
});

Long text
Creates a prompt for a long text input that renders as a multi-line text area.
typescript
Copied
1
const { reason } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { reason: "longtext" }
4
);
5
// or
6
const { reason } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  reason: {
9
    type: "longtext",
10
    name: "Refund reason",
11
    // ...
12
  },
13
});

SQL
Creates a prompt for a SQL input that renders within a code editor with SQL syntax highlighting.
typescript
Copied
1
const { query } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { query: "sql" }
4
);
5
// or
6
const { query } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  query: {
9
    type: "sql",
10
    name: "SQL query",
11
    // ...
12
  },
13
});

Float
Creates a prompt for a floating point input.
typescript
Copied
1
const { cost } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { cost: "float" }
4
);
5
// or
6
const { cost } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  cost: {
9
    type: "float",
10
    name: "Amount to charge",
11
    // ...
12
  },
13
});

Integer
Creates a prompt for an integer input.
typescript
Copied
1
const { count } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { count: "integer" }
4
);
5
// or
6
const { count } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  count: {
9
    type: "integer",
10
    name: "Record count",
11
    // ...
12
  },
13
});

Boolean
Creates a prompt for a boolean input.
typescript
Copied
1
const { ok } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { ok: "boolean" }
4
);
5
// or
6
const { ok } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  ok: {
9
    type: "boolean",
10
    name: "Countinue",
11
    // ...
12
  },
13
});

Date
Creates a prompt for a date input. Dates identify a day of the year and do not include a time component. If you need that, see Datetime.
typescript
Copied
1
const { date } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { date: "date" }
4
);
5
// or
6
const { date } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  date: {
9
    type: "date",
10
    name: "Start date",
11
    // ...
12
  },
13
});

Datetime
Creates a prompt for a datetime input. If you only need a date, see Date.
typescript
Copied
1
const { timestamp } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { timestamp: "datetime" }
4
);
5
// or
6
const { timestamp } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  timestamp: {
9
    type: "datetime",
10
    name: "Incident start",
11
    // ...
12
  },
13
});

File
Creates a prompt for a File input.
typescript
Copied
1
const { photo } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { photo: "upload" }
4
);
5
// or
6
const { photo } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  photo: {
9
    type: "upload",
10
    name: "Receipt photo",
11
    // ...
12
  },
13
});

Config variables
Support for prompts with Config variables parameters is coming soon.

Examples

Multi-parameter forms
Create a multi-parameter form by specifying more than one parameter.
typescript
Copied
1
const {amount, reason} = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { reason: "shorttext" }
4
  { amount: "float" }
5
);
6
// or
7
const {amount, reason} = await airplane.prompt({
8
  // Mapping of slug -> parameter definition
9
  reason: {
10
    type: "shorttext",
11
    name: "Refund reason",
12
    // ...
13
  },
14
  amount: {
15
    type: "float",
16
    name: "Refund amount",
17
    // ...
18
  },
19
});

Confirmation
Create a prompt that has no parameters to ask users for confirmation.
typescript
Copied
1
// Convenience helper for prompts with no parameters
2
await airplane.prompt.confirm({ description: "## Please review run before continuing." });
3


4
// Equivalent to
5
await airplane.prompt({}, { description: "## Please review run before continuing." });

Select options
Create a prompt for selecting a value from a list of options. Accepts values numbers, strings, booleans, and objects.
typescript
Copied
1
const users = [
2
  { name: "Colin", id: "usr1" },
3
  { name: "Lee", id: "usr2" },
4
];
5
const user = await airplane.prompt.select("User", users, {
6
  optionToLabel: (user) => user.name,
7
});

Background prompts
Prompts can be created in the background via prompt.background. When used in combination with the Submit Prompt API endpoint, you are able to able to programatically submit prompts from outside of Airplane's runtime.
typescript
Copied
1
// Create a prompt in the background to get an ID.
2
const myPrompt = await airplane.prompt.background({ deploy_succeeded: "boolean" });
3


4
// Start a downstream processes and pass a reference to the prompt via its ID.
5
await airplane.rest.request("deploy_resource", "POST", "/startDeploy", {
6
  body: { promptID: myPrompt.promptID },
7
});
8


9
// In this case, the request from the downstream processes would look like
10
// curl https://api.airplane.dev/v0/prompts/submit \
11
//  -X POST \
12
//  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
13
//  -d '{
14
//    "id": "pmt20221122zyydx3rho2t",
15
//    "values": {
16
//        "deploy_succeeded": "true",
17
//    }
18
//}'
19


20
// Wait on the downstream process to submit the prompt via the Airplane API.
21
const { deploy_succeeded } = await myPrompt.wait();

API reference
airplane.prompt(params, opts)
params
optional
PromptInputParams

Defines the parameter form as a mapping of slug to parameter. The values will be returned as an object that maps the parameter slug to the corresponding value. To learn more about parameters, see the Parameter documentation.

For details on parameter configuration in TypeScript, see parameter configuration.

opts.reviewers
optional
{groups: string[], users: string[], allowSelfApprovals: boolean}

Optionally restrict who can submit this prompt. See Approvals.

opts.confirmText
optional
string

Text of the confirmation button on the prompt dialog.

opts.cancelText
optional
string

Text of the cancellation button on the prompt dialog.

opts.description
optional
string

Prompt description to display. Supports markdown.

PrivacyTermsSupport