Work with IntuiFace & Airtable

Table of Contents

    Introduction

    Airtable is Web-based third-party software positioned as a "human-friendly database". Among other uses, Airtable can be an excellent cloud-hosted content management system for IntuiFace experiences thanks to IntuiFace API Explorer.

    This article covers all the methods for reading and writing between an IntuiFace experience and an Airtable "base".

    Throughout the article we use this photo gallery base as an example:

    Webinar-base.jpg

    Airtable API documentation

    About Airtable API documentation

    Once you have created your Airtable base, you should view its API documentation to determine which request you need to enter within the API Explorer. Airtable API documentation is dynamic and will adjust to reflect your base and the tables it contains. All of the snapshots below are from the Webinar Gallery Photos base and its PhotoList table.

    Accessing the documentation

    When logged into your base, click the help icon in the top right corner of the page, then click API Documentation:

    help_access.jpg

    Next, choose the particular table you're interested in. For this example our objective will be to retrieve photos found in the Photolist table.

    Here is the table for which we'll need API documentation:

    Photolist-Tab.jpg

    And here is the associated documentation page:

    Photolist_table_help_page.jpg

    IMPORTANT: All Airtable API requests need to be authenticated. To make things easier, check the Show API key checkbox to make sure all requests in the documentation can be directly copied / pasted in the API Explorer.

    show_api_key.png

    Using IntuiFace API Explorer with Airtable

    Display all content in a table

    To display all table contents in your IntuiFace experience, use the list records option. Select the "List records" option in the left nav bar. The curl statement in the right panel is what you would enter into API Explorer - i.e. it is your request URL.

    ListRecords.jpg

    Optionally:

    • Remove the maxRecords parameter in the curl statement to eliminate a limit on the number of items retrieved.
    • Keep the view parameter to ensure you get table items in the same order as you see them in your Airtable view. The value of the view parameter is the name or ID of a table view you've created.

    API_Explorer_List_records.jpg

    By default, even if you remove the maxRecords parameter, Airtable will only send up to 100 records in a request response. If you have more than 100 items in your table, see the pagination paragraph below.

    Refresh already-displayed content

    When using a REST-based Web Service Interface Asset to load content via a Web API, the content is loaded once, when starting the experience. If you need to refresh it, either on a user action or regularly, you need to call the Interface Asset's Refresh action. The retrieved content will not refresh on its own.

    You can use any trigger to call this action, such as a button press, a timer, a scheduler or even an external trigger.

    Refresh.jpg

    Filter content before displaying it

    Filtering content within an Airtable request is achieved by adding the filterByFormula parameter in the List records request URL. You can read more about Airtable formulas in their documentation but we will give you some examples below.

    Objective: Only display photos from a specific collection. Ex: Vintage Cars

    First, you need to add this collection parameter to your request.

    • Edit your Interface Asset in API Explorer. Edit_in_API_Explorer.jpg
    • Add the filterByFormula parameter with a default value. In our sample, we will use {Collection}="Vintage Cars", where Collection is the field name we want to use to filter the records, and Vintage Cars is the value to use within this filter. Filter.jpg

    Then, to let a user dynamically change the filter value, you can call the Set filterByFormula action on the Interface Asset from any trigger (ex: a button). It can either be:

    • a static value, ex: {Collection}="African Wildlife" FilterAction-Static.jpg
      OR
    • a dynamic value, using binding to retrieve that value from user input (e.g. from a Text Input asset), and then using the Enclose operation of the Text Manipulation binding converter. Filter_Binding_Converter.jpg

    To remove a filter, you need to call the Set filterByFormula action with an empty parameter.

    Search text fields for a specific string

    To identify records where a particular text field contains specific text, the value of the filterByFormula parameter should be set to {FieldName}="value".

    This formula will return records where the FieldName property is strictly equal to the passed value. NOTE: The entire formula is case sensitive.

    Ex: {Collection}="African Wildlife"

    To create a case insensitive formula, you need to convert both the field and value content to lower case strings, using the following formula: LOWER({FieldName})=LOWER("value").

    Search text fields for a substring

    To identify records where a particular text field contains text anywhere in their value, the value of the filterByFormula parameter should be FIND("value", {FieldName}) > 0.

    This formula will return all records where the FieldName property contains the passed value. NOTE: The entire formula is case sensitive.

    Ex: FIND("Vintage", {Collection}) > 0

    To create a case insensitive formula, you need to convert both the field and value content to lower case strings, using the following formula: `FIND(LOWER("value"), LOWER({FieldName})) > 0

    Search numeric fields for amounts more or less than a specific value

    To identify records where a particular numeric field contains a number more than a specified value, the value of the filterByFormula parameter should be set to {FieldName}>"value".

    This formula will return all records where the FieldName parameter contains a number greater than value.

    Ex: {Creation Date}>"1992"

    Conversely, to identify records for whom a particular numeric field contains a number less than a specified value, the value of the filterByFormula parameter should be set to {FieldName}<"value".

    Sort items

    Sorting items returned by an Airtable request is achieved by adding two parameters to the List records request:

    • sort[0][field]: the field to use for sorting.
    • sort[0][direction]: the direction for sorting, can be asc for ascending or desc for descending.

    Example with the PhotoList table:

    sort[0][field] = Price
    sort[0][direction] = asc

    Sort.jpg

    To enable a user to dynamically change the field used to sort records or the direction of the sorting, you can call the Set sort[0][field] or Set sort[0][description] action with a new value for the parameter.

    Calling the Set sort[0][field] with an empty parameter will remove the sorting and present the records in the way they are ordered in the view you are using in your request.

    Sort_action.jpg