JSONイベント

JSON イベントについて

クアルトリクスでチケットを作成するリクエストをウェブサイトで行うことを希望されたことはありますか？Qualtricsと自社の社内システムのシームレスな統合を実現したいと考えたことはありませんか？［ワークフロー］タブでタスクをトリガーしたいが、クアルトリクス以外で発生するイベントがあったことがありますか？

JSON イベントにより、外部ソフトウェアが HTTP 要求を介してワークフローを開始できるようになります。Qualtricsのイベントがプラットフォームで追加アクションをトリガするのを待つ代わりに、サードパーティからリクエストを受信するようにJSONイベントを設定するだけです。

制約

JSON イベントは以下のセットアップおよび設定と互換性がありません:

• HTTP 以外のすべて (メッセージキュー、SMS など)。
• 送信 HTTP コール。
• XML を処理します (XML 要求本文は無視されます)。
• JSON 以外の処理を行います。
• X-API-TOKEN ヘッダまたは修正された HTTP Basic 認証以外の方法で認証します。
  ヒント：OAuthやその他の形式の認証は、JSONイベントと互換性がありません。
• JSON 本文で JSONPath クエリを使用しても対応できない JSON 解析。
• API レートの制限である 1 分あたり 3,000 を超える呼び出し。
• 100 KB を超えるペイロード。

サポートされる権限のタイプ

トークンベースの認証/ヘッダ認証

リクエストのヘッダから API トークンを X-API-TOKEN として渡すことで、認証できます。

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

     "surveyId": "SV_012345678912345",

     format": "csv"

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

HTTP 基本認証

Basic 認証は通常、username:password の Base64 エンコードバージョンです。ただし、セキュリティ向上のため、Qualtricsではusername:x-api-token（ユーザー名：x-api-token）のBase64エンコード文字列を使用します。

基本認証を使用するには、HTTP 要求でヘッダを設定する必要があります。特定のヘッダは権限です。

 demo@qualtrics.com:f8gIK7G6GFH985Y4

 基本 ZGVtb0BxdWFsdHJpY3MuY29tOmY4Z0lLN0c2R0ZIOTg1WTQ=

JSON イベントの設定

1. 最初に、ワークフローを登録する必要があります。スタンドアロンワークフローページに移動します。
   
   ヒント：JSON イベントは、 プロジェクトの [ワークフロー] タブなど、アンケートで収集したデータが含まれます。ワークフローが明示的に関連している場合にのみ、特定のプロジェクトにワークフローを追加することをお奨めします。(たとえば、そのプロジェクトを JSON イベントで配布する場合など)。
2. ワークフロータブが表示されていることを確認します。
3. [ワークフローを作成] をクリックします。
4. [イベントの受信時に開始] を選択します。
5. JSON イベントを選択します。
   
6. 必要に応じて、JSON イベントの目的を記述する Trigger summary を指定します。
7. URL が与えられます。これを使用して、Postman社内、社内システム、またはその他の同様のアプリケーションを使用して、Qualtricsの外部から新しいワークフローを呼び出します。コピーするには、URL コピーをクリックします。
8. デフォルトでは、JSON イベントには認証が必要です。認証されていないリクエストを許可する場合は、［クアルトリクスによる認証を要求］を無効にできます。
9. これで、イベントデータを定義することができます。これにより、受信依頼からデータが取得されます。開始するには、詳細設定をクリックします。
   
   ヒント：［テスト］セクションの詳細については、以下の「イベントの記録」を参照してください。
10. 左側のボックスに JSON フィールド名を入力します。右側のボックスで、イベントデータ内の場所 (HTTP 要求本文) を指定します。
    ヒント：場所はJSONPath形式にしてください。JSONPath 構文のクイックガイドについては、以下の表を参照してください。
11. 別のフィールドを追加するには、[JSON フィールドを追加] をクリックします。
12. QUERY パラメータを追加する場合は、QUERY パラメータセクションに追加します。これらのパラメータと API での動作の詳細については、パラメータに関する API 文書を参照してください。
    警告: QUERY パラメータを使用して個人を特定できるデータを渡すことはお奨めしません。個人を特定できる情報や機密データは、POST の方が安全であるため、可能な限り POST 本文を通過する必要があります。質問や懸念事項がある場合は、Qualtricsサポートにお問い合わせください。
13. 項目を削除するには、マイナス符号 ( – ) をクリックします。
14. 変更を保存するには、保存をクリックします。
15. プラス記号 (+) をクリックすることで、ワークフローに条件とタスクを追加できるようになりました。条件によってワークフローが実行されるタイミングが決定され、タスクはワークフローの結果になります。以下を参照してください。 ワークフローの概要 をご覧ください。
    

イベントのキャプチャ

外部 API イベントを作成する場合、ポスト本文からのデータの解析が必要になる場合があります。ただし、このデータの解析が困難な場合があります。外部 API の送信内容を確認するには、以下の手順に従います。

1. JSON イベントをクリックします。
   
2. デフォルトでは、このワークフローオプションの他のタスクで差し込みテキストとして使用できるように、テスト結果から JSON フィールドをキャプチャが有効化されます。このオプションにより、ワークフロータスクの追加時に、ペイロードの本文に解析されたフィールドが自動的に差し込みテキストとして使用可能になります。
   
3. [新しいテストの実行] をクリックします。
4. 外部システムからのイベントの受信をクアルトリクスが待っていることを示すメッセージが表示されます。外部 API を起動します。
   ヒント：このテストをキャンセルするには、［テストをキャンセル］をクリックします。
5. テストが成功すると、サーバへ正常に接続されましたというメッセージが表示されます。ペイロードが解析され、ウィンドウに追加されます。
6. 必要に応じて、［新しいテストを実行］をクリックして別のテストを実行します。このオプションをクリックした後、次の API 呼び出しを実行する必要があります。
7. ［保存］をクリックします。

JSONPath 構文

以下の表に、JSONPath 構文の基本の一部を示します。これらはQualtricsでは確立されていませんが、JSONで使用される標準です。

JSONPath 構文の例

この例では、JSON オブジェクトを指定した JSONPath テーブルの使用方法について説明します。

これは JSON オブジェクトです。

{
 "eventDescription": "Monthly Revenue",
 "stores
": [
 {
 "name": "Acme Store",

 "total": 1000000,
 "topItem":

 { "price": "50", "description": "Anvil" }

 },
 {
 "name": "name":

 250000,
 "pepitem": 250000,
 "topItem":

 {
"価格", "4",


 "説明": "4", "説明": "説明" {

ここで、JSONPath テーブルに表示される戻り値をより明確にするために追加する必要があります。

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


 { "price": "50", "description": "Anvil

"-> 月次収益
 ..-> 50

 -&izza; ["Acperi" "Acper
me Store", "The Banana Stand", "Pizza Planet"]
 [] -> Acme Store


 [,] [] - 
:











:
 Un

known macro: {"name"}





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

 { "price": "50", "description": "Anvil" } 
 }] 

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

 "topi

"

ノード JavaScript の API 例

以下の例は、イベントデータの書式設定時に従うことができる基本テンプレートです。

var request = require('request-promise');
 var surveyId = "SV_XXXXXXXXXXXX";
 var triggerId = "OC_XXXXXXXXX";
 var brandId = "YOUR_BRAND_ID";
 var userId = "UR_XXXXXXXXXXXXXXX";


 var datacenter = "xx1";
 var apiToken = "YOUR_QUALTR.JSON" triggers"
     contextId=" + surveyId + "&userId=" + userId + "&brandId=" + brandId + "&triggerId=" + triggerId;
 var payload = {
    "text",
        ]
     "object": {
         "number": 4
    ,
,
     "array" "array": ["a",


    
    
    
    
        "X-API-TOKEN": apiToken
     }
;

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

例：Freshdeskとの統合

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

1. Qualtricsで、［イベント］を［JSON イベント］に設定します。
   
2. URL をコピーします。
   
3. 新しいタブで Freshdesk にログインします。
4. [管理] セクションで、設定するルールの種類に最も適したオプションに移動します。
   
   ヒント：Freshdeskのサポート文書で、Dispatch’r（派遣担当）、Supervisor（スーパーバイザー）、Observer（オブザーバー）の違いを学ぶ。
5. 新規ルールを登録します。
   
6. クアルトリクスでタスクをトリガーするFreshdeskイベントを決定する条件を設定します。
   
   例：Freshdeskエージェントによってチケットのステータスが任意のステータスから解決済みに変更された場合は、Qualtricsを使用してCSATアンケートを送信します。
7. 新しいアクションを追加し、Trigger Web Hook を選択します。
   
8. 要求タイプをPOST に設定します。
   
9. コールバック URL で、ステップ 2 の JSON イベント URL をペーストします。
10. トークン認証を使用するには、カスタムヘッダを追加し、X-API-TOKEN: を入力して API トークンと同じに設定します。
    
11. HTTP基本認証を使用するには、［認証が必要］をクリックし、クアルトリクスユーザー名を追加してから、パスワードの代わりにAPIトークンを入力します。
    
12. エンコーディングが JSON であることを確認します。
    
13. 受け渡すコンテンツをマニュアルで選択するか、詳細を選択して JSON 本文を入力します。
14. ルールを保存します。
15. Qualtricsでワークフローを終了します。この例では、 XM Directoryのタスク.
    
16. 開始する準備ができたら、アンケートの変更を忘れずに公開してください。

例: ServiceNow との統合

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

1. Qualtricsで、［イベント］を［JSON イベント］に設定します。
   
2. URL をコピーします。
   
3. 新しいタブで、ServiceNow 開発者インスタンスにログインします。
4. REST メッセージを選択します。
   
5. 新規をクリックします。
6. REST メッセージに名前を付けます。
   
7. エンドポイントフィールドで、ステップ 2 でコピーした URL をペーストします。
8. 認証タイプを基本に変更します。
9. HTTP 要求タブに移動します。
   
10. ダブルクリックして X-API-TOKEN を追加します。
11. ダブルクリックして API トークンをペーストします。
    
12. 新しい行に Content-type という名前を追加します。
13. 値を application/json に設定します。
14. ［送信］をクリックします。
    
15. 残りのメッセージを再度開きます。
    
16. HTTP メソッドで、新規をクリックします。
    
17. メソッドに名前を付けます。
    
18. HTTP メソッドを POST に設定します。
19. 認証タイプを親から継承に設定します。
20. ［送信］をクリックします。
21. 作成した POST HTTP メソッドを再度開きます。
    
22. ページの下部で、スクリプト使用状況のプレビューを選択します。
    
23. テキストをコピーします。
24. ビジネスルールを検索して選択します。
    
25. 新規を選択します。
26. テーブルを選択します。
    
27. 詳細を選択します。
28. ビジネスルールが実行されるタイミングを決定します。
    例：テーブルに対して［インシデント］を選択し、解決済みのチケットに対して CSAT 調査を送信する場合は、［インシデント］ステータスが ［解決済み］に変わったときにこのルールを実行する必要があることを示す条件を追加できます。
    ヒント：クアルトリクスサポートが、JSON イベントを設定し、ServiceNowを通じてイベントに接続するのに役立ちます。ただし、回答できない ServiceNow 機能に関する質問がいくつかある場合があります。ビジネスルールの実行方法/時期について質問がある場合は、ビジネスルールの動作に関する ServiceNow の文書を参照してください。
29. 詳細設定タブに移動します。
    
30. 手順 22 からコピーしたコンテンツを［ここにコードを追加］に貼り付けます。
    
31. 本文を追加します。ここでは、Qualtricsに渡す情報を伝えます。
    

    例: これは、この項目に含める最終コードの例です。このコードのほとんどは ServiceNow によって提供される送信メッセージであり、例によって異なります。残念ながら、Qualtricsサポートではカスタムコーディングをサポートできません。コードに問題がある場合は、ServiceNowのコミュニティに連絡してサポートを依頼してください。

    コードの太字部分には、元のコードには含まれていない 3 つの追加機能 (ユーザ ID とインシデントステータスを抽出する JSON 本文、および CSAT を送信できるようにインシデント顧客の電子メールアドレスを取得するコール (以下イタリック)) が含まれています。さらに質問がある場合は、ServiceNow の文書を参照し、コミュニティを参照してください。

    (関数 executeRule(current, previous /*null when async*/) {
    
         // ここにコードを追加
        
      try { 
         var r = new sn_ws.RESTMessageV2('Qualtrics JSON Event ', 'JSON Event POST');
         var body = {
              "User ID": gs.getUserID()
              "incident state": 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 response.getBody();
         
    
     var httpStatus = response.
    
    getStatusCode();
          gs.addInfoMessage(httpStatus);
        
    
         

32. 要求に本文を追加します。前のステップのコードの太字の斜体部分の下に、以下を追加します。

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

33. ［送信］をクリックします。
34. Qualtricsでワークフローを終了します。CSATアンケートの例を続けるために― XM Directoryのタスク.
    
35. 開始する準備ができたら、アンケートの変更を忘れずに公開してください。

例：Microsoft フローによる Microsoft Dynamics との統合

JSON イベントにより、Microsoft Dynamics のイベントでチケットの作成やアンケートの配信などのタスクをクアルトリクスでトリガーできるようになります。たとえば、Microsoftのアカウントレコードを削除するたびに、終了の質問を尋ねるQualtricsアンケートをアカウント所有者に配信できます。（例：お会いできて申し訳ありません！お忙しいところはいかがでしたか。改善方法)

JSON イベントを Microsoft Dynamics で発生するアクションと統合するには、実際には Dynamics ではなく Microsoft Flow 内で設定を行う必要があります。Microsoft Flow はすべての Microsoft Dynamics アカウントに無料で提供されるため、ここから Dynamics の情報を使用してフローにログインできます。

1. Qualtricsで、［イベント］を［JSON イベント］に設定します。
   
2. URL をコピーします。
   
3. 別のタブで、https://us.flow.microsoft.com/en-us/ に移動し、Microsoft Dynamics の情報を使用してフローにログインします。
4. 左側の My Flows を選択します。
   
5. 新規登録をクリックし、自動 – 開始空白を選択します。
6. フローに名前を付けます。
   
7. トリガを選択します。これは Microsoft で発生し、クアルトリクスでタスクを開始するイベントです。目的を果たすものは何でも選択できますが、この例では “レコードが削除されたとき (Dynamics 365)” を選択します。
8. 作成をクリックします。
9. 組織名で Dynamics アカウントにログインします。
   
10. エンティティ名で、レコードまたはファイルのタイプを選択します。この例では［アカウント］を使います
11. 次のステップへをクリックし、アクションの追加を選択します。
12. HTTP を選択します。
    
13. メソッドを POST に変更します。
14. URI フィールドに JSON イベント URL をペーストします。
15. トークン認証を使用します。ヘッダの下に X-API-TOKEN と入力し、その横にあるフィールドに API トークンをペーストします。
16. Body で、JSON 本文を入力できます。これは、DynamicsからQualtricsに渡す情報を決定するのに役立ちます。
    ヒント：［動的コンテンツを追加］ボタンを使用して、クアルトリクスに引き渡すダイナミックレコードフィールドを選択します。スクリーンショットに示されている適切な JSON 形式に従っていることを確認します。動的コンテンツのトラブルシューティングについては、Microsoft サポートにお問い合わせください。
17. 終了したら、保存をクリックします。
18. Qualtricsでワークフローを終了します。この例では、 XM Directoryのタスク.
    
19. 開始する準備ができたら、アンケートの変更を忘れずに公開してください。

例：Genesys PureCloudとの統合

JSON イベントを使用して、Genesys PureCloud と統合し、サポート電話またはチャットインタラクションの完了後にフォローアップ調査を顧客に送信することができます。

1. 送信するサーベイで、ワークフローにナビゲートします。
   
2. 新しいイベントベースワークフローを登録します。
3. ワークフローイベントの場合は、JSON イベントを選択します。
   
4. URL コピーをクリックして、イベントエンドポイントをクリップボードにコピーします。
   
5. JSON イベントウィンドウを閉じずに、ブラウザで新しいタブを開き、Genesys にナビゲートします。
6. ［管理］ページに移動します。
   
7. アクションをクリックします。
8. ［アクションを追加］をクリックします。
   
9. 統合名として Web サービスデータアクションを選択します。
   
   ヒント：［Web サービスデータアクション］を選択するオプションがない場合は、統合を有効にする必要があります。詳細については、こちらのページを参照してください。
10. アクションにアクション 名を指定します。
11. ［追加］をクリックします。
12. 設定タブにナビゲートします。
    
13. 契約タブに移動します。
14. 契約入力で、JSON を選択します。
15. Qualtrics に送信されるプロパティを設定します。

    例: 以下の例では、メールアドレス、電話番号、名、および姓が渡されます。

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

16. 設定タブに移動します。
17. 要求タイプを POST に変更します。
18. ［リクエストURLテンプレート］フィールドで、クアルトリクスのJSONイベントからURLを貼り付けます。
19. ヘッダ追加をクリックします。
    
20. キーボックスに X-API-TOKEN と入力します。
21. ［値］ボックスに、Qualtrics APIトークンを入力します。
22. テストタブに移動します。
23. プロパティのテスト値を入力します。
24. アクション実行をクリックします。
25. アクションが成功したかどうかは Genesys から通知されます。失敗した場合は、問題の解決に役立つエラー応答が表示されます。
    
26. クアルトリクスでJSONイベントに戻り、プロパティがクアルトリクスに正常に渡されたことを確認します。
27. ［保存］をクリックします。
28. プラス記号 (+) をクリックしてから Task をクリックし、JSON イベントがトリガされたときに実行するタスクを設定します。ここでは回答者にアンケートを送信するため［XM Directoryタスク］を選択します
    ヒント：タスクの設定時に、テキストの差し込みメニューを使用して、Genesysから渡された値（顧客のメール、名前など）を使用します。
29. クアルトリクスでタスクを設定したら、［Genesys］に戻り、［保存して公開］をクリックします。
    
30. はいをクリックします。
31. ［管理］ページに移動します。
32. アーキテクトをクリックします。
33. ［フロー］ドロップダウンメニューで［アンケートの招待］を選択します。
34. ［追加］をクリックします。
35. フローに名前、説明、および部門を指定します。
36. ［フローを作成］をクリックします。
37. ツールボックスのデータセクションで、データアクションの呼出を選択してフローのドロップボックスにドラッグします。
38. アクションに名前を付けます。
39. [カテゴリ] で、[Web サービスデータアクション] を選択します。
40. データアクションの場合は、前に作成したデータアクションを選択します。
41. 各プロパティの横にあるドロップダウンメニューをクリックし、[式] を選択します。
42. プロパティ値には、プロパティごとに送信されるデータを入力します。[] ボックスに入力するとフィールドが自動的に入力されます。
    ヒント： このページには、アンケートの招待フローに含まれるすべてのデフォルトプロパティがあります。また、顧客の連絡先情報が不足している場合や、追加の書式設定が必要な場合にも、複雑な表現を使用することができます。
    ヒント：連絡先情報の先頭に［Survey.CustomerContact］が表示されます。
43. フローの一番下のボックスをクリックします。
44. ［ツールボックス］、［アンケートの招待］、［アンケートを中止］の順に選択します。
45. 処置の optOut を選択します。
46. 公開をクリックします。Genesys によってフローが検証され、公開されます。これが完了すると、フローが設定され、サポートインタラクションの完了時に顧客への調査の送信が開始されます。

FAQ