コードのタスク

コードタスクについて

コードタスクでは、カスタム JavaScript を使用して、ワークフロー内の他のタスクの前または後に、データ操作、書式設定、および計算操作を実行できます。たとえば、コードタスクを使用して、API 呼び出しの戻り出力をよりユーザフレンドリな結果に変換できます (非テクニカルマネージャに結果を伝達する必要がある場合など)。その後、変換された結果を、マネージャに電子メールを送信する電子メールタスクに差し込むことができます。

コードタスクの設定

1. 以下にナビゲートします。 スタンドアロンの [ワークフロー] ページ または アンケートの［ワークフロー］タブ.
   
2. [ワークフローを作成] をクリックします。
3. [イベントの受信時に開始] を選択します。
4. ワークフローに名前を付けます。
   
5. [イベントの選択] をクリックし、ワークフローを開始するイベントを選択します。通常、これは調査回答イベントです。
6. 必要に応じて、プラス記号 (+) をクリックし、[条件] を選択してワークフローに条件を追加します。条件は、ワークフローが起動するタイミングを判断するのに役立ちます。建築条件の詳細については、リンク先のページを参照してください。
   
7. プラス記号 (+) をクリックし、タスクを選択します。
   
8. コードタスクを選択します。
   
9. JavaScript 式をボックスに入力します。コードを記述する際に役立つ情報については、ベストプラクティスに関するセクションを参照してください。
   
   ヒント：コードエディターは編集履歴を保持するため、CTRL + Z（PC）または CMD + Z（Mac）を押してコード変更を元に戻すことができます。SHIFT + CTRL + Y (PC) または SHIFT + CMD + Y (Mac) を使用して、変更をやり直します。
   ヒント：コードを記述すると、ウィンドウにエラーが表示される場合があります。これらのエラーは、実行エラーではなく、構文エラーのチェックです。構文エラーは、アカウントの言語設定に関係なく、常に英語で表示されます。タスクが保存され、ワークフローがトリガされるまで、実行は行われません。
   
10. 必要に応じて、JavaScript コードによって何が実現されるのかを説明するタスクサマリを入力します。
11. コードテストをクリックして、ローカルブラウザでコードを実行します。
    ヒント：これらは異なる環境で行われるため、コードのテストでは、ワークフローで実行する場合とまったく同じ結果が得られない場合があります。
12. {a}テキストの差し込みを追加メニューを使用して、テキストの差し込みをJavaScript式に追加します。テキストの差し込みは、回答者の調査回答の取得など、イベントから値を取得する際に役立ちます。テキストの差し込みは JavaScript 式の実行前に評価されます。
13. コードを消去してやり直す必要がある場合は、[デフォルトにリセット] をクリックします。
14. 終了したら、［保存］をクリックします。
15. コードタスクは、コードタスクの出力を使用するために別のタスクとペアリングされることがよくあります。プラス記号 (+) をクリックし、タスクを選択して、次のタスクを選択します。タスクの概要については、このページを参照してください。
    
    ヒント：後続のタスクを設定する場合、コードタスクの出力はタスクのテキストの差し込みメニューに表示されます。
    

JavaScript 実行の制限

コードタスクに含める JavaScript コードを記述する際は、以下の実行制限に注意してください。

• 最大実行時間: 10 秒
• JavaScript の最大長: 6KB
• 送信 API 要求なし: セキュリティ上の理由から、コードタスクでは他の API またはサービスへの送信要求を行うことができず、実行時に HTTP 要求を使用して他の JavaScript ライブラリを取得することもできません。

JavaScript コードがこれらの制限を超えると、コードタスクは失敗します。ワークフローが失敗した場合は、ワークフローのレポートに移動し、ワークフローが失敗した理由の詳細を確認します。

ベストプラクティス

JavaScript を記述する場合は、以下のベストプラクティスに従います。

• • コードは ES6 構文に準拠している必要があります。
  • コードは、保護された環境で Node.js を介して実行されます。現在、このタスクでは Node.js バージョン 8.10 が使用されています。
  • コードは結果を JavaScript オブジェクトとして返す必要があります。返される結果がこのように書式設定されている場合、カスタムコードから返されるフィールドが自動的に推測され、後続のタスクに適したテキストの差し込みが提供されます。

    例: この例では、複数の結果が返されます。

    function codeTask() {
      return {
        hello: "world",
        foo: "bar",
        status: 200
      };
     }

    例: この例では、単一の結果を返します。

    function codeTask() {
      return {
        result: "hello world",
      };
     }

  • 必要な情報の種類によっては、ロケータの構文を引用符で囲む必要がある場合があります。ロケータを文字列に変換する場合は、引用符を追加する必要があります。オブジェクトに解決される場合は、引用符を追加する必要はありません。

    例: たとえば、以下のコードには引用符が必要です。

    function codeTask() {
        let ticketId = "~{ch://OCAC_31HNMUuEpm3Jg/exports.data.key}";
        ...
     }

  • 引用符が含まれる可能性があるフィールドにテキストの差し込みを使用する場合は、差し込みテキストを引用符で囲む代わりに、テンプレートリテラル (`) を使用する必要があります。

例：ウェブサービスタスクでのコードタスクの使用

この例では、Web サービスタスクでコードタスクを使用する方法を説明します。ウェブサービスタスクでコードタスクを使用して、回答者のアンケート回答をAPIに対応したコードに変換し、戻り値を使用してAPI呼び出しを実行できます。その後、API 呼び出しの結果を取得し、別のコードタスクを使用して、返された値を人間フレンドリな応答に変換できます。

この例では、Qualtricsでレストランファインダーを構築しています。詳細は後で詳しく説明しますが、これを実現する方法の概要を以下に示します。

1. アンケートでは、回答者に食べたい場所と、結果を返す方法を尋ねます。
2. レストラン検索を実行するには、サードパーティーのレストランファインダーアプリを使用します。コードタスクを使用して、調査回答者の回答をサードパーティレストランファインダー API で使用できるフォームに変換します。
3. 次に、Web サービスタスクを使用してサードパーティレストランファインダへの API 呼び出しを実行し、その結果を JSON として返します。
4. 別のコードタスクを使用して、結果の JSON を人間が読み取ることができる形式に変換します。
5. 最後の1つのタスクでこの情報を回答者または自分に送信できます。たとえば、電子メールタスクを使用して、返された結果を含む電子メールを回答者に送信します。

コードタスクを使用したレストランファインダの作成

1. アンケートで、コードタスクにフィードする質問を作成します。ここでは、レストランの検索場所を尋ねる自由回答欄の質問と、結果の並べ替え方法を尋ねる多肢選択式の質問です。
   
2. ワークフローにナビゲートします。
3. 新規ワークフローを登録します。
4. ワークフローイベントの場合は、 調査回答 イベントを選択し、新しい回答の作成時にトリガされるようにイベントを設定します。詳細については、リンク先のページを参照してください。
   
5. プラス記号 (+) をクリックし、タスクを選択します。
6. コードタスクを選択します。
   
7. コードについて、回答者の回答をレストランファインダー API に必要な値に変換します。
   
8. テキストの差し込みを使用して、回答者の回答の出所である質問を取り込みます。
9. 保存をクリックしてタスクを保存します。
10. プラス記号 (+) をクリックし、  タスクを選択します。
    
11. Web サービスタスクを選択し、認証を選択します。詳細については、こちらのページを参照してください。
    
12. アクセスしようとしている URL を入力します。
    
13. クエリ文字列を使用してパラメータを追加します。テキストの差し込みメニュー {a} を使用して、アンケートと以前のコードタスクの値を使用します。

    例：完全に構築された URL は以下のとおりです。

    https://api.example.com/v3/businesses/search?sort_by=~{ch://OCAC_Zt2TNQYggAb6u89/sort_by}&location=${q://QID1/ChoiceTextEntryValue}

    これには、sort_by と location の 2 つのパラメータが含まれます。sort_by の場合、値は最初のコードタスクの結果です。場所の場合、値は自由回答の質問に対する回答です。

14. 必要に応じてタスクの設定を終了します。ヘルプが必要な場合は、Web サービスタスクを参照してください。
    ヒント：ウェブサービスタスクで、予想される戻り値をテストして、API呼び出しが機能することを確認できます。
    
15. 必要に応じて、他のタスクで使用できるカスタム JSON パスを作成します。この例では、検索結果から多数のビジネスを返す「ビジネス」パスを作成します。
    
    ヒント：ウェブサービスタスクをテストした場合、Qualtricsは自動的にJSONパスを識別してここに追加します。不要なものは、ごみ箱アイコンをクリックして削除できます。
16. ［保存］をクリックします。
17. プラス記号 (+) をクリックし、タスクを選択します。
    
18. コードタスクを選択します。
    
19. 現在は、Web サービスタスクから結果の JSON を読みやすい形式に変換する必要があります。ここでは、メールで使用するために HTML に変換します。
    
20. Web サービスタスクから結果の JSON を取得するには、テキストの差し込みメニュー {a} を使用します。
21. ［保存］をクリックします。
    ヒント：テキストの差し込みを使用する場合、テキストの差し込み指定機能が有効でないため、警告が表示される場合があります。ただし、差し込みのテキスト指定子はコードの実行前にフィールドの値で置き換えられるため、これは実行前に解決されます。
22. プラス記号 (+) をクリックし、タスクを選択します。
23. ［メール］を選択します。
    
24. 電子メールタスクを設定します。詳細については、リンク先のページを参照してください。
25. 2 番目のコードタスクの結果をメール本文に差し込みます。これは、レストラン検索の結果を返すものです。
    
    例：メールエディターが差し込まれた回答者の回答と 2番目のコードタスクの結果を下に示します。
    
26. 結果のメールは、回答者が選択した検索結果を返します。
    

FAQ