ユーザーアクティビティを取得するためのデータストリームアクションの作成

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：11分

    • SaaS アプリケーションからユーザーアクティビティを取得するデータストリームアクションを作成します。

    始める前に

    既存の ServiceNow® 統合ハブ スポークを使用している場合は、ユーザーアクティビティを取得するためのデータストリームアクションを作成する代わりに使用できるかどうかを確認してください。

    データストリームアクションの詳細については、「 データストリームアクション」を参照してください。

    必要なロール：flow_designer または admin

    このタスクについて

    ユーザーアクティビティを監視して、会社が料金を支払っているのに使用されていないソフトウェアサブスクリプションを見つけます。これらの未使用のサブスクリプションを再利用して、会社のソフトウェア費用を削減できます。

    データストリームアクションを作成する前に、意味のあるユーザーアクティビティを定義する方法を決定します。意味のあるアクティビティは、ユーザーアクションの組み合わせにすることができます。ユーザーアクティビティメトリクスごとに個別のデータストリームアクションを作成します。たとえば、ミーティング統合 Webex ベースシステムでは、意味のあるアクティビティをミーティングの開催として定義します。1 つのデータストリームアクションを使用して、すべてのユーザーの最後に開催された会議の日付を取得します。Webex Meetings 統合に有意義なアクティビティとしてログインを含める場合は、2 つ目のデータストリームアクションを作成して、すべてのユーザーの最新のログイン時間を取得します。

    ユーザーを取得するデータストリームアクションは、最終ログイン時間などのユーザーアクティビティメトリクスを返す場合があります。この場合、追加のユーザーアクティビティメトリクスを定義する場合を除き、ユーザーアクティビティを取得するためのデータストリームアクションやユーザーアクティビティを取得するためのサブフローを作成する必要はありません。ユーザーを取得するためのサブフローで、このユーザーアクティビティメトリクスが [ユーザーサブスクリプションをアップサート] アクションの最後のアクティビティ入力として設定されていることを確認してください。

    手順

    1. 移動先 すべて > Flow Designer > デザイナー.
    2. [ 新規] をクリックし、[ データストリーム] を選択します。
    3. フォームのフィールドに入力します。
      表 : 1. アクションプロパティフォーム
      フィールド 値
      名前 任意の名前。たとえば、[ ユーザーアクティビティを取得 (Get User Activity)] などです。
      アクセス可能 すべてのアプリケーションスコープ。
      カテゴリ このフィールドは空のままにします。
      保護 なし。
      アプリケーション SaaS アプリケーションと統合するためのスポークアプリ。このスポークアプリは、既存の 統合ハブ スポークでも、作成した新しいスポークでもかまいません。
      インフロー注釈 このフィールドは空のままにします。
      説明 選択内容の説明。
    4. [送信] をクリックします。
    5. [Action Outline] の [Inputs] セクションで、[ Create Input] をクリックします。
    6. 過去の検索時間の入力を追加します。
      表 : 2. 入力
      ラベル 名前 タイプ 必須
      過去の検索時間 look_back_time 日付/時刻 はい
    7. 使用している API が要求に対してユーザー認証を必要とする場合は、認証用の入力を追加します。
      一般的なユーザー認証入力の例としては、admin ユーザー ID とサイト名があります。特定のケースでのユーザー認証の要件については、選択した API のドキュメントを参照してください。API にアクセストークンが必要な場合は、 後で認証情報値 変数が自動的に作成されます。アクセストークンを入力として追加する必要はありません。

      完成したデータストリームアクションをサブフローで使用する場合は、これらの入力として渡す値を定義します。

    8. [Action Outline] で [ Request ] をクリックします。
    9. フォームのフィールドに入力します。
      表 : 3. [要求] フォーム
      フィールド 値
      データをどのように取得しますか。 [REST ステップ] または [SOAP ステップ] のいずれかを選択します。どちらを選択するかは、統合する SaaS アプリケーションの API によって異なります。
      ページネーションを有効化 選択済み。
      各要求の前にスクリプトを実行 未選択。
    10. [アクションアウトライン] の [ページネーション設定] ステップ をクリックします。
    11. SaaS API で使用されるクエリパラメーターに基づいてページネーション変数を定義します。

      オフセットベースのページネーションを使用している場合は、制限/オフセットページネーションテンプレートを使用して、ページネーション構成をプリロードします。

      注:
      予約済みの getNextPage 変数の値によって、結果の別のページを要求するかどうかが決まります。getNextPage 変数が true である限り、アクションは次のページの要求を送信し続けます。
    12. ページネーション変数を更新するためのページネーション変数スクリプトを記述します。

      スクリプトは要求ごとに実行されます。ページネーションテンプレートを使用している場合は、必要に応じてプリロードされたスクリプトを調整します。

      次の画像は、ページネーションセットアップ手順の完了した例を示しています。この例は、 Webex Download Subscriptions サブフローで使用される Get Users データストリームアクションからのものです。

      ページネーションセットアップステップ
      注:
      ページネーション変数は、文字列データ型のみをサポートします。数学演算を実行するには、値を整数に変換し、必要な演算を実行してから、文字列に変換し直します。
    13. データの取得方法について選択したオプションに応じて、[アクションアウトライン] で [ SOAP ステップ ] または [REST ステップ ] をクリックします。
    14. [SOAP] を選択した場合は、次のようにフォームに入力します。
      表 : 4. SOAP ステップフォーム
      フィールド 値
      接続の詳細
      接続 接続エイリアスを使用。
      接続エイリアス 統合プロファイルを作成したときに作成した接続エイリアス。統合プロファイルをまだ作成していない場合は、 手順に従って接続エイリアスを使用してカスタム統合プロファイルを作成します。
      エンドポイント この値は、接続エイリアスを選択すると自動的に入力されます。エイリアスにリンクされた HTTP(s) 接続レコードの接続 URL に設定されます。
      要求の詳細
      エンベロープの作成 手動。
      SOAP アクション 意味のあるユーザーアクティビティのリストを取得するための API 要求。たとえば、ミーティング統合 Webex ベースシステムは、意味のあるユーザーアクティビティをミーティングを主催するものとして定義し、 LstsummaryMeeting 要求を使用してすべてのミーティングのリストを取得するようにします。適切な要求を選択するには、選択した API のドキュメントを参照してください。
      SOAP エンベロープ すべてのユーザーのリストを取得するための XML 要求メッセージ。XML 要求メッセージの記述方法については、選択した API のドキュメントを参照してください。一般に、ヘッダーには、ユーザー認証用の入力変数と、アクセストークンとしての 認証情報値 変数を含める必要があります。本文には、意味のあるユーザーアクティビティのリストを取得する要求、[ 過去の検索時間 ] 入力として設定された開始日、およびページネーションセットアップステップからの変数を含める必要があります。
      注:
      SOAP エンベロープの例については、「 Webex ユーザーアクティビティの更新」サブフローで使用される「ユーザーアクティビティデータストリームを取得」アクションを参照してください。
    15. [REST] を選択した場合は、次のようにフォームに入力します。
      表 : 5. REST ステップフォーム
      フィールド 値
      接続の詳細
      接続 接続エイリアスを使用。
      接続エイリアス 統合プロファイルを作成したときに作成した接続エイリアス。統合プロファイルをまだ作成していない場合は、 手順に従って接続エイリアスを使用してカスタム統合プロファイルを作成します。
      ベース URL この値は、接続エイリアスを選択すると自動的に入力されます。エイリアスにリンクされた HTTP(s) 接続レコードの接続 URL に設定されます。
      要求の詳細
      ビルド要求 手動。
      リソース パス リソースへのパス。この値はベース URL に追加されます。リソースパスの構築方法については、使用している API のドキュメントを参照してください。
      HTTP メソッド GETです。
      クエリ パラメーター ページネーションのパラメーターを追加します。これらの値は、ページネーションセットアップステップで作成した変数として設定します。
      要求が開始日から現在の日付までの結果を返すように、開始日に別のパラメーターを追加します。この値を [ 過去の検索時間 ] の入力として設定します。
      注:
      ルックバック時間の入力日付/時刻変数が、使用している API に対して正しい形式になっていることを確認してください。文字列などの別のデータタイプを再フォーマットまたは変換する必要がある場合は、アクション前処理スクリプトステップでこれを行うことができます。

      次の画像は、REST ステップの完成した例を示しています。この例は、 Jira ユーザーアクティビティの更新サブフローで使用される [監査ログデータストリームを取得] アクションからのものです。

      REST ステップ
    16. [Action Outline] の [ Parsing ] をクリックします。
    17. フォームのフィールドに入力します。
      表 : 6. フォームを解析中
      フィールド 値
      各レコードをどのように識別しますか。 JSON/XML スプリッター
      各アイテムをどのように解析してオブジェクトにしますか。 スクリプトパーサー
    18. [Action Outline] の [ Splitter step] をクリックします 。
    19. フォームのフィールドに入力します。
      表 : 7. スプリッターステップフォーム
      フィールド 値
      ソースフォーマット API 応答によって返される形式に応じて、[ XML ] または [JSON] を選択します。
      アイテムパス 応答メッセージ内の意味のあるアクティビティ要素への絶対パス。応答メッセージの形式については、使用している API のドキュメントを参照してください。
      • XML アイテムパスの例: /message/body/meeting
      • JSON アイテムパスの例: $.data.meeting
    20. 「アクション・アウトライン」の 「出力 」をクリックします。
    21. [ Create Output (出力の作成)] をクリックし、変数を次のように編集します。
      表 : 8. アクションの出力
      ラベル 名前 タイプ 必須
      targetObject targetObject オブジェクト いいえ
    22. targetObject の子アイテムを追加して、ユーザーのメールと有意義なアクティビティの日付を保存します。
      たとえば、XML 応答は次のようになります。
      <message>​
  <body>​
    <meeting>
      <meetingID>​12345</meetingID>​
      <startDate>​08/13/2019 20:08:16</startDate>​
      <hostEmail>​email@email.com</hostEmail>​
    </meeting>​
    <meeting>
      ...
    </meeting>
  </body>​
</message>
      この応答では、次のように子アイテムを追加します。
      表 : 9. targetObject の子アイテム
      ラベル 名前 タイプ 必須
      メール メール 文字列 いいえ
      last_activity last_activity 文字列 いいえ
    23. 「アクション・アウトライン」で、「 スクリプト・パーサー・ステップ」をクリックします。
    24. 応答内の意味のあるアクティビティ要素ごとに targetObject 出力オブジェクトを作成し、それぞれをアクティビティの日付とユーザーのメールを targetObject 子アイテムにマッピングします。

      パーサースクリプトは、ユーザー要素ごとに実行されます。

      注:
      これらの例は、応答に含めることができる要素の種類を示しています。これらのスクリプトを直接コピーしないでください。使用している API のドキュメントに記載されている要素名を使用します。
      XML 応答を解析するスクリプト例。 
      (function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.email = xmlDoc.getNodeText('/meeting/hostEmail');
    outputs.targetObject.last_activity = xmlDoc.getNodeText('/meeting/startDate');
})(inputs, outputs)
      JSON 応答を解析するスクリプトの例。 
      (function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.email = record.hostEmail;
    outputs.targetObject.last_activity = record.startDate;
})(inputs, outputs)
    25. データストリームアクションをテストするには、[ テスト] をクリックします。
      1. エラーの詳細については、テスト結果とシステムログを表示します。
        システムログを表示するには、次の場所に移動します システムログ > システムログ > すべて.
      2. データストリームアクションにエラーが発生した場合は、正しいエンドポイントを使用していることと、API リクエストとレスポンスが想定どおりに構成されていることを確認してください。
    26. データストリームアクションが期待どおりに動作していることを確認したら、[ 公開] をクリックします。