ドキュメントメニュー

Salesforce

MailInApp にはインストールする Salesforce アプリはなく、必要もありません。Salesforce の REST API は HTTPS でシンプルな JSON を返します。MailInApp の API データソースは OAuth2 JWT Bearer 認証で、Salesforce のサーバー間ログインフローを直接扱います。同意画面もリフレッシュトークンの管理も不要で、Salesforce のパスワードが MailInApp に届くことはありません。

英語の動画です

このガイドでは読み取り専用の接続を設定します。Opportunity、Account、Contact、商品の行を差し込みタグ、繰り返しブロック、データ連動グラフに取り込み、Salesforce の連絡先をオーディエンスとしてインポートすることもできます。Salesforce に書き戻すことはありません。

接続のしくみ

  1. MailInApp は、アプリの秘密鍵で短時間だけ有効な JWT アサーションに署名します。
  2. そのアサーションを Salesforce のトークンエンドポイントに送ります。Salesforce はアップロード済みの証明書で署名を確認し、アクセストークンを返します。ユーザー名やパスワードは送信されません。
  3. MailInApp はアクセストークンをキャッシュし、それを使って Salesforce の REST API(SOQL クエリ)を呼び出します。期限切れの前や、呼び出しが未認証で返ったときは新しいトークンを取得します。

すべてサーバー側で、取得のたびに行われます。一度設定すれば、維持や再認可の作業はありません。

鍵ペアを作成する

JWT フローには RSA の鍵ペアが必要です。証明書は Salesforce に、秘密鍵は MailInApp に渡します。まだない場合は、OpenSSL で自己署名のペアを作成します。

openssl req -x509 -newkey rsa:2048 -nodes -keyout mailinapp.key -out mailinapp.crt -days 730 -subj "/CN=MailInApp"

mailinapp.key は安全な場所に保管してください。MailInApp に一度貼り付けると、以降はマスクされます。

Salesforce 側の設定

Salesforce では、新しい連携は External Client Apps として作成します(最近の組織では、新しい Connected App の作成は既定で無効です)。

  1. 設定(Setup)で External Client App Manager を開き、New External Client App をクリックします。
  2. 名前(例:MailInApp JWT)と連絡先メールを入力し、Distribution State は Local のままにします。
  3. API (Enable OAuth Settings) を開き、Enable OAuth にチェックを入れます。JWT フローは Callback URL を使いませんが入力は必須です。https://login.salesforce.com/services/oauth2/success で問題ありません。
  4. OAuth Scopes で Manage user data via APIs (api) と Perform requests at any time (refresh_token, offline_access) を追加します。
  5. Flow Enablement で Enable JWT Bearer Flow にチェックを入れ、証明書(mailinapp.crt)をアップロードします。Create をクリックします。
  6. アプリの Policies タブで Edit をクリックします。OAuth Policies の Permitted Users を Admin approved users are pre-authorized にし、MailInApp がログインするユーザーのプロファイルまたは権限セットを選びます。これでフローが非対話型になります。この設定がないと、Salesforce は誰かが同意画面で承認することを求めます。保存します。
  7. Settings タブで OAuth Settings を開き、Consumer Key and Secret をクリックします。本人確認のコードがメールで届き、その後 Consumer Key が表示されます。これが MailInApp に必要な発行者です。シークレットは不要です。

MailInApp がログインするユーザーには、そのユーザーが Salesforce で見られるものだけが見えます。メールで使うオブジェクトに読み取り権限を持つ専用の連携ユーザーにするのがいちばんきれいです。そのユーザーから(項目レベルセキュリティで)隠れている項目は、クエリ結果に含まれません。

MailInApp で接続する

データソース → + API 接続 を開き、次のように設定します。

  • エンドポイント URL:組織のクエリ URL に SOQL クエリを付けたもの。例:https://yourorg.my.salesforce.com/services/data/v62.0/query?q=SELECT Name, Amount, StageName, CloseDate, Account.Name FROM Opportunity WHERE IsClosed = false。クエリは普通のスペースのまま入力できます。MailInApp がエンコードします。
  • データパス:records。Salesforce は行を records 配列に入れ、totalSize と done を添えて返します。
  • 認証:OAuth2 JWT Bearer。
    • トークン URL:https://login.salesforce.com/services/oauth2/token(または My Domain の https://yourorg.my.salesforce.com/services/oauth2/token)。Sandbox では https://test.salesforce.com/services/oauth2/token。
    • 発行者:アプリの Consumer Key。
    • サブジェクト:MailInApp がログインする Salesforce のユーザー名。
    • オーディエンス(aud):https://login.salesforce.com(Sandbox では https://test.salesforce.com)。
    • 秘密鍵:mailinapp.key の中身。

この設定をテスト をクリックすると、実際にトークンを取得してクエリを実行し、差し込みタグから見えるとおりの最初の数行を表示します。保存後は、保存済みの接続をテスト で鍵を貼り直さずにいつでも確認できます。

1 つの接続は 1 つのクエリです。用途ごとに作成します。パイプラインのメールには商談、商品カタログには価格表、オーディエンスには連絡先、という具合です。

SOQL でのクエリ

クエリがそのまま受け取るデータになります。メールに必要な列だけを選んでください。

  • 関連項目も使えます。 Salesforce は Account.Name のような参照項目を入れ子のオブジェクトで返しますが、MailInApp はそれを Account.Name という名前の項目にします。差し込みタグでは {{alias.Account.Name}}、繰り返しブロックの中では {{Account.Name}} と書きます。3 階層(Account.Owner.Name)まで対応し、Salesforce が各レコードに付ける attributes のメタデータは除かれます。
  • 並べ替えと件数はクエリで。 ORDER BY CloseDate と LIMIT 10 で、繰り返しブロックに表示する行の順序と数が決まります。
  • 1 回の取得で最大 1,000 行。ダイジェストやカタログには十分です。
  • レンダリングのたびに取得し直します。 毎回の送信(定期送信の各回を含む)でクエリが再実行されるため、メールは常に Salesforce の最新データを表示します。キャッシュされるのは OAuth トークンだけです。

便利なクエリの例:

SELECT Name, StageName, Amount, CloseDate, NextStep, Account.Name FROM Opportunity WHERE IsClosed = false ORDER BY CloseDate
SELECT Name, ProductCode, UnitPrice, Product2.Description, Product2.DisplayUrl FROM PricebookEntry WHERE Pricebook2.IsStandard = true AND IsActive = true
SELECT Id, FirstName, LastName, Title, Email, HasOptedOutOfEmail, Account.Name, Account.Industry FROM Contact WHERE AccountId != null

データを使う

スタジオのデータパネルから、エイリアス(例:pipeline)と役割を付けて接続をメールに追加します。

  • 差し込みフィールド:{{pipeline.field}} は最初の行から解決されます。見出しの数字 1 つに向いています。
  • 繰り返し行:繰り返しブロックに渡され、行ごとに中身を繰り返します。たとえば商品ごとに 1 枚のカードです。
  • 同じ行は KPI・棒・折れ線・円グラフにも使えます。Amount を合計する KPI は進行中パイプラインのライブな数字に、StageName でまとめた棒グラフはステージ別のパイプラインになります。

受信者ごとに違う切り口を見せる

繰り返しブロックの 行をフィルター とグラフのフィルターでは、Salesforce の項目を受信者自身のデータと比べられます。company 列を持つオーディエンスリストなら、Account.Name が次と等しい {{company}} というルールで、各販売店に自社の商談だけを見せられます。クエリは 1 つで共通です。各受信者のメールは、送信時にその人の行から作られます。

Salesforce の連絡先をインポートする

オーディエンスは MailInApp の連絡先リストです。Salesforce から埋めるには、Contact のクエリ(上の 3 つ目)で API 接続を作り、連絡先 → 連絡先をインポート で API接続 を選びます。

MailInApp は保存済みの認証情報で行を読み込み、Salesforce の項目を認識して Salesforce の対応付けを使う を提案します。FirstName → first_name、Account.Name → company、Id → salesforce_id などです。Salesforce で Email Opt Out(HasOptedOutOfEmail)がオンの連絡先は確認ステップで示され、除外するか選べます。CSV で書き出した Salesforce レポートも同じように認識されます。リードのインポートもご覧ください。

インポートはコピーです。新しい連絡先を取り込むには、もう一度実行します。

この接続で作る週次のパイプラインダイジェストの例は、Salesforce のライブデータで動くインタラクティブメールをご覧ください。