スコアXMLリファレンス (クラシック)

Experience Optimization の一部の機能は Finder (クラシック) と連携しています。

Nexthink Finder は、Windows のみ対応のデスクトップアプリケーションで、その機能は現在 Nexthink の web インターフェース内で利用可能です。 Nexthink は今やブラウザから直接使用でき、ほとんどの機能は追加のデスクトップアプリケーションを必要としなくなりました。

スコアは XML ドキュメント内で定義されています。この記事ではスコアを定義する XML ファイルのフォーマットについて詳述します。

他の XML ファイル同様、スコア定義は XML ヘッダーから始めなければなりません。 utf-8 エンコードを使用してください:

<?xml version="1.0" encoding="utf-8"?>

XML ヘッダーの後に続くのは、ルート要素です。スコア定義を定義する XML ドキュメントのルート要素の名前は ScoreDef です:

<ScoreDef UID="[<unique identifier>]" Name="[<name of the score>]"
  Object="[device|user]" InObjectView="[true|false]"
  Status="[enabled|disabled]" SyntaxVersion="1"
  DataModelVersion="12">
    <Platforms ...
    <ScopeQuery ...
    <ComputationSchedule ...
    <Thresholds ...
    <CompositeScore|LeafScore ...
</ScoreDef>

ScoreDef 要素に加え、以下の属性を見つけてください:

UIDA

スコアの普遍的にユニークな識別子は、セパレーター付きの16進形式で表現された128ビットの整数です。低衝突確率でこれらを生成するツールが利用可能です。例: f54972e7-0f9c-46ce-8931-bbe31b06f7b4

名前

Finder に表示されるスコアの名前

オブジェクト

スコアが適用されるオブジェクトの種類。 user か device のいずれかです。

InObjectView

スコアが Finder 内の User View または Device View に表示されるかどうか。 User View と Device View はそれぞれ最大5つのスコアを表示可能ですので注意してください。考えられる値は true か false です。

状況

スコアが計算されるべきかどうか。考えられる値は enabled または disabled です。

SyntaxVersion

XML ファイルのスキーマのバージョン。現在は 1 に固定されています。

DataModelVersion

スコアがクエリのために依存する Nexthink データモデルのバージョン。現在は 12 に固定されています。

属性の後には、ScoreDef 内に以下の要素が見つかります:

プラットフォーム

スコアが適用されるプラットフォーム。 Platform 要素内にサポートされている各プラットフォームを列挙します。プラットフォームの考えられる値は windows, mac_os, または mobile です。例:&#x20

<Platforms><Platform>windows</Platform></Platforms>

ScopeQuery

オブジェクトをフィルタリングすることにより、ユーザーやデバイスを取得するためのクエリの範囲を定義します。 Filtering 要素内に NXQL で where 句を書きます。たとえば、デバイス上のスコアからサーバーを除外する場合:&#x20

<ScopeQuery><Filtering>(where device (ne device_type (enum server)))</Filtering></ScopeQuery>

ComputationSchedule

計算入力を持つすべてのリーフスコアを計算するタイミング。スコアを特定の時間に毎日計算する特定の時間か、より頻繁にスコアを計算する一定の時間間隔を指定できます。これは入力が計算でありフィールドではないリーフスコアにのみ適用されます。フィールドベースのスコアは毎分更新されます。主なスコアは、リーフスコアが変更されると、計算入力またはフィールド入力のいずれかで更新されます。日にちの特定の時間を指定するために、0 から 23 までの値を持つ At 要素を挿入します。一定の期間を指定するために、15分、1時間または6時間の値を持つ Every 要素を挿入します。例:

<ComputationSchedule><At>2</At></ComputationSchedule>

しきい値

オプション: スコアのステータスを決定する制限値。特定のステータスにあるためにスコアが超えなければならない最大3つのしきい値を定義できます。 Finder はスコアをそれに応じた色で表示します: 赤、黄色または緑。しきい値を緑から赤へまたは赤から緑へ (黄色はオプション) 常に値を昇順で指定します。各 Threshold 要素には Color 属性およびしきい値の制限値を定義する From 属性と、対応するステータスの名前を定義する Label 属性を持つ Keyword 要素を含めます。しきい値を定義しないスコアには、色が none のしきい値を1つだけ指定します。

例:

<Threshold color="green"><Keyword From="9" Label="good"/></Threshold>

スコア定義の一般的な要素を使い終えたら、単一の合成またはリーフスコア要素を定義に追加します。この最後の要素は、Nexthink データベースに保存された値からスコアを計算する方法を記述します。 LeafScore 要素を ScoreDef に追加すると、スコアは1つの計算または1つのフィールドの値にのみ依存します。反対に、CompositeScore 要素を ScoreDef に追加すると、スコアの組み合わせにより主なスコアを計算します。

実際、合成スコア自体が他の合成またはリーフスコアで構成されており、最大で5レベルのツリーを形成します。最終的に、ツリーの最下層のすべてのノードはリーフスコアでなければなりません。

合成スコアとリーフスコア

CompositeScore と LeafScore は、個々のスコアを計算するために使用されるスコア定義内の要素です。

CompositeScore および LeafScore 要素には、以下の共通の属性があります。

UID

スコアの普遍的にユニークな識別子 (ScoreDef 要素と類似)、

名前

スコアの名前

説明

スコアのテキストによる説明

可視性

オプション: スコアが Finder に表示されるか、どこにも表示されないか、または Portal の数量指標でのみに表示されるか。考えられる値は visible, hidden および visible only in quantity metrics です。デフォルトでは、スコアはどこでも visible です。

重み

オプション: 小数点以下2位までの浮動小数点数で、直近の合成親スコアが加重平均操作を行うときに計算されたスコアの乗数として機能します。以下に合成スコアがどのように計算されるかを確認してください。

共通の属性に加え、CompositeScore と LeafScore の両方の要素はオプションで Document 要素を含みます。 Document 要素には、そのスコアが適用されるオブジェクトに応じてデバイスビューまたはユーザービューのいずれかのスコアタブに表示されるスコアのドキュメントが含まれています。スコアの詳細な説明に加え、スコアのドキュメントには以下が含まれる場合があります。

外部 HTTP リソースへのリンク（例：知識ベース、外部ドキュメントなど）。
Remote Actions を手動でトリガーして不良スコアを表示するデバイスに適切な対応を取るためのリンク。

Document 要素の完全なリファレンスについてはスコアのドキュメントを参照してください。

合成スコアの計算

合成スコアはその直下の子スコアを操作によって組み合わせた結果です。各合成スコアは、子スコアを組み合わせる方法を指定する Operation 要素を宣言します。操作の後には、合成スコアに寄与する子スコアのリストが見つかります:

<CompositeScore UID="[<unique identifier>]" Name="[<name of the score>]"
  Description="[<score description>]" Visibility="[visible|hidden]"
  Weight="[<float>]">
    <Operation>[Average|Min|Max|Sum|WeightedAverage|Multiply]</Operation>
    <!-- 子スコアのリスト -->
    <LeafScore ...
    <CompositeScore ...
    <LeafScore ...
    ...
    <!-- デバイスビューまたはユーザービューで見られるスコアのオプションのドキュメント -->
    <Document ... 
</CompositeScore>

Operation 要素の考えられる値のリストは以下です。

Average

直下の子スコアの算術平均を計算します。

最小

最小の直下の子スコアを取得します。

最大

最大の直下の子スコアを取得します。

合計

直下の子スコアの総和を計算します。

加重平均

直下の子スコアをその Weight 属性で指定された量で掛けた後、算術平均を計算します。

乗算

直下の子スコアの乗算を計算します。

子スコアのリストは、同時に有効化できるスコアの最大数に制限されています。しかしながら、この制限にはネストされたスコアも含まれ、スコアの最大ネストは5レベルです。

リーフスコアの計算

リーフスコアは、Nexthink データベースからの入力値に適用された正規化手順の結果です。入力は、ユーザーまたはデバイスオブジェクトに属するフィールドの値または、NXQL 言語で表されたデバイスまたはユーザーに対する計算の結果のいずれかです。

したがって、LeafScore は Input 要素と Normalization 要素で構成されます。

<LeafScore UID="[<unique identifier>]" Name="[<name of the score>]"
  Description="[<score description>]" Visibility="[visible|hidden]"
  Weight="[float]">
    <Input ...
    <Normalization ...
    <!-- デバイスビューまたはユーザービューで見られるスコアのオプションのドキュメント -->
    <Document ... 
</LeafScore>

その際に、Input 要素は Field 要素または Computation 要素のいずれかを囲みます。

フィールド型の入力には、Field 要素の Name 属性に取得するフィールドの名前を指定します。 NXQL データモデルで規定されたフィールドの名前を記入してください。たとえば、デバイスの WMI ステータスを取得するには、次のように書きます。

<Input><Field Name="wmi_status" /></Input>

計算型の入力は定義がやや複雑です。まず、Computation 要素の属性として計算に名前、説明、そしてユニークな識別子を与えてください。次に、子要素 Query 内に Nexthink データベースから情報を抽出するための NXQL クエリを書いてください。 Query 要素の属性として、リーフスコアの入力として渡すべきクエリの集計またはフィールドを Output に設定します。以前に指定された出力が未定義の場合に返される値を DefaultOutputValue に設定します。計算入力の構造は以下の通りです。

<Input>
  <Computation Name="[<name>]" Description="[<desc>]" UID="[<identifier>]">
  <Query Output="[<name_of_aggregate>|<name_of_field>]"
    DefaultOutputValue="[<value>]">
    <!-- NXQL query -->
    (select (id ...) (from [user|device] ...
    </Query>
  </Computation>
 </Input>

その埋め込まれた NXQL クエリは、取得されたオブジェクト（ユーザーまたはデバイス）の id を選択しなければならず、出力として宣言されたフィールドがある場合、それも選択される必要があります。代わりに、集計が出力として宣言された場合、クエリ内で compute 句内にその集計の計算を含めます。例えば、前の週にデバイスの HTTP リクエスト成功率を計算してリーフスコアへの入力として使用するには、次の Query 要素を書いてください。

 <Query Output="successful_http_requests_ratio" DefaultOutputValue="NULL">
   (select (id) (from device
     (with web_request
       (compute successful_http_requests_ratio)
       (between now-7d now))))
 </Query>

前のクエリにおけるデフォルト出力値として NULL を使用しています。基礎的なフィールドまたは集計が未定義のときにスコア用に値を返す意味がない場合は、デフォルト出力値として NULL を書きます。前の例のクエリでは、そのデバイスが HTTP リクエストを行わなかった場合、HTTP リクエストの比率は未定義です。人工的な値をスコアに強制するよりも、値を返さないことの方が望ましいです。

合成スコアの一部であるが値を持たないリーフスコアは、その合成スコアの計算から除外されます。基礎的な値が不足しているために合成スコアやメインスコアが計算できない場合、結果として値がありません。 Finder は未定義の値を持つスコアについてダッシュマーク (-) を表示します。

リーフスコアへの入力が実際に適正な値を持つ場合、その値を正規化関数を用いてビジネス的な意味を持たせます。スコアの目的は、Nexthink データベースの詳細な測定結果に意味を持たせることです。数量、比率、列挙、あるいは文字列を数値範囲（通常は0から10の範囲）に正規化して、測定された入力に対するユーザーやデバイスの状態を理解しやすくしてください。

Normalization 要素は、入力値を希望する範囲にどのようにマッピングするかを定義します。入力の種類に応じて、異なる正規化関数を適用します。

入力の種類

利用可能な正規化

数値型

ステップ関数
区分的線形関数

列挙型

直接マッピング

文字列型

直接マッピング（オプションのプレースホルダーを含む）

数値入力値をステップ関数で正規化するために、入力値を昇順で持つ Ranges のリストを定義してください（割り当てられたスコアは特定の順序でなくても構いません）。次の例に示す通りです。

<Normalization>
  <Ranges>
    <Range>
      <From Value="0" Score="0" />
    </Range>
    <Range>
      <From Value="0.6" Score="5" />
    </Range>
    <Range>
       <From Value="0.8" Score="10" />
    </Range>
  </Ranges>
</Normalization>

この例は、次のような比率入力のためのステップ関数を定義しています。

入力値が0%から60%（含まない）までの場合のスコアは0です
入力値が60%から80%（含まない）までの場合のスコアは5です
入力値が80%以上の場合のスコアは10です

前述のように、スコアは必ずしも入力値とともに成長するわけではありません。例えば、入力値が80%を超えた場合にスコアをゼロに下げる代替の正規化を考えてください。

<Normalization>
  <Ranges>
    <Range>
      <From Value="0" Score="5" />
    </Range>
    <Range>
      <From Value="0.6" Score="10" />
    </Range>
    <Range>
       <From Value="0.8" Score="0" />
    </Range>
  </Ranges>
</Normalization>

ステップ関数により得られる結果は次のとおりです：

入力値が0％から60％（含まない）までの範囲であれば、スコアは5です。
入力値が60％から80％（含まない）までの範囲であれば、スコアは10です。
入力値が80％以上であれば、スコアは0です。

数値入力値を区分線形関数で正規化するには、ステップ関数に見られるものと似たRangesリストを定義し、今回は線形範囲を限定し、範囲内の最終的なスコア値を指定する追加のTo要素を含めます。

<Normalization>
  <Ranges>
    <Range>
      <From Value="0" Score="0" />
      <To Value="0.6" Score="2" />
    </Range>
    <Range>
      <From Value="0.6" Score="2" />
      <To Value="0.8" Score="9" />
    </Range>
    <Range>
      <From Value="0.8" Score="9" />
      <To Value="1.0" Score="10" />
    </Range>
    <Range>
      <From Value="1.0" Score="10" />
    </Range>
  </Ranges>
</Normalization>

この例は、比率入力を区分ごとに線形で進化するスコアにマッピングする区分線形関数を定義しています：

入力値が0％から60％までの場合、スコアは0から2の範囲です。
入力値が60％から90％までの場合、スコアは2から9の範囲です。
入力値が90％から100％までの場合、スコアは9から10の範囲です。
入力値が100％以上であれば、スコアは10です。

図に示すように、各区間内で線形補間が行われます。たとえば、入力値が30％であれば、スコアは1になります。

To要素のValue属性とScore属性は、区分線形関数が連続するために、次の範囲で定義されたFrom要素のものと等しくなければなりません。最後の範囲では、入力値に制限を課さないようにTo要素を定義していません（仮想の比率入力が100％を超える可能性がある場合に備えて）。

列挙型の入力に対しては、正規化関数が各可能な入力をスコアに直接マッピングする必要があります。例として次のように示します：

<Normalization>
  <Enums>
    <Enum Value="ok" Score="10" />
    <Enum Value="failure" Score="0" />
  </Enums>
</Normalization>

同様に、文字列型の入力に対しても、正規化関数が可能な入力をスコアにマッピングする必要があります。入力が指定された値と一致するのは、その文字列を含んでいる場合です。ワイルドカードを使用できます：

* は0文字以上のプレースホルダーとして。
? は1文字のプレースホルダーとして。

たとえば、次のような入力に対する正常化関数が可能です：デバイスのWindowsライセンスキーを返します：

<Normalization>
  <Strings>
    <String Value="Windows is not activated" Score="0" />
    <String Value="?????-?????-?????-?????-?????" Score="10" />
  </Strings>
</Normalization>

EnumsとStringsの場合、値は大文字と小文字を区別することに注意してください。したがって、定義が期待される値と一致していることを確認してください。たとえば：

Value="Ok"はValue="ok"と同じではありません。

さらに、EnumsとStringsに対して同じスコアを持つ複数の値を提供することはできません。リストの最初の値のみが考慮されるためです。

デバイスまたはユーザービューでリーフスコアを表示する際、Finderは特定のスコアになる入力値、そのスコアのペイロードを表示します。デバイスおよびユーザービューでのスコアの読みやすさを向上させるために、スコアへの入力の意味が不明瞭な場合、各正規化ルールにラベルを付けて、生の入力をスコアのペイロードとして置き換えてください。 RangeやEnum、String要素内でLabel属性を使用してください。たとえば：

<Normalization>
  <Enums>
    <Enum Label="Service working" Value="ok" Score="10" />
    <Enum Label="Service not available" Value="failure" Score="0" />
  </Enums>
</Normalization>

スコアXML検証

スコアを記述するXMLファイルの構造とデータ型は、Nexthinkが提供するXML Schema Definition (XSD)ファイルで定義されています。スキーマファイル（score.xsd）を取得するには：

スコアを管理する権限を持ったユーザーとしてFinderにログインします。
メインウィンドウの左側パネルでScoresを選択します。
Scoresスペースの任意の場所を右クリックしてコンテキストメニューを表示します。
メニューからエクスポート > スコアスキーマをファイルに出力... を選択します。
ファイルを保存する場所をダイアログボックスで選択し、保存を押します。

独自のスコアを記述するには、Libraryで見つけることができる既存のスコアを例として、作成したXMLファイルをこのscore.xsdスキーマファイルに対して検証してください。