Salesforce

MailInAppにはインストールするSalesforceアプリはありませんが、必要ありません。Salesforce自身のREST APIはHTTPS経由のプレーンなJSONで応答し、MailInAppのAPI接続のOAuth2 JWT Bearer認証は、Salesforceのサーバー間ログインフローを直接話せるように作られています。対話的な同意画面も、管理が必要なリフレッシュトークンもなく、SalesforceのパスワードがMailInAppに触れることも一切ありません。

このガイドでは、読み取り専用の接続を設定します — Opportunity、Account、Contactの行をマージタグ、繰り返しブロック、ライブに紐付けられたチャートブロックに取り込みます。Salesforceへの書き込みは行いません。

接続の仕組み

MailInAppは、SalesforceのConnected Appの秘密鍵を使って、短命なJWTアサーションに署名します。
そのアサーションをSalesforceのトークンエンドポイントにPOSTします。エンドポイントはアップロードした証明書に対して署名を検証し、アクセストークンを返します — ユーザー名やパスワードは一切送信されません。
MailInAppはアクセストークンをキャッシュし、それをBearerトークンとしてSalesforce REST API(SOQLクエリ)を呼び出します。トークンが期限切れになる前、またはリクエストが未認証で返ってきた場合は自動的に更新されます。

すべてのステップはサーバーサイドで、各フェッチのたびに実行されます — 一度設定すれば、手動で維持したり再認証したりする必要はありません。

Salesforce側を設定する

Salesforce SetupでApp Manager → New Connected App(またはNew Connected App (Lightning))に移動します。
基本の名前・メールフィールドを入力し、Enable OAuth Settingsにチェックを入れます。
Use digital signaturesの下で証明書をアップロードします。まだ持っていない場合は、自己署名証明書とそれに対応するRSA秘密鍵を生成してください — 証明書はSalesforceへ、秘密鍵はMailInAppへ渡します。秘密鍵は安全な場所に保管してください。MailInAppには一度だけ貼り付ければよく、以降はマスクされます。
連携に必要なOAuthスコープを追加します — レコードを読み取るだけであればapi(Manage user data via APIs)で十分です。
保存し、Connected Appのポリシーを編集します:Permitted UsersをAdmin approved users are pre-authorizedに設定します。これにより、このフローは非対話的になります — これを設定しないと、Salesforceは人間が同意画面をクリックすることを期待しますが、サーバー間のJWT交換ではそれができません。
インテグレーションユーザー(プロフィールでAPIアクセスが有効になっている実在のSalesforceユーザー、または連携専用のユーザー)を、permission set経由でConnected Appに割り当てます。
Connected AppのConsumer Key(MailInAppが必要とするissuerです)と、組織のMy Domain URL(Setup → My Domain、例:https://yourorg.my.salesforce.com)を控えておきます。

MailInAppで接続する

データソース → + API接続から、以下を設定します:

エンドポイント — 組織のREST問い合わせURL。例:https://yourorg.my.salesforce.com/services/data/v61.0/query?q=SELECT+Name,Amount,StageName,CloseDate+FROM+Opportunity+WHERE+IsClosed+=+false(URLエンコードされたSOQLクエリです — 下記のSOQLでのクエリを参照)。
データパス — records。Salesforceのクエリレスポンスは、実際の行をtotalSize/doneフィールドと並んでrecords配列にラップしています。
認証方式 — OAuth2 JWT Bearer:
- トークンURL — 本番環境およびDeveloper Edition組織ではhttps://login.salesforce.com/services/oauth2/token、サンドボックスではhttps://test.salesforce.com/services/oauth2/token。
- Issuer — Connected AppのConsumer Key。
- Subject — インテグレーションユーザーのSalesforceユーザー名(JWTが主張するアイデンティティ)。
- Audience — トークンURLと同じホスト:https://login.salesforce.com(サンドボックスの場合はhttps://test.salesforce.com)。
- 秘密鍵 — Connected Appにアップロードした証明書に対応するRSA秘密鍵。

保存する前にTest these settingsをクリックして接続を確認します — 実際にトークンを発行し、最初の数行をプレビューします。保存した後は、秘密鍵を再度貼り付けることなく、いつでもTest saved connectionで再確認できます。

SOQLでのクエリ

エンドポイントのクエリ文字列は、そのまま得られるデータそのものです — 「フィールドを選ぶ」専用のUIはないため、メールが必要とする列だけを返すようにSOQLクエリを組み立ててください:

SELECT Name, Amount, StageName, CloseDate FROM Opportunity WHERE IsClosed = false

返ってくるデータの形について、知っておくとよいことがいくつかあります:

フラットなフィールドのみ。 Owner.EmailやAccount.Nameのようなリレーションフィールドは、ネストしたJSONオブジェクト({"Owner": {"Email": "..."}})として返ってきますが、MailInAppの行パーサーは、フラット化の方法を推測するのではなく、ネストした値を捨てます。オーナーやアカウントの識別子を使えるマージタグとして必要な場合は、ドット区切りのリレーションパスではなく、OwnerIdのようなフラットなフィールドを選んでください。
1回のフェッチで最大1,000行。 ダイジェストやダッシュボードメールには十分な量です。特定の範囲だけが必要な場合は、クエリ自体でWHERE/ORDER BY/LIMITを使ってさらに絞り込んでください。
レンダリングごとに新しく取得。 繰り返し送信では、送信のたびにクエリを再実行し、Salesforceの現在の行で紐付けられたブロックを再レンダリングします — OAuthトークン自体を除けば、キャッシュは行われません。

データを使う

接続したら、スタジオのデータパネルから、エイリアス(例:pipeline)と役割を指定してプロジェクトに追加します:

マージフィールドは、返された最初の行から{{pipeline.field}}を解決します — 単一の見出し数値に便利です。
繰り返し行は繰り返しブロックに供給されます — Opportunityごとに1行、リストまたはテーブルとしてレンダリングされます。
繰り返し行の紐付けは、KPIスコアカード、バー、ライン、円グラフブロックが直接紐付ける対象です — KPIスコアカードのValueフィールドをAmountに設定し、Sum集計を使うだけで、マージタグの配線を一切必要とせずにライブな「オープンパイプラインの合計」数値が得られます。また、StageNameでグループ化したバーチャートは、同じクエリをステージ別のパイプライン内訳に変換します。

この接続だけで構築された週次のパイプラインダイジェストという、完全な実例についてはライブSalesforceデータを活用したインタラクティブメールを参照してください。