CraftとNotionを連携させて実現するアンケート管理

<html><head></head><body>こんにちは、Customer Engineerの島本です！ホームサウナは松本湯です。
さて、以前「<a href="https://solution.plaid.co.jp/202306-craft-webhook">Web上のユーザー行動をトリガーにして外部にWebhookリクエストを飛ばす</a>」という内容をご紹介しましたが、KARTEを使っていると、Web上のユーザー行動だけではなく、「KARTE 内で発生した特定の変更や追加などの変化をトリガーにして、そのデータをリアルタイムに外部のシステムに投げたいな」と思うことがあります。
例えば次のようなケースです。
<ul>
<li>KARTEの接客サービスのステータスが変更されたら社内Slackに通知したい</li>
<li>Datahubの特定のジョブフローが開始・終了したタイミングで通知メールを送りたい</li>
</ul>
KARTE を社内の色々な人が活用するようになると、管理を目的にKARTE 内で発生した特定の変更や追加を通知して把握したいというニーズは出てくると思いますが、現在のKARTE では<a href="https://support.karte.io/post/3NTXQLgdSft8XSWlypUiEg" target="_blank" rel="noreferrer">「お知らせ・通知」機能</a>で特定のメールアドレスに通知を飛ばすことしかできません。また、特定の条件に合致した際にだけ通知を飛ばすというような柔軟な対応もできないです。
しかし、KARTE Craftを使うことでこれらを解決することができます。
今回はKARTEの「Hook v2」機能と「Craft Functions」を使ってKARTEの接客サービスのステータス変更時に社内Slackに通知を飛ばす方法を紹介します。
<h1 id="処理の流れ">処理の流れ</h1>
全体の処理の流れは、次の通りです。 
<img src="https://ik.imagekit.io/plaid/7f3b2157-90b6-41a2-aa63-76f0bdb71134/hookv2-slack-integration.png" alt="hookv2-slack-integration.png">
接客サービス機能とCraft Functionsの連携では、次の2つの機能を利用します。
<ul>
<li><a href="https://developers.karte.io/reference/campaign-enable-hook" target="_blank" rel="noreferrer">Hook v2 の Campaign Change Enabled Hook</a>
<ul>
<li>接客のステータス変更に関する情報をリアルタイムに外部に連携する</li>
</ul>
</li>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/hook-v2" target="_blank" rel="noreferrer">Craft Hook v2 トリガー</a>
<ul>
<li>Hook v2 起動時に Craft Functions を実行する</li>
</ul>
</li>
</ul>
<h1 id="実装手順">実装手順</h1>
実装の手順は次の通りです。 
大きく分けてSlack 側と KARTE 側のそれぞれの設定があります。
<ol>
<li>Slack アプリを作成する</li>
<li>Slack アプリをチャンネルに追加する</li>
<li>API v2 アプリを作成する</li>
<li>Slack アプリの OAuth トークンを Craft Secret Manager に登録する</li>
<li>Craft Functions を作成する</li>
<li>Craft Hook v2 トリガーを設定する</li>
</ol>
順番に見てみましょう。
<h2 id="1. Slack アプリを作成する">1. Slack アプリを作成する</h2>
まず、Slack チャンネルに通知をするための Slack アプリを作成します。
<ul>
<li><a href="https://api.slack.com/apps" target="_blank" rel="noreferrer"> [slack api &gt; Your Apps] </a> から <code>Create New App</code> をクリック</li>
<li>Create an appの画面で <code>From scratch</code> を選択</li>
<li>次の画面で slack app 名と、slack app を適用する slack workspace を指定</li>
</ul>
アプリの作成が完了したら、Slack アプリ に必要なスコープの設定とOAuth トークンを取得します。
スコープの設定
<ul>
<li>作成したアプリを選択して、[Features &gt; OAuth &amp; Permissions]をクリック</li>
<li>ページ内の Scopes の項目の Bot Token Scopes の <code>Add an OAuth Scope</code> をクリック</li>
<li>プルダウンメニューから <code>chat:write</code> を選択 
<img src="https://ik.imagekit.io/plaid/2de46e75-afc9-4d6f-92a5-444e6a1aa71e/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-07-1812.57.49.png" alt="スクリーンショット2023-07-1812.57.49.png"></li>
</ul>
OAuth トークンの取得
<ul>
<li>OAuth &amp; Permissions ページ内の OAuth Tokens for Your Workspace の <code>Install to Workspace</code> をクリック</li>
<li>アプリがワークスペースにアクセスするための権限を許可するために、<code>許可する</code> をクリック</li>
<li>自動的に生成される OAuth トークン（Bot User OAuth Token）を控えておく 
<img src="https://ik.imagekit.io/plaid/0696d92f-ec7b-4c5d-9327-cddfbc143039/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-07-1813.01.11.png" alt="スクリーンショット2023-07-1813.01.11.png"></li>
</ul>
<h2 id="2. Slack アプリをチャンネルに追加する">2. Slack アプリをチャンネルに追加する</h2>
作成した Slack アプリを発言させるためには、通知を飛ばしたいチャンネルに追加する必要があります。
<ul>
<li>通知を飛ばしたいチャンネルの詳細ページを表示</li>
<li>[インテグレーション &gt; App]の <code>アプリを追加する</code> をクリック</li>
<li>今回作成したアプリを追加 
<img src="https://ik.imagekit.io/plaid/c7a4a606-d266-4b12-b647-aae1f1372fe4/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-07-1813.04.32.png" alt="スクリーンショット2023-07-1813.04.32.png"></li>
</ul>
また、通知を飛ばす Slack チャンネルのチャンネルIDは後で使うため控えておいて下さい。 
ここまでがSlack側の設定となります。次からKARTE側の設定になります。
<h2 id="3. API v2 アプリを作成する">3. API v2 アプリを作成する</h2>
Campaign Change Enabled Hook を利用するためのAPI v2アプリを作成します。 
<img src="https://ik.imagekit.io/plaid/7024cc30-2a3e-4c82-bb14-3514a62deb25/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-07-180.23.18.png" alt="スクリーンショット2023-07-180.23.18.png">
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を <code>token</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>beta.action.campaign.findById</code>: Hook に必要</li>
</ul>
</li>
</ul>
「アプリタイプ」は後から変更できないため、誤って作成した場合は、アプリを再度作成し直してください。
<h2 id="4. Slack アプリの OAuth トークンを Craft Secret Manager に登録する">4. Slack アプリの OAuth トークンを Craft Secret Manager に登録する</h2>
Slack アプリの OAuth トークンを Craft Secret Manager のシークレットとして登録します。それにより、秘匿すべきアクセストークンをファンクション上に直接記述する必要がなくなります。
<img src="https://ik.imagekit.io/plaid/7dfbbd31-7bbe-4b81-9003-b4df79c21995/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-07-1722.43.07.png" alt="スクリーンショット2023-07-1722.43.07.png">
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>控えておいた OAuth トークンを貼り付けて、適当な名前を付けて保存</li>
</ul>
作成したシークレットの名前は、次に作成するCraft Functionsの中に記載します。
<h2 id="5. Craft Functions を作成する">5. Craft Functions を作成する</h2>
Slackに通知を飛ばすためのCraft Functions のファンクションを作成します。 
サンプルとなるソースコードは、GitHubで公開しています。 
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/notify-campaign-status-change-to-slack" target="_blank" rel="noreferrer">craft-codes/craft-functions/notify-campaign-status-change-to-slack at main · plaidev/craft-codes</a>
実装内容は、次のとおりです。
<ol>
<li>Hook v2経由でステータスが変更された接客サービスの内容を受け取る</li>
<li>Slack に通知するメッセージ内容を作成</li>
<li>Slack API の chat.postMessage を使ってメッセージを送信</li>
</ol>
Craft Functions作成画面のcode に サンプルコードのindex.js の内容を貼り付け、modules に modules.json の内容を貼り付けます。冒頭に以下の2つを定数に指定します。
<ul>
<li>KARTE プロジェクトID
<ul>
<li>KARTE プロジェクトIDは KARTE の管理画面URLの project= 以降の部分 
https://admin.karte.io/craft/functions?project=<code>XXXXXXXXXXXXXXXX</code> 
※上記はファンクション一覧ページのURLを例としています</li>
</ul>
</li>
<li>送信先の Slack チャンネルID
<ul>
<li>送信先の Slack チャンネルIDには、控えておいたチャンネルIDを貼り付ける</li>
</ul>
</li>
</ul>
<pre><code class="hljs"> const KARTE_PROJECT_ID = ''; // KARTEプロジェクトIDを指定
 const SLACK_CHANNEL_ID = ''; // 送信先のチャンネルIDを指定
</code></pre>
また、サンプルコードではSlack に通知するメッセージについて、以下で「接客名」と「ステータス」と「接客URL」をメッセージ内容に指定していますが、接客サービスの設定詳細を指定することもできるため、<a href="https://developers.karte.io/reference/post_v2beta-action-campaign-findbyid" target="_blank" rel="noreferrer">Fetch a campaign by id</a> の Response を参照の上追加してください。
<pre><code class="hljs"> // chat.postMessageのパラメータを設定
 const title = data.jsonPayload.data.ret.title;
 const campaignId = data.jsonPayload.data.ret.id;
 const status = data.jsonPayload.data.ret.enabled;
 let statusText = ''
 if (status === true) {
 statusText = '公開'
 } else {
 statusText = '非公開' 
 }
 
 let msg = `接客のステータスが変わりました。\n`;
 msg += `接客名：${title}\n`;
 msg += `ステータス：${statusText}\n`;
 msg += `接客URL： https://admin.karte.io/p/${KARTE_PROJECT_ID}/service/${campaignId}`;
</code></pre>
<h2 id="6. Craft Hook v2 トリガーを設定する">6. Craft Hook v2 トリガーを設定する</h2>
最後に接客サービスのステータスが変更される度にファンクションが実行されるように Hook v2 の設定をします。 Hook v2 の設定は API v2 アプリ上で行います。
<img src="https://ik.imagekit.io/plaid/43b577e6-80d5-40ac-b949-b4739707135c/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-07-1722.38.10.png" alt="スクリーンショット2023-07-1722.38.10.png">
<ul>
<li>「2. API v2 アプリを作成する」で作成したアプリの設定画面を開く</li>
<li>[トリガー設定] に <code>KARTE Action: 接客サービスの公開・非公開時</code> を指定</li>
<li>[チャネル設定 &gt; Craft] を有効化し、先ほど作成したファンクション名を入力</li>
</ul>
これで、接客サービスのステータス変更時に先ほど作成したファンクションが実行され、Slackに通知が飛ぶ設定が完了しました。
<h1 id="実際に動かしてみる">実際に動かしてみる</h1>
接客サービスのステータス変更時に Slack に通知を飛ばす実装が完成したところで、実際に動作を確認しましょう。
まず、接客サービスのステータスを変更します。 
新規で作成した接客サービスのステータスを「公開」に変更しました。 
<img src="https://ik.imagekit.io/plaid/035b1f3b-98a8-4f68-b9bf-5590c785fb34/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-07-181.15.08.png" alt="スクリーンショット2023-07-181.15.08.png">
指定した Slack チャンネルに作成した Slack アプリから通知が飛んできました。 
<img src="https://ik.imagekit.io/plaid/04adc8f9-6511-4018-b9bd-c3e3b38b6c7b/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-07-181.16.02.png" alt="スクリーンショット2023-07-181.16.02.png">
該当の接客サービス名やステータス、URLが含まれているメッセージが送信されていることを確認できました。
<h1 id="おわりに">おわりに</h1>
今回は接客サービスのステータス変更時をトリガーに Slack に通知を飛ばす方法を紹介しましたが、他にも KARTE TALK のメッセージ送信時や Datahub Jobflowの開始・終了 といった各種トリガーからファンクションを実行することができるため、あらゆるシーンでの活用ができます。
通常のKARTE 運用において痒いところに手が届かない部分でもKARTE Craft を使うことで実現することができるため、「こんなこと出来ないかな？」と思った際には是非一度ご相談くださいませ！
<hr>
プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ 
ぜひ気軽にお問い合わせください。
↓ パートナー企業になりたい
<ul>
<li><a href="https://ecosystem.plaid.co.jp/" target="_blank" rel="noreferrer">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
↓ PLAIDで働きたい
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer" target="_blank" rel="noreferrer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer" target="_blank" rel="noreferrer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>
</body></html>

KARTE Craftを使って「KARTE 内で発生した特定の変更や追加などの変化時に社内にSlack通知する」方法について紹介します。

KARTE CraftでKARTEの接客ステータス変更時にSlack通知をする