カスタム変数

Insights always ingests data via the pre-defined fields available in the Insights data model, but Admins can also configure custom variables extracted from robot logs and queues to use for calculating specific KPIs or building more specialized dashboards.

ヒント:

1. プロセスにカスタム変数を含めるには、まず Studio の [UiPath.System.Activities.AddLogFields] アクティビティを介してその変数がオートメーションのログに追加されていることを確認してから、取り込むためにその変数を選択する必要があります。
   • プロセスのカスタム変数は、既定のロボット ログ (プロセスが開始/終了しました) および [メッセージをログ] アクティビティで書き込まれたすべてのメッセージとともに送信されます。 変数が設定されていない場合は、必ず [メッセージをログ] アクティビティを記述してください。
2. キューのカスタム変数を含めるには、まずその変数が Studio の以下のアクティビティを介してワークフローに追加されていることを確認してください。その後、それらの変数を取り込むよう選択する必要があります。
   • 固有データには UiPath.System.Activities.AddQueueItem アクティビティを使用します。
   • 出力データと分析データには UiPath.System.Activities.SetTransactionStatus アクティビティを使用します。
3. カスタム変数が選択されているときにビジュアリゼーションを作成できます。
4. カスタム変数を無効化すると、その変数を参照している既存のダッシュボードが動作しなくなる可能性があります。 同じビジュアリゼーションにカスタム変数をさらに追加しても、ダッシュボードが破損することはありません。
5. [キュー アイテムを追加] アクティビティにカスタム フィールドを追加済みの場合は、トランザクション アイテムを [成功] または [失敗] のいずれかに指定するだけでよく、[出力データ] または [分析データ] のプロパティに入力する必要はありません。 [キュー アイテムを追加] アクティビティでフィールドを指定しなかった場合は、ステータスの設定時に [トランザクション アイテムを設定] アクティビティに追加する必要があります。
6. カスタム変数を使用する場合、ジョブ レベルの情報にはロボット ログを使用し、キュー レベルの情報にはキュー アイテムを使用することをお勧めします。キューを使用してロボット ログを使用すると、予期しない結果が生じる可能性があります。

組織範囲のダッシュボードでカスタム変数を使用する

組織範囲のダッシュボードでカスタム変数を使用する場合は、以下の点を考慮してください。

• テナント ビューの [カスタム変数を設定] ウィンドウから抽出されたカスタム変数のみが、組織範囲のカスタム変数設定セクションに表示されます。テナントから抽出されないカスタム変数は、組織範囲のダッシュボードには表示されません。
• テナント範囲のカスタム変数を変更すると、組織範囲のカスタム変数は組織で無効化されます。すべての変更をダッシュボード内に表示させるため、変更後には必ず再度有効化してください。
• ROI セクションとカスタム変数セクションは読み取り専用です。

カスタム変数を設定する

カスタム変数を設定するには、管理者は次の手順に従う必要があります。

1. Insights の任意のページの右上隅にある 3 点リーダー メニューをクリックして開き、[カスタム変数を設定] を選択します。設定ページが開き、抽出できるすべてのカスタム フィールドが一覧表示されます。

2. 設定ページの上部に表示された、プロセスまたはキューのタブをクリックして、どちらのカスタム変数を設定するか決定します。

   

3. [抽出] 列で、ダッシュボードの構築に使用するカスタム変数を選択します。

4. [型] 列でカスタム変数の型を選択します。[String]、[Number]、[DateTime] から選択できます。

   重要:

   • フィールドには最大で 40 文字を入力でき、この数を超えた文字は切り捨てられます。40 文字を超える文字を追加するには、Insights.Etl.Json.MaxStringLen フラグを変更します。このフラグを Orchestrator の Web 構成に追加し、プロジェクトのニーズに従って値を設定できます。以下に例を示します。

   <add key="Insights.Etl.Json.MaxStringLen" value="60" />

   • バックフィルの進行状況には、すべてのプロセスまたはキューからのカスタム変数の抽出の進行状況が表示されます。バックフィルの最新の進行状況を確認するには、ページを更新する必要があります。データのサイズによっては、少し時間がかかる場合があります。カスタム変数の値は、最新のデータから最も古いデータの順にバックフィルされます。このフィールドは、設定を保存するとすぐに使用できるようになります。100% バックフィルされるまで待つ必要はありません。
   • 変数を抽出できるプロセスまたはキューは最大 500 個です。変数はプロセスまたはキューごとに最大 200 個選択できます。
   • カスタム変数の [型] を [Number] に設定する場合は、変数に , や他の数字以外の文字 ($ など) が含まれていないことを確認してください。これらの文字はサポートされていません。特殊文字が含まれる数値の場合は、[型] として [String] を選択します。
   • カスタム変数の設定が変更されるたびに、その特定のプロセスに対して完全なバックフィルが新規に行われます。バックフィルの時間は、その特定のプロセスに対して Insights データベースに保存されているログの数によって異なります。

5. 設定を保存します。特定のプロセスに対して抽出された変数はすべて、「*プロセス - プロセス名」という名前の Explore に表示され、特定のキューに対して抽出された変数はすべて、「*キュー - キュー名」という名前の Explore に表示されます。

   重要:

   変数を抽出できるプロセスまたはキューは最大 500 個です。変数はプロセスまたはキューごとに最大 200 個選択できます。

   設定されたカスタム変数の数	ハードウェア スケール	プロセスの数	プロセスあたりのロボット ログの数	おおよその抽出時間
   30	大規模	1	1,000,000	5 分
   30	大規模	1	40,000,000	120 分

既存の構成の編集

既存の設定を編集するには、管理者は次の手順に従う必要があります。

1. Insights の任意のページの右上隅にある 3 点リーダー メニューをクリックして開き、[カスタム変数を設定] を選択します。設定ページが開き、抽出できるすべてのカスタム フィールドが一覧表示されます。

2. プロセスとキューのどちらにカスタム変数を設定するかを指定するには、設定ページの上部にある対応するタブを選択します。

3. 以前選択した変数を削除するには、[抽出] チェックボックスをオフにします。

   注:

   カスタム変数を無効化すると、その変数を参照している既存のダッシュボードが動作しなくなる可能性があります。 同じビジュアリゼーションにカスタム変数をさらに追加しても、ダッシュボードが破損することはありません。

4. 変数から [共通] ステータスを削除するには、専用のチェックボックスをオフにします。

5. 変数の型を変更するには、ドロップダウン リストから目的の新しい型を選択します。

6. 設定は忘れずに保存してください。

7. 変更または削除した変数を使用している既存のダッシュボードで、以下の項目を確認します。

   1. 変数を削除した場合は、作成・変更された式、フィルター、またはビジュアリゼーション内から、その変数への参照をすべて削除してください。
   2. 変数の型を変更した場合は、新しい型が引き続き正しく適用されていることを確認してください。
   3. If the variable no longer has Common status, you need to replace the reference to the common variable with the updated per-process value.

設定例

このセクションでは、ダッシュボードでカスタム変数を使用する例を示します。

以下のスクリーンショットでは、「ProcessCount」変数は複数のプロセスで使用されていますが、「Argument1_Email」変数は 1 つのプロセスでのみ使用されています。

カスタム変数を設定するには、以下の手順に従います。

1. 抽出対象として「ProcessCount」変数を選択し、[String] 型を選択します。変数が使用されるすべてのプロセスの値を取得できるよう、変数を [共通] としてマークします。

2. 「Argument1_Email」変数を有効化して、[String] 型を選択します。この変数は複数のプロセスで使用されないため、[共通] は選択しません。[保存] を選択します。

   

3. ダッシュボード画面に戻って新しいダッシュボードを作成し、新しいタイルを追加します。

4. [ロボット ログ] Explore を選択して、設定済みのカスタム変数を確認します。

   「ProcessCount」変数の [共通] チェックボックスをオンにしたため、この変数は標準データ モデルに追加されており、プロセス名のプレフィックスが付いていないことが分かります。「ProcessCount」変数と異なり、「Argument1_Email」変数では [共通] チェックボックスをオンにしなかったため、こちらのカスタム フィールドは「Log_Email.Argument1_Email」として追加されました。

   

カスタム変数の値が null になるケース

カスタム変数は、以下のセクションで説明するような特定のケースで、値が null になることがあります。

シナリオ 1

ビジュアリゼーションで標準データ モデルのフィールドとプロセス固有のカスタム変数フィールドを組み合わせて使用し、ロボット ログにプロセスのカスタム変数が含まれていない場合、そのプロセスに関連付けられたすべてのフィールドの値は null になります。

このシナリオで null の値を削除する方法は、以下の 2 つです。

オプション 1: カスタム変数をフィルターとして追加し、条件を [ null ではない ] に設定して、ビジュアリゼーションから null 値を削除します。

オプション 2: カスタム変数を含むプロセス名のフィルターを設定します。ただし、このアプローチを採用すると、2 番目のシナリオが発生する可能性があることに注意してください。

シナリオ 2

プロセスによって生成されたすべてのログにカスタム変数が存在しない場合、そのカスタム変数の値を含まないログでは、変数の値が null として表示されます。

この特定のケースの例を以下に示します。

1. [カスタム変数を設定] に移動します。カスタム変数フィールド「Argument1_Email」は、プロセス「Log_Email」でのみ使用されていることが分かります。「Argument1_Email」はプロセス固有のカスタム変数フィールドであるため、[共通] は選択しないでおきます。

   

2. 新規または既存のダッシュボードを開き、タイルを追加します。

3. [ロボット ログ] Explore に移動します。[プロセス名] フィールドとカスタム変数フィールドを選択します。この場合、カスタム変数フィールドは「Log_Email.Argument1_Email」です。

4. [実行] を選択します。 表示される結果は、以下のスクリーンショットのようになります。

   

null 値を削除するには、カスタム変数フィールドをフィルターとして追加します。最後に、ビジュアリゼーションから null 値が削除されるよう、条件を [is not null] に設定します。

注:

上記のケースは 2 つとも、カスタム フィールドの生データを表示している場合に発生します。カスタム変数に関数 (Sum、Average など) を適用すると、null の値は除外されます。

トラブルシューティングと制限事項

トラブルシューティングや制限事項の情報について詳しくは、「トラブルシューティング」をご覧ください。