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: "Continue",
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.

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

Cancellation
Cancelling a prompt will throw an error. You can handle this error in your code to perform any cleanup or other actions.
typescript
Copied
1
try {
2
  const { amount } = await airplane.prompt(
3
    { amount: "integer" },
4
    { description: "## How much should the customer be refunded?" },
5
  );
6
} catch (err) {
7
  // import { PromptCancelledError } from "airplane";
8
  if (err instanceof PromptCancelledError) {
9
    // Handle cancellation
10
    airplane.display.text("Refund prompt was cancelled, no refund was issued.");
11
  }
12
}

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 programmatically 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();

Finding the prompt submitter
Background prompts expose a method that returns metadata about the user who submitted the prompt (if any).
typescript
Copied
1
// Create a prompt in the background
2
const myPrompt = await airplane.prompt.background({ deploy_succeeded: "boolean" });
3


4
// Wait for the prompt to be submitted
5
const { deploy_succeeded } = await myPrompt.wait();
6


7
// Get the prompt submitter
8
const { name, email } = await myPrompt.submitter();

Slack support
Airplane's Slack integration supports submitting prompts via Slack. For more information, see Slack integration.

SDK reference
See Prompt SDK reference for more information.
PrivacyTermsSupport