Unit 3

Scripts Workshop

Guided challenges on Airtable scripts. Read a line, find what breaks, and choose between a script and native actions. The terms are defined on the Module 3 overview.

Challenge: Read the Line

Part of each line is explained. Answer the question about the rest

Question:

const { invoiceId, clientEmail } = input.config();

input.config() is a method call. It returns an object with one property for each input variable configured on the script action.

What does const { invoiceId, clientEmail } = do with that object?

This is destructuring. The curly braces on the left name the properties to read from the object, and each one becomes a variable.

The object returned by input.config() isn’t changed. The line reads from it.

Input variables are configured on the script action in the automation editor. A script can read them and can’t create them.

Arguments go inside the parentheses of a call. The parentheses of input.config() are empty.

The answer: Declares two variables, invoiceId and clientEmail, and assigns each one the value of the property with the same name.

This is destructuring. The curly braces on the left name the properties to read from the object, and each one becomes a variable.

const invoicesTable = base.getTable("Invoices");

base.getTable("Invoices") calls the getTable method on the base object, with the string "Invoices" as its argument.

What does that call return?

getTable doesn’t load records. Records are loaded by a later call on the Table object, such as selectRecordAsync.

The Table object has methods for loading and changing records. Later lines call those methods on invoicesTable.

getTable returns a table that already exists in the base. It doesn’t create one.

"Invoices" is the argument passed in. The return value is a Table object.

The answer: A Table object that represents the Invoices table. No records have been loaded.

The Table object has methods for loading and changing records. Later lines call those methods on invoicesTable.

const invoice = await invoicesTable.selectRecordAsync(invoiceId);

selectRecordAsync is an asynchronous method. It returns a Promise.

What does the await keyword do?

Without await, the Promise itself would be assigned to invoice. With it, the script waits and invoice is assigned the Record object.

Lines still run in order. await makes the script wait on this line before it continues to the next.

await doesn’t retry. If the call fails, the script throws an error on this line.

Without await, invoice is assigned a Promise, and the method calls on later lines throw errors.

The answer: Pauses the script until the Promise resolves, then produces the Record object, which is assigned to invoice.

Without await, the Promise itself would be assigned to invoice. With it, the script waits and invoice is assigned the Record object.

const clientId = invoice.getCellValue("Client")[0].id;

Client is a linked record field. invoice.getCellValue("Client") returns an array of objects, one for each linked record. Each object has an id property and a name property.

What does [0] do?

[0] is the element at position 0. .id then reads the id property of that element.

[0] is applied to the array returned by getCellValue. The client’s name is in the name property of each element.

This line doesn’t call any method on the Clients table. It reads the Client field of the record stored in invoice.

[0] reads a value. It doesn’t change the array or the field.

The answer: Accesses the first element of that array. Array positions start at 0.

[0] is the element at position 0. .id then reads the id property of that element.

const message = `Invoice ${number} is due ${dueDate}`;

The value of number is "INV-204" and the value of dueDate is "March 3". Text inside backticks is a template literal, and each ${ } is a placeholder.

What string is assigned to message?

That would be the result with regular quotes. Inside a template literal, each placeholder is replaced.

Each placeholder is replaced with the value of the variable inside it.

A placeholder is replaced with the variable’s value, not the variable’s name.

The answer: Invoice INV-204 is due March 3

Each placeholder is replaced with the value of the variable inside it.

output.set("reminderText", message);

set is a method on the output object. This call passes two arguments: the string "reminderText" and the variable message.

What does the call do?

Updating a field takes a call to updateRecordAsync on a Table object. output.set doesn’t change records.

output.set doesn’t send anything. A later action in the automation sends the message.

The first argument is the output’s name and the second is its value. The output appears in the configuration of later actions.

The answer: Creates an output named reminderText whose value is the value of message. Later actions in the automation can use it.

The first argument is the output’s name and the second is its value. The output appears in the configuration of later actions.

Challenge: What Breaks

Each script has one mistake. Work out what value or error it produces

Question:

The script action has one input variable, named OrderID.

Input variables on the script action

OrderID Record ID, from the trigger

const { orderId } = input.config();

input.config() returns an object with one property, OrderID.

What value is assigned to the variable orderId?

Property names are case-sensitive. OrderID and orderId are different names.

Destructuring a property that doesn’t exist assigns undefined. The script continues and fails on a later line that uses orderId.

Airtable doesn’t check the variable names in the script against the input variables. The mismatch appears only when the script runs.

The answer: undefined, because the object has no property named orderId.

Destructuring a property that doesn’t exist assigns undefined. The script continues and fails on a later line that uses orderId.

const order = ordersTable.selectRecordAsync(orderId);
const item = order.getCellValueAsString("Item");

selectRecordAsync returns a Promise. The first line assigns its return value to order without await.

What happens on the second line?

Adding await before the call makes the script wait for the Promise to resolve, and order is then assigned the Record object.

The second line runs immediately. At that point order is a Promise, not a Record object.

selectRecordAsync is called once. The error comes from calling a Record method on a Promise.

The answer: It throws an error. order is a Promise, and a Promise has no getCellValueAsString method.

Adding await before the call makes the script wait for the Promise to resolve, and order is then assigned the Record object.

await ordersTable.updateRecordAsync(orderId, { "Notifed": true });

The second argument is an object. Each of its property names must be the name of a field in the table. The Orders table has a checkbox field named Notified, and this object’s property is named Notifed.

What does the call do?

A script can’t create a field by writing to it. Property names must match fields that exist.

Field names are matched exactly.

Field names are strings, so nothing checks them until the call runs.

The answer: Throws an error, because the table has no field named Notifed. No record is updated.

Field names are strings, so nothing checks them until the call runs.

const customerId = order.getCellValue("Customer").id;

Customer is a linked record field with one linked record. order.getCellValue("Customer") returns an array containing one object. This line reads the id property on the array.

What value is assigned to customerId?

An array with one element is still an array. The id property is on the element.

Reading a property that doesn’t exist produces undefined. [0].id reads the id of the first element.

Reading .id on the array doesn’t read it on each element.

The answer: undefined, because an array has no id property. The id property is on the element at [0].

Reading a property that doesn’t exist produces undefined. [0].id reads the id of the first element.

const customer = order.getCellValue("Customer");
const message = `${customer}: order ready`;

getCellValue("Customer") returns an array containing one object. A template literal converts the value in each placeholder to a string.

What string is assigned to message?

getCellValue returns an array of objects for a linked record field. getCellValueAsString("Customer") returns the name as a string.

Converting an object to a string produces [object Object]. To get the name as a string, call getCellValueAsString("Customer").

The record ID is in the id property of the element. The placeholder contains the whole array.

The answer: [object Object]: order ready

Converting an object to a string produces [object Object]. To get the name as a string, call getCellValueAsString("Customer").

The script action has one input variable, named orderId. The Orders table has a field named Customer Name.

Input variables on the script action

orderId Record ID, from the trigger

const { orderId, customerName } = input.config();
const message = `${customerName}: order ready`;

What string is assigned to message?

Native actions can use any field from the trigger record. A script receives only the input variables configured on the script action.

customerName is assigned undefined, and the template literal converts undefined to the string undefined.

Input variables are added by hand in the automation editor.

The answer: undefined: order ready, because the object returned by input.config() has no customerName property.

customerName is assigned undefined, and the template literal converts undefined to the string undefined.

Challenge: Script, Native Actions, or Extension

Read the trigger and the requirement, then choose what to build it with

Question:

Trigger: When a form is submitted.
Requirement: Send an email to the address in the submitted record.

Which should this be built with?

One trigger and one Send an email action. The automation has no records to iterate over and nothing to calculate.

A script would do what one native action does, and the automation would be harder for someone else to maintain.

The Scripting extension runs when a user clicks Run. This has to run on every form submission.

The answer: Native automation actions

One trigger and one Send an email action. The automation has no records to iterate over and nothing to calculate.

Trigger: At a scheduled time, daily.
Requirement: Call a project management app’s API, then create a record for each returned task whose ID is not already in the table.

Which should this be built with?

This requires an API call, iterating over the returned tasks, and checking each ID against existing records. Native actions can’t do that.

The script calls the API with fetch, iterates over the returned tasks, and creates the missing records. The scheduled trigger runs it daily.

A user would have to open the base and click Run every day.

The answer: A “Run a script” action in an automation

The script calls the API with fetch, iterates over the returned tasks, and creates the missing records. The scheduled trigger runs it daily.

A one-time migration.

Requirement: Split a Clients table into a Companies table and a Contacts table, and link each contact record to its company record.

Which should this be built with?

This iterates over a whole table and creates linked records in two others. It also runs once, so it doesn’t need a trigger.

An automation is for work that repeats. A migration runs once, started by a person.

The Scripting extension is for one-time jobs that a user runs by hand.

The answer: The Scripting extension

The Scripting extension is for one-time jobs that a user runs by hand.

Trigger: When a record is created in the Leads table.
Requirement: Assign the lead to the sales rep with the lowest count of open leads.

Which should this be built with?

This requires counting the open leads for each rep and comparing the counts on every run.

The script loads the open leads, counts them per rep, and assigns the new lead to the rep with the lowest count.

Leads would stay unassigned until a user clicked Run.

The answer: A “Run a script” action in an automation

The script loads the open leads, counts them per rep, and assigns the new lead to the rep with the lowest count.

Trigger: When a record matches conditions (Status is Won).
Requirement: Create a record in the Projects table and send a Slack message. The automation will be maintained by a client who doesn’t read code.

Which should this be built with?

A Create record action and a Slack action cover the requirement, and the client can open the automation and read each action’s configuration.

It would work, and the client would have to maintain code they can’t read for something two native actions do.

This has to run every time a deal is won, without a user clicking Run.

The answer: Native automation actions

A Create record action and a Slack action cover the requirement, and the client can open the automation and read each action’s configuration.

Trigger: When a record is created in the Payments table.
Requirement: Allocate the payment amount across the customer’s open invoices, in order of oldest due date, until the amount is used up.

Which should this be built with?

Allocating one amount across several records in order, and stopping when it is used up, requires a loop and arithmetic.

The script loads the open invoices, sorts them by due date, and updates each one until the amount is used up.

Payments keep being created. Each one would wait for a user to click Run.

The answer: A “Run a script” action in an automation

The script loads the open invoices, sorts them by due date, and updates each one until the amount is used up.

A one-time audit.

Requirement: Produce a list of every record in the base that has an empty required field.

Which should this be built with?

This reads every record in the base and produces one list. An automation acts on the record that triggered it.

Nothing needs to run repeatedly. The list is needed once.

An audit is a one-time job run by hand, and the extension displays its output in its own panel.

The answer: The Scripting extension

An audit is a one-time job run by hand, and the extension displays its output in its own panel.