Scripting
input

input

Your scripting extension can ask the user for input using the built-in input object. Each interactive input method is asynchronous, which means you should prefix each call with await.

Your scripting automation action can use inputs that are passed to it using the built-in input object. Click '+ Add property' within 'Script input' and specify the keys and values of your input. Keys must be string literals, while values may use template expressions which allow you to refer to the results of previous automation steps.

textAsync
Scripting Extension only

function
async function (label: string) => Promise<string>;
Parameter nameDescription
labelA label explaining what the user should enter.

Prompts the user to enter text. It's similar to prompt() in normal JavaScript, but looks much nicer.

Example
let name = await input.textAsync('What is your name?');
output.text(`Your name is ${name}.`);

buttonsAsync
Scripting Extension only

function
async function (
label: string,
options: Array<string | {
label: string,
value?: any,
variant?: 'default' | 'danger' | 'primary' | 'secondary'
}>
) => Promise<string>;
Parameter nameDescription
labelA label explaining what the user is choosing.
optionsAn array of options for the user to choose from.

Prompts the user to choose one from a list of several options.

You can mix and match both string and object options. The function will return either the label string, or the value from the object if one is specified.

Example
let catOrDog = await input.buttonsAsync('Cats or dogs?', ['Cats!', 'Dogs!']);
if (catOrDog === 'Cats!') {
output.text('Meow');
} else {
output.text('Woof');
}
Example
let shouldContinue = await input.buttonsAsync(
'Should we delete all the records in your base?',
[
{label: 'Cancel', value: 'cancel'},
{label: 'Go for it', value: 'yes', variant: 'danger'},
],
);
if (shouldContinue === 'yes') {
output.text('I refuse!');
}
Example
let today = new Date();
let tomorrow = new Date();
tomorrow.setDate(today.getDate() + 1);
let date = await input.buttonsAsync(
'When should this event start?',
[
{label: 'Today', value: today},
{label: 'Tomorrow', value: tomorrow},
],
);
output.text(date.toDateString());

tableAsync
Scripting Extension only

function
async function (label: string) => Promise<Table>;
Parameter nameDescription
labelA label explaining which table the user should pick.

Prompts the user to choose a table from a list of all tables in the base.

Example
// prompt the user to pick a table, then show the number of records in that table:
let table = await input.tableAsync('Pick a table');
let result = await table.selectRecordsAsync({fields: []});
output.text(`There are ${result.records.length} records in '${table.name}'.`);

viewAsync
Scripting Extension only

function
async function (label: string, table: Table) => Promise<View>;
async function (label: string, tableName: string) => Promise<View>;
async function (label: string, tableId: string) => Promise<View>;
Parameter nameDescription
labelA label explaining which view the user should pick.
tableOrTableNameOrTableIdEither a Table instance or the name/id of a table in your base

Prompts the user to choose a view belonging to the table specified by tableOrTableNameOrTableId.

Example
// prompt the user to pick a view in "Projects", then show the number of records in that view:
let view = await input.viewAsync("Pick a view", "Projects");
let result = await view.selectRecordsAsync({fields: []});
output.text(`There are ${result.records.length} records in '${view.name}'.`);

fieldAsync
Scripting Extension only

function
async function (label: string, table: Table) => Promise<Field>;
async function (label: string, tableName: string) => Promise<Field>;
async function (label: string, tableId: string) => Promise<Field>;
Parameter nameDescription
labelA label explaining which field the user should pick.
tableOrTableNameOrTableIdEither a Table instance or the name/id of a table in your base

Prompts the user to choose a field belonging to the table specified by tableOrTableNameOrTableId.

Example
let field = await input.fieldAsync("Pick a field", "People");
output.text(`You picked the '${field.name}' field.'`);

recordAsync
Scripting Extension only

function
async function (
label: string,
source: Table | View | Array<Record> | RecordQueryResult,
options: {
fields?: Array<Field | string>;
shouldAllowCreatingRecord?: boolean;
},
) => Promise<Record | null>;
Parameter nameDescription
labelA label explaining what the picked record will be used for.
sourceThe source for the records to pick from. To allow picking any record in a table, a view or a record query result, pass it here directly. To limit picking from a specific list of records, pass the list instead.
optionsOptional. Options for the record picker.
options.fieldsOptional. The fields or field names/ids to include in the record cards and the returned record. The primary field will always be shown. Duplicate fields will be removed.
options.shouldAllowCreatingRecordOptional. If set to true, the user will be able to create an empty new record from the record picker.

Expands a list of records in the Airtable UI, and prompts the user to pick one.

If the user picks a record, the record instance is returned. If the user dismisses the picker, null is returned. If there are no records to pick from in the source, the picker is not shown and null is returned.

Button field
Scripting Extension only

To use your script with the "Run script" action of a button field, use recordAsync with the Table that contains the button field, or a View from that table.

When the script is run from a button, the first recordAsync call in your script will use the button's record instead of prompting the user. The record must be from the same Table, or if using a View, be visible within that view.

If the record satisfies those criteria, the prompt will be skipped and the button's record will be returned. Otherwise, a warning will be shown and the user will be prompted to pick a record.

You can use the Record picker example as a starting point for a button field script.

Example
/* Pick from a table */
let table = base.getTable("Tasks");
let record = await input.recordAsync('Pick a record', table);
if (record) {
output.text(`You picked ${record.getCellValueAsString("Description")}`);
}
Example
/* Pick from a view */
let table = base.getTable("Tasks");
let view = table.getView("Backlog");
let record = await input.recordAsync('Pick a record', view);
if (record) {
output.text(`You picked ${record.getCellValueAsString("Description")}`);
}
Example
/* Pick from a record query result */
let table = base.getTable("Tasks");
let result = await table.selectRecordsAsync({sorts: [{field: "Priority"}]});
let record = await input.recordAsync('Pick a record', result);
if (record) {
output.text(`You picked ${record.getCellValueAsString("Description")}`);
}
Example
/* Pick from a list of records */
let table = base.getTable("Tasks");
let result = await table.selectRecordsAsync({fields: ["Description"]});
let records = result.records.filter((_, i) => i % 2 == 0); // Filter out every other record
let record = await input.recordAsync('Pick a record', records);
if (record) {
output.text(`You picked ${record.getCellValueAsString("Description")}`);
}
Example
/* Options */
let table = base.getTable("Tasks");
let record = await input.recordAsync('Pick a record', table, {
fields: ["Priority"],
shouldAllowCreatingRecord: true,
});
if (record) {
output.text(`You picked ${record.getCellValueAsString("Priority")}`);
}

fileAsync
Scripting Extension only

function
async function (
label: string,
options?: {
hasHeaderRow?: boolean,
allowedFileTypes?: Array<string>
useRawValues?: boolean,
}
) => Promise<{file: File, parsedContents: any}>;
Parameter nameDescription
labelA label explaining what file being requested.
optionsOptional. Options for the file input.
options.allowedFileTypesOptional. Which file types can be imported. Like input#accept, these can be a mix of mime types and extension names, e.g. '.xlsx', 'application/json', 'image/*'. If omitted, all file types are allowed.
options.hasHeaderRowOptional. Only affects '.xls', '.xlsx', and '.csv' files. If set to true, each parsed row will be an object with keys determined from the header row. If false, each row will be arrays of strings. Defaults to false.
options.useRawValuesOptional. Only affects '.xls', '.xlsx', and '.csv' files. If set to true, the raw cell and header values will be returned as strings. If false, cell and header values will be automatically parsed (e.g. numbers will be converted from string to number type, dates will be converted to Date objects). Defaults to false.

Prompts the user to import a file.

Returns the imported File object. If the imported file is a .txt, .xls, .xlsx, .csv, .json, or .xml file, it will also attempt to parse the file and return the parsed contents.

Example
let fileResult = await input.fileAsync(
'Import a CSV file with header row',
{
allowedFileTypes: ['.csv'],
hasHeaderRow: true
}
);
output.text(`You uploaded the '${fileResult.file.name}' file.`);
output.table(fileResult.parsedContents);

config
Automations only

function
function () => Input Object;

Returns an object with all input keys mapped to their corresponding values.

Example
let inputConfig = input.config();
console.log(`The value of myKey is ${inputConfig['myKey']}.`);

config
Scripting Extension only

function
function (
settings: {
title: string,
description?: string,
items: Array<SettingsItem>
}
) => { [key: string]: Table | Field | string | number };
Parameter nameDescription
settingsSettings for your script.
settings.titleTitle of your script.
settings.descriptionOptional. Description of what your script does.
settings.itemsList of items used to generate the script settings UI.

Define the settings for the script. Users of your script can fill in these settings from the extension.

See Script settings for full details on how to use input.config().