記事テンプレート

JSONイベントについて

ウェブサイトで行ったリクエストをクアルトリクスでチケットのトリガーにしたいと思ったことはありませんか？クアルトリクスと社内システムのシームレスな統合を実現したいと思ったことはありませんか？ワークフロータブでタスクをトリガーしたいが、クアルトリクスの外部で発生したイベントをトリガーしたいと思ったことはありませんか？

JSONイベントにより、外部ソフトウェアがHTTPリクエスト経由でワークフローを開始することができます。クアルトリクスでイベントが発生し、プラットフォームでさらなるアクションがトリガーされるのを待つ代わりに、JSONイベントを設定するだけで、サードパーティーからのリクエストを受け取ることができます。

制約

JSONイベントは、以下のセットアップやコンフィギュレーションとは互換性がありません：

• HTTP以外のもの（メッセージキュー、SMSなど）。
• アウトバウンドHTTPコール。
• XMLを処理する(XMLリクエストボディは無視される)。
• JSON以外を処理する。
• X-API-トークン・ヘッダ、またはHTTPベーシック認証以外の方法で自分らしくいられることを認証してください。
  Qtip:OAuthやその他の認証機能はJSONイベントと互換性がありません。
• JSONボディのJSONPathクエリを使用しても満たされないJSONパース。
• 1分あたり3,000のAPIレート制限を超える通話。
• 100KBを超えるペイロード。

対応する認証の種類

トークン・ベース認証／ヘッダー認証

リクエストのヘッダーにX-API-TOKENとしてAPIトークンを渡すことで、自分らしくいられることを認証することができます。

.curl -X POST -H 'X-API-TOKEN: yourapitokenhere' -H 'Content-Type: application/json' -d '{

 

surveyId"："SV_012345678912345",

  "format"："csv"

}' 'https://yourdatacenterid.qualtrics.com/API/v3/responseexports'.

HTTPベーシック認証

Basic Authは通常、username:passwordをBase64エンコードしたものです。ただし、クアルトリクスではセキュリティ向上のため、username:x-Api-tokenをBase64エンコードした文字列を使用しています。

Basic Authを使用するには、HTTPリクエストにヘッダーを設定する必要があります。特定のヘッダーはAuthorizationである。

 demo@qualtrics.com:f8gIK7G6GFH985Y4

 ベーシック ZGVtb0BxdWFsdHJpY3MuY29tOmY4Z0lLN0c2R0ZIOTg1WTQ=

JSONイベントの設定

1. まず、ワークフローを作成する必要があります。スタンドアローンのワークフローページに移動します。
   
   Qtip:JSONイベントを プロジェクトのワークフロータブ。ワークフローを特定のプロジェクトに追加することをお勧めするのは、それらが明確に関連している場合のみです。(例えば、JSONイベントでそのプロジェクトを配信している場合など)。
2. ワークフロー 」タブにいることを確認してください。
3. ワークフローの作成」をクリックします。
4. イベント受信時に開始を選択。
5. JSON イベントを選択します。
   
6. 必要であれば、JSONイベントの目的を説明するトリガー・サマリーを指定します。
7. URLが表示されます。Postmanや社内システムなど、クアルトリクス外部から新しいワークフローを呼び出す場合に使用します。URLをコピーするには、「URLをコピー」をクリックします。
8. デフォルトでは、JSONイベントは認証を必要とします。未認証のリクエストを許可したい場合は、クアルトリクスによる認証を要求するを無効にすることができます。
9. ここで、イベントデータを定義することができる。これはインバウンドリクエストからデータを取得する。開始するには、詳細設定をクリックします。
   
   Qtip：「テスト」セクションについては、下記の「イベントをキャプチャする」を参照してください。
10. 左側のボックスで、JSONフィールド名を指定します。右側のボックスで、イベントデータ（HTTPリクエストボディ）内の場所を指定します。
    Qtip:ロケーションはJSONPathフォーマットでなければなりません！JSONPath構文のクイックガイドについては、以下の表を参照してください。
11. 別のフィールドを追加するには、Add a JSON fieldをクリックします。
12. QUERYパラメータを追加したい場合は、 QUERYパラメータ セクションに追加してください。これらのパラメータが何であり、APIでどのように機能するかについては、API Documentation on Parametersを参照してください。
    警告個人を特定できるデータをQUERYパラメータで渡すことはお勧めしません。個人を特定できる情報や機密性の高いデータは、POSTの方がより安全であるため、可能な限りPOSTボディを通して渡されるべきです。ご不明な点やご質問がございましたら、クアルトリクスサポートまでご連絡ください。
13. フィールドを削除するには、マイナス記号（–）をクリックします。
14. 変更を保存するには、Saveをクリックします。
15. ワークフローに条件とタスクを追加するには、プラス記号(+)をクリックします。条件はワークフローがいつ実行されるかを決定し、タスクはワークフローの結果である。参照 ワークフローの概要 をご覧ください。
    

イベントの捕捉

外部APIイベントを作成する際、post bodyからデータを解析する必要があるかもしれません。しかし、このデータを解析するのは時として難しい。外部APIが何を送信しているかを知りたい場合は、以下の手順に従ってください。

1. JSONイベントをクリックします。
   
2. デフォルトでは、テスト結果から JSON フィールドをキャプチャし、このワークフローの他のタスクでテキストの差し込みとして使用できるようにするオプションが有効になっています。このオプションは、ワークフロータスクを追加する際に、ペイロードのボディに解析されたフィールドが自動的にテキストの差し込みとして利用できるようにします。
   
3. Run a new testをクリックします。
4. クアルトリクスが外部システムからのイベント受信を待っているというメッセージが表示されます。外部APIを起動します。
   Qtip:このテストをキャンセルするには、Cancel testをクリックします。
5. テストが成功すると、「サーバーへの接続に成功しました」というメッセージが表示されます。ペイロードは解析され、ウィンドウに追加される。
6. 必要であれば、Run a new testをクリックして別のテストを実行します。このオプションをクリックした後、次へAPIコールを実行する必要があります。
7. ［保存］をクリックします。

JSONPathの構文

以下の表は、JSONPath構文の基本を示したものである。これらはクアルトリクスによって確立されたものではなく、JSONで使用される標準であることに注意してください。

JSONPath構文の例

この例では、JSONオブジェクトが与えられた場合、JSONPathテーブルをどのように使用できるかを示します。

これがJSONオブジェクトだ：

{
"eventDescription"："Monthly Revenue",
"stores"：[
{
"name"："Acme Store",
"total": 1000000,
"topItem":

{ "price"：「50", "description"："Anvil" }
},
{
"name"："The Banana Stand",
"total": 250000,
"topItem":

{ "price"："4", "description"："The Gob" }
},
{
"name"："Pizza Planet",
"total": 80000,
"topItem":

{ "price"：「15", "description"："Pepperoni" }
}
]
}.

ここで、JSONPathテーブルで見た戻り値を追加して、より明確にしよう。

$ -> Acme Store
@ -> [
{
"name"："Acme Store",
"total": 1000000,
"topItem":

{ "price"：「50", "description"："Anvil" }
}
]
. -> 月収
. -> 50

-> ["Acme Store", "The Banana Stand", "Pizza Planet"]
[] -> Acme Store
[,] -> [
Unknown macro: { "name"}
,

Unknown macro: { "name"}
]

**[start:end:step]のExampleを「$.stores[1:3:1]"
[start:end:step] -> [
{
"name"："The Banana Stand",
"total": 250000,
"topItem":

{ "price"："4", "description"："The Gob" }
},
{
"name"："Pizza Planet",
"total": 80000,
"topItem":

{ "price"：「15", "description"："Pepperoni" }
}
]

?() -> [{
"name"："Acme Store",
"total": 1000000,
"topItem":

{ "price"：「50", "description"："Anvil" }
}]

() -> [
{
"name"："Pizza Planet",
"total": 80000,
"topItem":

{ "price"：「15", "description"："Pepperoni" }
}
].

Node JavascriptでのAPI例

以下の例は、イベントデータをフォーマットする際に従うことができる基本的なテンプレートです。

var request = require('request-promise');
var surveyId = "SV_XXXXXXXXXX";
var triggerId = "OC_XXXXXXXXX";
var brandId = "YOUR_BRAND_ID"；
var userId = "UR_XXXXXXXXXXXX";
var datacenter = "xx1";
var apiToken = "YOUR_QUALTRICS_API_TOKEN";

var url = "https：//" + datacenter + ".qualtrics.com/inbound-event/v1/event/JSON/triggers" +
     "?contextId=" + surveyId + "&userId=" + userId + "&brandId=" + brandId + "&triggerId=" + triggerId;
var payload = {
    "text"："This is some text",
    "object"：{
        "number"：4
    },
    "array"：["a", "b", "c", "d"]
};

var options = {
    url: url,
    json: true,
    body: payload,
    headers：{
        "Content-Type"："application/json", // 必須!!!!
        
    "X-API-TOKEN": apiToken
    }
};

request.post(options).then(function (ret) {
    console.log("success:", url, payload);
}).catch(function (err) {
    console.log("error: ", url);
})；

例Freshdeskとの統合

JSONイベントは、Dispatch’rのWebhookルールとしてFreshdeskと統合するために使用できます。つまり、Freshdeskのイベントは、チケットの作成やアンケートの配信など、クアルトリクスでのタスクをトリガーすることができます。

1. クアルトリクスで、イベントをJSONイベントに設定します。
   
2. URLをコピーしてください。
   
3. 新しいタブでFreshdeskにログインします。
4. Adminセクションで、設定したいルールの種類に最も適したオプションに移動します。
   
   Qtip:Freshdeskのサポートドキュメントで、Dispatch’r、Supervisor、Observerの違いを学んでください。
5. 新しいルールを作成する。
   
6. クアルトリクスでタスクをトリガーするFreshdeskイベントを決定する条件セット。
   
   例Freshdeskエージェントがチケットのステータスを任意のステータスからアンケートのステータスに変更した場合、クアルトリクスを使用してCSATアンケートを送信したいとします。
7. 新しいアクションを追加し、トリガーウェブフックを選択します。
   
8. リクエストタイプをPOSTに設定する。
   
9. Callback URLに、ステップ2のJSONイベントURLを貼り付けます。
10. トークン認証を使用するには、カスタムヘッダを追加し、X-API-TOKEN:を入力し、APIトークンと同じ値を設定します。
    
11. HTTP Basic認証を使用するには、Requires Authenticationをクリックし、クアルトリクスユーザー名を追加し、パスワードの代わりにApiトークンを入力します。
    
12. EncodingがJSONであることを確認してください。
    
13. 渡すコンテンツを手動で選択するか、Advancedを選択してJSONボディを入力する。
14. ルールを守れ。
15. クアルトリクスで、ワークフローを終了します。この例では、おそらく XM DIRECTORYタスク。
    
16. アンケートの公開準備ができたら、アンケートの変更を公開することを忘れないでください。

例ServiceNowとの統合

JSONイベントは、ServiceNowと統合するために使用することができます。つまり、ServiceNowのイベントは、チケットの作成やアンケートの配信など、クアルトリクスでのタスクをトリガーすることができます。

1. クアルトリクスで、イベントをJSONイベントに設定します。
   
2. URLをコピーしてください。
   
3. 新しいタブで、ServiceNow開発者インスタンスにログインします。
4. RESTメッセージを選択します。
   
5. Newをクリックする。
6. RESTのメッセージに名前をつける。
   
7. Endpointフィールドに、ステップ2でコピーしたURLを貼り付けます。
8. 自分らしくいられること認証機能をBasicに変更する。
9. HTTP Requestタブに移動する。
   
10. ダブルクリックしてX-APIトークンを追加します。
11. ダブルクリックしてAPIトークンを貼り付けます。
    
12. 新しい行に、Content-typeという名前を追加する。
13. 値をapplication/jsonにする。
14. ［送信］をクリックします。
    
15. RESTメッセージを開き直す。
    
16. HTTP Methods］で［New］をクリックする。
    
17. メソッドに名前をつける。
    
18. HTTPメソッドをPOSTに設定する。
19. 自分らしくいられること認証機能を親から継承に設定する。
20. ［送信］をクリックします。
21. 先ほど作成したPOST HTTPメソッドを開き直す。
    
22. ページの下部で、［スクリプトの使用状況をプレビュー］を選択します。
    
23. テキストをコピーする。
24. 検索し、ビジネスルールを選択します。
    
25. 新規を選択する。
26. テーブルを選択する。
    
27. 詳細」を選択する。
28. ビジネスルールが実行されるタイミングを決定する。
    例テーブルに Incident を選択し、解決されたチケットに対して CSAT アンケートを送信したい場合、Incident の状態が Resolved に変わったときにこのルールを実行するという条件を追加できます。
    Qtip：クアルトリクスサポートでは、JSONイベントのセットアップとServiceNow経由での接続をサポートします。しかし、ServiceNowの機能に関する質問には答えられないこともあるでしょう。ビジネスルールの実行方法/タイミングについてご質問がある場合は、ビジネスルールの仕組みに関するServiceNowのドキュメントを参照してください。
29. 詳細設定タブに移動する。
    
30. ステップ22でコピーした内容を、「ここにコードを追加してください」と書かれているところに貼り付けます。
    
31. ボディを追加する。ここで、クアルトリクスに渡したい情報をコミュニケーションします。
    

    例このフィールドに入れる最終的なコードの例です。このコードのほとんどは、ServiceNowが提供する送信メッセージであり、例によって異なります。残念ながら、クアルトリクスサポートではカスタムコーディングのサポートは行っておりません。コードに問題がある場合は、ServiceNowのコミュニティにお問い合わせください。

    太字の部分には、元のコードには含まれていない3つの追加関数が含まれています。ユーザーIDとインシデントの状態をプルするJSONボディと、CSATを送信できるようにインシデントの顧客の電子メールアドレスを取得する呼び出しです（以下イタリック体）。その他の質問がある場合は、ServiceNowのドキュメントを参照してください。

    (function executeRule(current, previous /*null when async*/) {
    
        // ここにコードを追加
        
     try {
         var r = new sn_ws.RESTMessageV2('クアルトリクス JSON イベント ', 'JSON イベント POST')
         ;var body = {
             "ユーザーID": gs.getUserID()
             "インシデント状態": current.state.getDisplayValue()
         }；
         
         var target = new GlideRecord('sys_user');
         target.addQuery('sys_id', '=', current.caller_id);
         target.query();
         while(target.next()) {
             body["email"] = target.email.getDisplayValue();
         }.  
     
         var response = r.execute();
         var responseBody = response.getBody();
         var httpStatus = response.getStatusCode();
         gs.addInfoMessage(httpStatus);
        }
    catch(ex) {
         var message = ex.message;
    
    }
    
    }(current, previous)；

32. リクエストにボディを追加する。前のステップのコードの太字のイタリック体の部分の下に以下を追加する：

     r.setRequestBody(JSON.stringify(body))； 

33. ［送信］をクリックします。
34. クアルトリクスで、ワークフローを終了します。CSAT アンケートの例を続けると、次のようになります。 XM DIRECTORYタスク。
    
35. アンケートの公開準備ができたら、アンケートの変更を公開することを忘れないでください。

例Microsoft FlowによるMicrosoft Dynamicsとの統合

JSONイベントを利用することで、Microsoft Dynamicsのイベントをトリガーとして、チケットの作成やアンケートの配信など、クアルトリクスのタスクを実行することができます。例えば、マイクロソフトのアカウントレコードを削除するたびに、クアルトリクスアンケートをアカウント所有者に配信し、退職に関する質問をすることができます。(例：お名残惜しいです！私たちとの時間はいかがでしたか？

JSONイベントをMicrosoft Dynamicsで発生するアクションと統合するには、DynamicsではなくMicrosoft Flow内でセットアップを行う必要があります。Microsoft FlowはMicrosoft Dynamicsアカウントに無料で付属していますので、Dynamicsの情報を使ってFlowにログインできます。

1. クアルトリクスで、イベントをJSONイベントに設定します。
   
2. URLをコピーしてください。
   
3. 別のタブでhttps://us.flow.microsoft.com/en-us/、Microsoft Dynamicsの情報を使ってFlowにログインする。
4. 左側のMy Flowsを選択します。
   
5. New をクリックし、Automated – from blank を選択する。
6. 流れに名前をつける。
   
7. トリガーを選択します。これは、クアルトリクスでタスクを開始するためにMicrosoftで発生するイベントです。目的に合ったものを選べばよいが、この例では「レコードが削除されたとき（Dynamics 365）」を選択する。
8. 作成」をクリックする。
9. 組織名]で、Dynamicsアカウントにログインします。
   
10. エンティティ名]で、レコードまたはファイルのタイプを選択します。この例では、”アカウント “を使う。
11. 次へ」をクリックし、「アクションの追加」を選択します。
12. HTTPを選択する。
    
13. メソッドをPOSTに変更します。
14. URIフィールドにJSONイベントURLを貼り付けます。
15. トークン認証を使用すること。Headersの下にX-API-TOKENと入力し、次へAPIトークンを貼り付けます。
16. BodyにはJSONのボディを入力します。これは、Dynamicsからクアルトリクスに渡す情報を決定するのに役立ちます。
    Qtip:ダイナミックコンテンツの追加ボタンを使用して、クアルトリクスに引き継ぐDynamicsレコードフィールドを選択します。スクリーンショットに表示されているように、適切なJSONフォーマットに従っていることを確認してください。動的コンテンツのトラブルシューティングについては、マイクロソフト サポートにお問い合わせください。
17. 終了したら、Saveをクリックします。
18. クアルトリクスで、ワークフローを終了します。この例では、おそらく XM DIRECTORYタスク。
    
19. アンケートの公開準備ができたら、アンケートの変更を公開することを忘れないでください。

例Genesys PureCloudとの統合

JSONイベントを使用して、Genesys PureCloudと統合し、電話やチャットでのサポート対応完了後に顧客にフォローアップ調査を送信できます。

1. 送信するアンケートで、ワークフローに移動します。
   
2. イベントベースのワークフローを新規作成します。
3. ワークフローイベントでは、JSON イベントを選択します。
   
4. URLをコピー」をクリックすると、イベントのエンドポイントがクリップボードにコピーされます。
   
5. JSONイベント・ウィンドウを閉じずに、ブラウザで新しいタブを開き、Genesysに移動します。
6. ［管理］ページに移動します。
   
7. アクションをクリックする。
8. Add Actionをクリックする。
   
9. 統合名としてWeb Services Data Actionsを選択します。
   
   Qtip:Web Services Data Actionsを選択するオプションがない場合、統合を有効にする必要があります。詳しくはこのページをご覧ください。
10. アクションにアクション 名をつける。
11. ［追加］をクリックします。
12. Setupタブに移動します。
    
13. 契約タブを開く。
14. Input Contract」で「JSON」を選択します。
15. クアルトリクスに送信するプロパティを設定します。

    例 例えば、以下のコードはメールアドレス、電話番号、名前、姓を渡します。

    {
           "type"：「object",
           "properties"：{
             "emailAddress"：{
               "type"："string"
             },
             "phoneNumber"：{
               "type"："string"
             },
             "firstName"：{
               "type"："string"
             },
             "lastName"：{
               "type"："string"
             }
           },
           "additionalProperties": true
         }.

16. コンフィギュレーション・タブに 移動する。
17. リクエストタイプをPOSTに変更します。
18. Request URL Templateフィールドに、クアルトリクスのJSONイベントのURLを貼り付けます。
19. ヘッダーの追加をクリックする。
    
20. Key」 ボックスに「X-APIトークン」と入力する。
21. Value]ボックスに、クアルトリクス API トークンを入力します。
22. テスト」タブを開く。
23. プロパティのテスト値を入力します。
24. Run Actionをクリックする。
25. Genesysは、アクションが成功したかどうかを通知します。失敗した場合は、問題を解決するためのエラー回答が表示されます。
    
26. クアルトリクスのJSONイベントに戻り、プロパティが正常にクアルトリクスに渡されたことを確認します。
27. ［保存］をクリックします。
28. JSONイベントがトリガーされたときにフォローアップするタスクを設定するには、プラス記号（+）、 タスクの順にクリックします。この場合、回答者にアンケートを送信したいので、XM DIRECTORYタスクを選択します。
    Qtip:タスクをセットアップするとき、Genesysから渡された値（例えば、顧客のメール、名前など）を使用するためにテキストの差し込みメニューを使用してください。
29. クアルトリクスでタスクを設定した後、Genesysに戻り、「Save & Publish」をクリックします。
    
30. はい」をクリックする。
31. ［管理］ページに移動します。
32. アーキテクトをクリックする。
33. フローのドロップダウンメニューで、アンケート調査の招待を選択します。
34. ［追加］をクリックします。
35. フローに名前、説明、部署をつける。
36. フローの作成」をクリックする。
37. ツールボックスの「データ」セクションで「データアクションの呼び出し」を選択し、フローのドロップボックスにドラッグする。
38. アクションに名前をつける。
39. Category（カテゴリー）」で「Web Services Data Action（ウェブサービス・データ・アクション）」を選択する。
40. Data Action（データ・アクション）」で、先ほど作成したデータ・アクションを選択する。
41. 各プロパティの次へ、ドロップダウンメニューをクリックし、Expressionを選択します。
42. プロパティ値については、各プロパティについてどのようなデータが送信されるかを入力する。フィールドタイプは自動入力されます。
    Qtip: このページには、アンケートの招待フローに含まれるすべてのデフォルトプロパティがあります。また、顧客の連絡先情報が不足していたり、追加の書式設定が必要な場合には、複雑な式を使用することもできます。
    Qtip:連絡先の前にSurvey.CustomerContact を付けます。
43. フローの一番下のボックスをクリックします。
44. ツールボックス]、[アンケートの招待]、[アンケートの中止] の順に選択します。
45. Disposition にoptOutを選択します。
46. ［公開］をクリックします。Genesysはフローを検証し、公開する。これが完了すると、フローが整い、サポート対応を完了した顧客にアンケート調査を送信するようになります。

FAQ