Airtable

Airtable adds an Airtable panel to each form in Forms. Each action sends the submission to a table in one of your bases, as a new record or as an update to a matching one. It runs in the background once the submission is saved, so a slow Airtable never slows the form.

It needs XPAC Forms. Without it, admins see a notice asking for it.

In Airtable's words, a base holds tables, a record is a row and a field is a column.

Connect Airtable

Test connection checks the token with Airtable and sends nothing. It says "Connected." (with the email when the token may read it) and how many of the token's bases your account can edit. Airtable doesn't report a token's scopes, so check the token has data.records:write yourself. The whole site uses this one token, and it stays visible to administrators on this screen.

Add it to a form

Open the form's Airtable panel and click Add Airtable action. A form can have several actions, each with its own on/off switch, and Forms' conditional logic can add a condition to each.

• Action: Create record always adds a record. Create or update record updates the record that matches, or adds one when none does.
• Base and Table: read from your account. A base you can only read shows as "(read only)" and can't be picked. A base, table or field you just added in Airtable can take up to 10 minutes to show. Try again appears when a list fails or is empty.
• Field mapping: pairs a Form field with the Airtable field it fills. Each list offers only fields that fit the other side, and fields Airtable works out itself, such as formulas, aren't offered. A row whose field no longer exists is flagged.
• Match records on (Create or update record only): up to three Airtable fields that must all match, each with a form field mapped to it. Pick fields that are unique, such as an email. If one is left blank in a submission, that action is skipped. If more than one record matches, Airtable refuses the update.
• Convert submitted values: on by default. Airtable converts text to each field's type, and adds select options or linked records that don't exist yet, so a free-text answer mapped to a select field adds an option. Off, an answer that doesn't already fit its field fails the whole record.
• Send numbers as numbers: Percent reads 0.75 as 75%, and Duration reads 120 as 120 seconds. Always on while Convert submitted values is off.

What goes across:

• Choice fields send the label the visitor saw, not the stored value.
• Blank answers are left out, so their cells stay empty.
• User fields take an Airtable user ID or an email address.
• Files go to attachment fields. Files up to 5 MB are uploaded. Bigger ones are sent as a link that Airtable downloads, which only works when Airtable can reach your site. If it can't, the record is still sent and a note says the cell is probably empty. A file kept private by Keep uploaded files private (XPAC → Forms → Settings) can't go as a link, so one over 5 MB is left out and a note names it for you to add by hand. A file field mapped to a field that doesn't take files is left out, with a note.

When a send fails

Each result is on XPAC → Forms → Deliveries and in the submission's own Deliveries row:

• Waiting: queued, or waiting for its next try.
• Delivered: sent. Notes say what was left out, if anything.
• Failed: not sent. The error names the action and says why.
• Skipped: nothing to send, for example because a match field was left blank.
• Dismissed: you dismissed it, or the submission is in spam or the trash.

Timeouts, rate limits and server errors are tried again after 1, 5, 30 and 120 minutes, five tries in all. Other errors, such as a revoked token or a missing table, fail at once. Each action that went through is marked done, so a retry sends only the ones that didn't.

Retry now sends a failed or dismissed delivery again with the form's current settings and the token saved now, so fix the cause first. If you save a different token while submissions are waiting, they fail with a message that the account changed, and Retry now sends them with the new token. Retry works for 30 days after the submission. After that, its answers are no longer kept.

After 5 failed submissions in a row on one form, Airtable pauses on that form. Rate limits and errors about one submission's data don't count. While it's paused, new submissions are saved but show as Failed, XPAC still tries one an hour, and the first one that goes through ends the pause. The site admin gets one email when it pauses, and Deliveries shows the pause with a Resume and retry button that resumes and sends the failed submissions again.

Two cases need a look in Airtable before you retry:

• For an action with files, if Airtable doesn't confirm the record or a file, the delivery fails and asks you to check the table. Retry won't send it again.
• For an action without files, if Airtable's reply is lost after it created the record, a retry can add a duplicate. Create or update record avoids this when its match fields are unique.

For developers

Filters:

• xpac_airtable_typecast: whether Airtable converts values. Defaults to the action's Convert submitted values. Return false to turn it off for every action.
• xpac_airtable_upload_attachments: return false to send every file as a link.
• xpac_airtable_site_is_fetchable: return true or false to say whether Airtable can reach this site, for example behind a reverse proxy.
• xpac_airtable_request_timeout: seconds to wait for Airtable. Default 10.
• xpac_airtable_upload_timeout: seconds for a file upload. Default 30 plus 10 per started MB.
• xpac_airtable_max_rate_limit_wait: longest wait, in seconds, for Airtable's rate limit before the delivery is retried later. Default 30.

Each form stores its actions under airtable.items in its settings. An action has status, action (createRecord or upsertRecord), baseId, tableId, map (rows of local form field name, remote Airtable field ID and remoteType Airtable field type), mergeOn (Airtable field IDs), typecast, nativeNumbers and an optional title. A row written without remoteType is sent as older versions sent it. Signatures are in the Airtable hook reference.