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
async function (label: string) => Promise<string>;
Parameter name | Description |
---|---|
label | A 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.
let name = await input.textAsync('What is your name?');output.text(`Your name is ${name}.`);
buttonsAsync Scripting Extension only
async function (label: string,options: Array<string | {label: string,value?: any,variant?: 'default' | 'danger' | 'primary' | 'secondary'}>) => Promise<string>;
Parameter name | Description |
---|---|
label | A label explaining what the user is choosing. |
options | An 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.
let catOrDog = await input.buttonsAsync('Cats or dogs?', ['Cats!', 'Dogs!']);if (catOrDog === 'Cats!') {output.text('Meow');} else {output.text('Woof');}
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!');}
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
async function (label: string) => Promise<Table>;
Parameter name | Description |
---|---|
label | A label explaining which table the user should pick. |
Prompts the user to choose a table from a list of all tables in the base.
// 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
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 name | Description |
---|---|
label | A label explaining which view the user should pick. |
tableOrTableNameOrTableId | Either 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
.
// 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
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 name | Description |
---|---|
label | A label explaining which field the user should pick. |
tableOrTableNameOrTableId | Either 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
.
let field = await input.fieldAsync("Pick a field", "People");output.text(`You picked the '${field.name}' field.'`);
recordAsync Scripting Extension only
async function (label: string,source: Table | View | Array<Record> | RecordQueryResult,options: {fields?: Array<Field | string>;shouldAllowCreatingRecord?: boolean;},) => Promise<Record | null>;
Parameter name | Description |
---|---|
label | A label explaining what the picked record will be used for. |
source | The 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. |
options | Optional. Options for the record picker. |
options.fields | Optional. 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.shouldAllowCreatingRecord | Optional. 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.
/* 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")}`);}
/* 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")}`);}
/* 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")}`);}
/* 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 recordlet record = await input.recordAsync('Pick a record', records);if (record) {output.text(`You picked ${record.getCellValueAsString("Description")}`);}
/* 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
async function (label: string,options?: {hasHeaderRow?: boolean,allowedFileTypes?: Array<string>useRawValues?: boolean,}) => Promise<{file: File, parsedContents: any}>;
Parameter name | Description |
---|---|
label | A label explaining what file being requested. |
options | Optional. Options for the file input. |
options.allowedFileTypes | Optional. 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.hasHeaderRow | Optional. 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.useRawValues | Optional. 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.
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 () => Input Object;
Returns an object with all input keys mapped to their corresponding values.
let inputConfig = input.config();console.log(`The value of myKey is ${inputConfig['myKey']}.`);
config Scripting Extension only
function (settings: {title: string,description?: string,items: Array<SettingsItem>}) => { [key: string]: Table | Field | string | number };
Parameter name | Description |
---|---|
settings | Settings for your script. |
settings.title | Title of your script. |
settings.description | Optional. Description of what your script does. |
settings.items | List 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()
.