Airtableのインテグレーション

Retoolは、GraphQLを使用した場合はBaseQL経由で、SQLを使用した場合はSync Inc経由でAirtableに接続できます。AirtableのREST APIの使用に関するドキュメントは近日追加する予定です。

BaseQL経由での接続

注意: BaseQLはAirtable Pro Planでのみ利用可能です。

最初に、Airtable MarketplaceからBaseQLをインストールする必要があります。marketplaceタブに移動し、BaseQLを検索します。

BaseQLをインストールしたら、Retool内で照会および使用したいAirtableベースに移動します。ここには、Retool内で使用するSharks(Shark Tankから引用)のベースが一覧表示されています。

右側の「Apps」をクリックしてBaseQLを選択します。

まず、Airtable APIキーを取得する必要があります。画面右上のご自分のアカウントのアイコンをクリックします。

このアカウントはまだAPIキーを取得していないため、「Generate API Key」ボタンで作成する必要があります。

このAPIキーをクリップボードにコピーしたら、ベースに戻り、BaseQLのAPIキー・フィールドにペーストします。BaseQLには2つのオプションがあります。インラインのIDEを使用してクエリーを作成するか(「GraphQL Explorer」)、直接BaseQLアプリケーションを開いてそこにクエリーを作成することができます。いずれの場合も、BaseQLがサーバーに作成するエンドポイントを確認する必要があります。エンドポイントは、以下のようになります。

https://api.baseql.com/airtable/graphql/appb5EQO5dqP1YdprX

これがRetool内で照会されるエンドポイントです。

Retoolアプリケーションを開いて(お持ちでない場合はアカウントを作成して)、画面の下部にあるクエリー・エディターに移動し、「+ new」ボタンで新しいクエリーを作成します。ドロップダウンから「GraphQL」を選択し、上記のエンドポイントを「URL」フィールドにペーストします。これで次に進むことができます。

BaseQL Airtableの基本的なクエリー

Sharksの例に戻りましょう。以下に、ベースの一部のデータを取り込む単純なGraphQLクエリーを示します。

query {
  sharks {
    sharkName
    sharkNumber
    sharkImage
    biography
  }
}

Previewをクリックすると、GraphQLから正しいJSONフォーマットでデータが返されていることが分かります。

データをテーブルに取り込むには、{{ AirtableQuery.data.sharks }}を参照します。

Sync Inc経由での接続

Airtableの設定

このチュートリアルでは、Airtableのcustomer success managementテンプレートを使用します。このベースを例にとると、Airtableがすべての顧客データや関係をどのように管理するのかがよく分かります。しかし、より細かいワークフローやアクセス許可が必要な場合は、Airtableの利用に限界があることも分かります。ここでRetoolの出番です。

まず、Airtableのcustomer success managementテンプレートをAirtableのワークスペースに追加します。

  1. Airtableのワークスペースにログインし、customer success managementテンプレートを新しいタブで開きます。

  2. Use Templateボタンをクリックして、customer success managementテンプレートをワークスペースに追加します。

Sync Incの設定

Sync Incを利用して、Airtable内のcustomer success managementベースを、Retoolで動作するPostgresデータベースに変換しましょう。

  1. https://app.syncinc.so/signup に移動し、アカウントを作成します。

  2. チュートリアルの手順に従うか、Add Baseボタンをクリックして、Airtableベースを接続します。

  1. Airtable APIキーを入力するよう指示されます。その後、Customer Success Managementベースとそのテーブルすべてを選択します。次に、Createをクリックします。
  1. すぐにSync IncにPostgresデータベースが表示され、Airtableベースのすべてのデータがそこに同期され始めます。新規データベースの資格情報が提供されます。この認証情報はSync IncデータベースをRetoolに接続する際に使用するので、いつでもすぐに見られるところに保存してください。

Retoolのリソースの設定

それでは次に、Sync Incデータベースを、他のPostgresデータベースと同様にRetoolに追加します。

  1. 新しいタブで、Retoolのダッシュボードにログインします。画面上部のメニュー・バーのResourcesをクリックし、次に青色のCreate Newボタンをクリックします。
  1. リソース・タイプの一覧からPostgresを選択します。
  1. リソース名(つまり「Airtable - Customer Success」)を入力し、Sync IncデータベースのHostPortDatabase nameDatabase usernamePasswordを入力します。これらは、Sync Incからコピーしてペーストすることができます(先頭にスペースが残らないよう注意してください)。次に、青色のCreate resourceボタンをクリックします。
  1. Retoolでリソースが作成されたことが確認されます。Create an appをクリックしてアプリケーション・ページに戻ります。

Retoolアプリケーションの設定

Sync Incを使用してAirtableをRetoolに正しく接続したら、すべての顧客データを1つのビューに表示するアプリケーションを構築できるようになります。これは、顧客のシングル・ビューとも呼ばれます。

  1. Retoolアプリケーション・ページで青色のCreate newボタンをクリックし、Generate app from dataを選択します。
  1. AirtableデータはPostgresデータベースに入っているので、Retoolはテーブルと検索バーを持つアプリケーションをすぐに起動させることができます。これが顧客のシングル・ビュー・アプリケーションの優れた基盤になります。表示されるモーダルで、作成したSync Inc Postgresデータベース(つまり、Airtable - Customer Success)、accountsテーブル、およびaccount列をアプリケーションの初期データとして選択します。次に、青色のNextボタンをクリックします。
  1. ここで、アプリケーションに名前を付けます。「Customer Central」などの名前を付けて、青色のCreate appボタンをクリックします。
  1. Retoolにより、テーブルと検索バーを持つアプリケーションが作成されます。accountsテーブルとaccount列を選択したので、アプリケーションには最初にaccountsテーブルが表示され、accountで検索することができます。試してみましょう。検索バーに「long」と入力してEnterキーを押すと、テーブルに「Long Beach College」が自動的に表示されます。
  1. では、このアプリケーションの編集を始めましょう。右上隅にあるEditボタンをクリックします。
  1. まず、Retoolがテンプレート・アプリケーションにロードする役立つヒントを削除しましょう。このヒントは必要ありません。ページ上部の2つのテキスト・ボックスと、下部の余分なボタンを選択して削除します。これですっきりしたテーブルと検索バーが残ります。

顧客アカウント・テーブルの作成

Retoolアプリケーションの基本的なスキャフォールディングを配置したら、SQLを使用してアプリケーションをニーズに合わせていくことができます。

まず、下部のパネルのクエリー・セクションをご覧ください。AirtableベースがSync Incによって適切なPostgresデータベースに変換されているため、RetoolのSQLのすべての機能にアクセスすることができます。例えば、ベースのスキーマ全体や列のタイプを確認することができます。また、SQLクエリーを作成することでオートコンプリートのメリットを享受できます。

それでは次に、アカウント・テーブルにデータを読み込むクエリーを編集し、顧客のアカウントごとに必要なデータを取り込むことができるようにします。

select accounts.id, accounts.account, accounts.primary_csm ->> 'name' AS "CSM", accounts.partnership_growth, accounts.customer_stage, count(task_manager.id) as "tasks", accounts.next_meeting
from accounts
left join task_manager on task_manager.account[1] = accounts.id
where ({{ !searchBar.value }} or accounts.account ilike {{ '%' + searchBar.value + '%' }})
group by accounts.id;

このクエリーで、必要な列をaccountsテーブルから選択しています。これは、primary_csmを取り込む構文と少し異なります。primary_csm列はAirtableのコラボレーター・フィールドであるため、Sync Incデータベース内にJSONとして保存されます。->> 'name'構文がJSON内のnameキーの値を取り出します。

また、アカウントごとのタスク数を取り込むために、accountsテーブルをtask_managerテーブルにJOINします。1つのレコードを他の多数のレコードにリンクできるため、リンクされたレコードはAirtable内に配列として表示されます。この場合、各タスクは1つのアカウントにリンクされるため、[1]構文がこの唯一のアカウントを配列から抽出して結合を完了させます。

すると、クエリーは検索バーの値に基づいてWHERE句で結果をフィルタします。検索バーに何も入力されていない場合は、アカウントのリスト全体が返されます。

Save and Runボタンをクリックすると、クエリーの結果がプレビュー表示されます。すべてきれいにできていますね。最後の手順として、このクエリーの名前をlist_accountsに変更します。左のバーに表示されているクエリーの名前をクリックして編集します。

最後に、このテーブルの見栄えを良くしましょう。キャンバス内でaccountsテーブルを選択した状態で右側のパネルのInspectorタブに入り、列を再編成して分かりやすいタイトルを付けます。id列は参照用フィールドなので、小さな「目」のアイコンをクリックして非表示にします。最後に、テーブルのソートとページ割りを適宜調整します。

テーブルの見栄えが整ったらタイトルを付けます。textコンポーネントをテーブルの上へドラッグ・アンド・ドロップします。

次に、Inspectorタブで、マークダウンを使用してテキスト・コンポーネントに# 📂 Accountsの値を付与します。これで、このテキストがH1ヘッダーになります。

残りの顧客データを追加する

これで1つ目のテーブルが完成しました。AccountsテーブルはAirtableからライブでデータを取り出し、簡単に検索できるようになっています。これはSQLとRetoolが手元にあれば非常に簡単にできました。それでは、残りの顧客データを追加しましょう。

アカウント・テーブルを作成したときと同じ手順を繰り返しますが、もう少し効率良く行います。

  1. コンポーネントをドラッグ・アンド・ドロップして、アプリケーションの他の部分をレイアウトします。
  2. 各コンポーネントにデータを追加します。
  3. コンポーネントの見栄えを良くします。

1. 残りのテーブルとタイトルをレイアウトします

任意のアカウントの関連情報をすべて表示させるためには、選択したアカウントについて、アプリケーションでContactsTasksMeetings、およびInvoicesを表示する必要があります。これらはそれぞれが独自のテーブルを持っています。このため、テーブルとテキスト・コンポーネントをキャンバスにドラッグ・アンド・ドロップすることで、アプリケーション全体をレイアウトすることができます。数回クリックすると、アプリケーションがこのようになります。

注意: テーブルをキャンバスにドラッグすると、Retoolがlist_accountsクエリーを用いてテーブルに自動的にデータを読み込みます。それについては特に心配はいりません。

2. テーブルにデータを追加する

各テーブルへのデータの取り込みは2段階の作業で行います。

  1. 選択したアカウントのデータを検索するクエリーを作成します。
  2. テーブルを構成してクエリーからのデータを取り込みます。

それでは、Contactsテーブルから始めましょう。

まず、下部のパネルを開き、Newをクリックして新規クエリーを追加します。

連絡先を検索するために簡単なSQLクエリーを作成します。

SELECT 
    contacts.name, 
  contacts.role, 
  contacts.email, 
  contacts.linkedin
FROM contacts
WHERE contacts.company[1] = {{table.selectedRow.data.id}};

ここで、SELECT文がテーブルの特定の列を取り込みます。さらに、Accountsテーブル(つまり、table)で選択されたアカウントに基づき、WHERE句が返された結果をフィルタします。

WHERE句でcontacts.company[1]を使用することに疑問を持たれるかもしれません。簡単に説明すると、company列はもともとはAirtable内のリンクされたレコードのフィールドです。リンクされたレコードは2つ以上の値を保持している可能性があります。このため、複数の値が存在する場合、Sync Inc PostgresデータベースにはcompanyがPostgres配列として保存されます。[1]によってPostgres配列の中の最初の値を選択します。詳しい説明については、Sync Incのチートシートまたはこのdev.toチュートリアルを参照してください。

Accountsテーブルでアカウントを1つ選択して(テスト用のSoho Real Estateアカウントの選択を推奨)、Save and Runボタンをクリックすると、このクエリーから選択されたアカウントの連絡先が返されます。これこそが探していたものです。

識別しやすくするために、クエリーにlist_contactsという名前を付けます。そして、キャンバスのContactsという見出しの下にある空のテーブルをクリックします。すると、右側のInspectorタブにテーブルの設定が表示されます。データ・フィールドに{{ list_contacts.data }}を入力します。これにより、list_contactsクエリーから返されたデータがテーブルに取り込まれます。

このパターンを繰り返して残りのテーブルにデータを取り込みます。各テーブルで使用できるPostgreSQLクエリーは以下のとおりです。これらはすべて同じパターンを用いています。

Tasks (list_tasks)

SELECT task_manager.task_name, task_manager.status, task_manager.assignee, task_manager.due_date
FROM task_manager
WHERE task_manager.account[1] = {{table.selectedRow.data.id}};

Meetings (list_meetings)

SELECT meetings.date, meetings.name, meetings.meeting_complete
FROM meetings
WHERE meetings.account[1] = {{table.selectedRow.data.id}};

Invoices (list_invoices)

SELECT invoices.invoice_number, invoices.invoice_frequency, invoices.invoicing_status, invoices.invoice_amount, invoices.invoice_period_beginning_date, invoices.invoice_period_end_date, invoices.invoice_type
FROM invoices
WHERE invoices.account[1] = {{table.selectedRow.data.id}};

すべてのクエリーの作成と接続が終わると、アプリケーションはほぼ完全な状態になっているはずです。「Soho Real Estate」などのアカウントを検索して選択すると、すべてのテーブルにそのアカウントに関する詳細情報が表示されます。

3. テーブルをきれいに仕上げる

アプリケーションを使いやすくするために、各テーブルをもう少し機能的にしましょう。

まず、これらの追加テーブルを読みやすくするためにInspectorタブのCompact modeをオンにします。これで各テーブルに詳細情報を表示できるようになります。

次に、各テーブルに分かりやすい列名と列のタイプを追加します。キャンバス内のテーブルを選択してからInspectorタブで列を選択し、その列の名前とタイプを設定します。例えば、invoice_amountの列のタイトルをAmountに変更し、その列のタイプをUSD (dollars)にします。

Retoolには、これらのテーブルを華やかにするオプションが多数ありますが、このように少し変更するだけでアプリケーションは使いやすくなります。

これで、すべての重要な顧客データが1つのすっきりとしたウィンドウに表示される顧客のシングル・ビュー・アプリケーションができあがりました。

Airtableへの書き込み

カスタマー・サクセス・エージェントがアカウントの新規タスクを作成できるようにしてみましょう。

この機能を追加するには、最初にコンポーネントを設定し、次にデータを接続します。

この場合は、簡単なモーダルを使用してタスクの詳細情報を収集します。

Sync Inc Proxy

Sync Incは一方向データフローを奨励しています。Airtableからのデータの読み取りにはSync Inc Postgresデータベースを使用し、Airtableへの書き込みはSync Inc Proxyを介して行います。

プロキシはコードとAirtableのAPIの間に配置され、CREATES、UPDATES、またはDELETESがAirtableとSync Incデータベースの両方に同時に書き込まれます。その結果、Retoolアプリケーションは素早く応答し、高速で動作します。

Sync Inc Proxyを使用するには、すべてのAirtable APIコールのホスト名をhttps://api.airtable.comからhttps://proxy.syncinc.so/api.airtable.comに変更します。その後、通常どおりにAirtable APIを使用します。

この場合、Airtable上に新規タスクを作成するにはSync Inc Proxy経由でAirtableに対してPOSTを行います。このアップデートはAirtableとSync Inc Postgresデータベースに同時に適用されます。つまり、Retoolは常に最新のデータを表示します。

モーダルの追加

コンポーネント・リストからモーダル・コンポーネントを探し、そのボタンをキャンバス上のTaskテーブルのすぐ上へドラッグ・アンド・ドロップします。

このボタンは、緑色にして「New Task」というテキストを入れることができます。

それでは、モーダル内に、新規タスクの詳細情報を収集するためのフォームを作成しましょう。

「New Task」ボタンをクリックするとモーダルが表示されます。モーダルはそれほど大きくする必要はありません。Inspecorタブで、モーダルの高さを350pxに調整します。

それでは、複数のコンポーネントをモーダル内にドラッグ・アンド・ドロップします。

  • テキスト・コンポーネント(Add a new taskにします)
  • テキスト入力コンポーネント(ラベルをTaskにします)
  • 日時選択コンポーネント(ラベルをDue Dateにします)
  • ドロップダウン・コンポーネント(ラベルをStatusにします)。値と表示値を、["Not Started", "In Progress", "Complete", "On Hold"]という配列になるように設定します。
  • 下部の2つのボタン(片方はSave、もう片方はCancelにします)

最終的に、モーダルはこのようになります。

モーダルの接続

まず、ユーザーがモーダルを閉じることができるようにします。

  • 下部のパネルを開いてクリックし、新規クエリーを作成します。
  • リソースはRun JS code (Javascript)を選択します。
  • クエリーにmodal1.close()を入力し、クエリーをclose_modalとして保存します。

ユーザーがモーダルを閉じるか、Cancelボタンをクリックしたときに、close_modalクエリーをトリガーします。

次に、ユーザーがSaveをクリックしたときに新規タスクの作成をトリガーしましょう。

そのためには、まずSync Inc Proxyをリソースとして追加する必要があります。

左上隅にあるRetoolアイコンをクリックし、Resourcesを選択します。

Resourceページで青色のCreate Newボタンをクリックし、次にオプションの中からREST APIを選択します。

Airtable APIを構成します。

  • APIにAirtable API - Customer Successという名前を付けます。
  • Base URLを取得するにはhttps://airtable.com/apiに移動してCustomer Success Managementベースを選択します。ページの中ほどに、ベースID(Sync Incで使用したものと同じ)が緑色で表示されています。このベースIDを、URLの後ろに追加します。https://proxy.syncinc.so/api.airtable.com/v0/{YOUR_BASE_ID}
  • 次に、APIキーをAirtableアカウント・ページから取得し、以下の2つのヘッダーを追加します。
  • Authorization: Bearer {YOUR_API_KEY}
  • Content-Type: application/json

次に、青色のCreate resourceボタンをクリックします。

アプリケーションに戻り、下部のパネルを開いてクリックし、以下のように新規クエリーを作成します。

  • Resourceでは、作成したAirtable APIリソースを選択します。
  • Action typeではPOSTを選択してTask%20Managerを入力します(%20はスペースをURLに適した型に変えたものです)。
  • bodyでは、Rawを選択して以下のJSONを入力します。
'{
  "records": [
    {
      "fields": {
        "Status": "{{select1.value}}",
        "Due Date": "{{datetimepicker1.formattedString}}",
        "Account": [
          "{{table.selectedRow.data.id}}"
        ],
        "Task name": "{{textinput2.value}}"
      }
    }
  ]
}'

このAPIクエリーの本体がTask Managerテーブル内に新規レコードを作成します。タスクの詳細情報はモーダルに入力した値から取り込まれます。

最後に、新規タスクの作成後にアプリケーション内のデータをリフレッシュする必要があります。そのためには、ページ下部のOn success triggerフィールド内でlist_accountsクエリーを選択します。これでページ上のすべてのテーブルがリフレッシュされます。

Saveをクリックしてクエリーの名前をcreate_new_taskにします。

ユーザーがモーダル内のSaveをクリックしたときに、新規タスクを作成し、モーダルを閉じ、そのページのデータをリフレッシュする必要があります。

このため、最後にもう一つのクエリーを作成してこれらの機能をつなぎ合わせましょう。

クリックして新規クエリーを作成し、リソースとしてRun JS Code (Javascript)を選択します。次に、以下のコードを入力します。

create_new_task.trigger();
modal1.close();
  1. 1行目で新規タスクをトリガーします。
  2. 2行目でモーダルを閉じます。

Saveボタンをクリックし、このクエリーの名前をrun_modalにします。

では、この新規クエリーをモーダルに接続しましょう。ユーザーがSaveボタンをクリックしたときにrun_modalクエリーをトリガーする必要があります。このため、モーダルを開いてSaveボタンを選択します。Inspecorタブで、クリック時のRun a queryを選択します。ドロップダウンからrun_modalを選択します。

最後の手順です。テストを行います。モーダルを開いてタスクを作成します。Saveボタンをクリックします。モーダルが閉じて、作成した新規タスクが直ちに表示されます。✨

これで、SQLとSync Inc Proxyを利用して、Airtableデータ上に直ちにRetoolアプリケーションを構築することができます。