LogoLogo
LearnDocumentationSupportCommunity
Version 6.30
Version 6.30
  • Welcome
  • Nexthink V6
  • Overview
    • Software components
    • Collector
    • Finder
    • Engine
    • Portal
    • Nexthink Library
    • Digital Experience Score
  • Installation and configuration
    • Planning your installation
      • Overview of the installation process
      • Hardware requirements
      • Connectivity requirements
      • Software requirements
      • Reference architectures
    • Installing Portal and Engine Appliances
      • Installing the Appliance
      • Installing the Appliance on Azure
      • Installing the Appliance on AWS
      • Installing the Appliance on OTC
      • Managing Appliance accounts
      • Setting the names of the Portal
      • Setting the names of the Engines
      • Specifying your internal networks and domains
      • Federating your Appliances
      • STIG compliance in Web Console
      • Connecting the Portal to the Engines
      • Configuring session performance storage
      • Configuring device performance storage
      • Setting up a software license
      • Sending email notifications from the Appliance
      • Allocating resources for the Portal
    • Installing the Collector
      • Installing the Collector on Windows
      • Installing the Collector on macOS
      • Installing the Collector for a Proof of Value
      • Assigning Collectors to Engines
      • Assignment of roaming Collectors
      • Collector MSI parameters reference table
      • Nxtcfg - Collector configuration tool
      • Inspecting the connection status of the Collector
      • Querying the status of the TCP connection of the Collector
      • Reporting the URL of HTTP web requests
      • Auditing logon events
      • Viewing user interactions in virtualized and embedded environments
      • Engage notifications on macOS
      • Configuring Collector level anonymization
    • Collector remote connectivity
      • Redirecting and anonymizing Collector traffic
      • Redirecting the Collector TCP channel
      • Support for DirectAccess
      • Windows Collector proxy support
      • Mac Collector proxy support
    • Installing the Event Connector
      • Installing the Event Connector on Linux
    • Installing the Finder
      • Installing the Finder on Windows
      • Enabling Cross-Engine Finder features
      • Expanding the time frame of investigations in the Finder
      • Enabling Finder access to the Library
      • Finder proxy support
    • Updating from V6.x
      • Updating the Appliance
      • Content centralization when updating the Appliance
      • Updating the Collector
      • Viewing Collector deprecated fields
      • Updating the Finder
    • Security and user account management
      • Importing and replacing certificates
      • Hierarchizing your infrastructure
      • Adding users
      • Enabling SAML authentication of users
      • Just-In-Time provisioning of user accounts
      • Enabling Windows authentication of users
      • Multi-factor authentication for local accounts overview
      • Provisioning user accounts from Active Directory
      • Establishing a privacy policy
      • Disabling local accounts for interactive users
      • Setting the complexity and minimum length of passwords for local accounts
      • Protecting local accounts against brute force attacks
      • Preventing password saving in the Finder
      • Controlling session timeouts in the Portal
      • Security settings in the Appliance
      • Setting the Do Not Disturb periods between campaigns
    • Data retrieval and storage
      • Data retention
      • Increasing the maximum number of metrics
      • Establishing a data retention policy in the Engine
      • Storing Engine data in a secondary disk drive
      • Importing data from Microsoft Active Directory
      • Setting the locale in the Portal
      • Changing the Time Zone of the Portal
      • Time Zones and data collection
      • Changing the data collection time of the Portal
      • Nightly task schedules timetable
      • Changing the thresholds of High CPU warnings
      • Automatic restart of unresponsive Engine
    • Maintenance operations
      • Logging in to the CLI
      • Special operation modes for the Engine and the Portal
      • Changing the default ports in the Appliance
      • Centralized Management of Appliances and Engines
      • Monitoring the performance of the Appliance
      • Resizing partitions in Appliance
      • Configuring the system log
      • Examining the logs in the Portal
      • GDPR - Retrieving or anonymizing personal data
      • Finding out unlicensed devices
      • Removing devices
      • Installing third-party software in the Appliance
      • Installing VMware Tools in the Appliance
      • Operational data sent to Nexthink
      • Sending additional data to Support
    • Disaster recovery
      • Planning for disaster recovery
      • Web Console backup and restore
      • Engine backup and restore
      • Portal backup and restore
      • Rule-based assignment backup and restore
      • License backup and restore
      • PKI backup and restore
    • Branding
      • Branding the Portal
      • Branding of campaigns
  • User manual
    • Getting started
      • Logging in to the Finder
      • Logging in to the Portal
      • Enabling STIG in Webconsole
    • Querying the system
      • Searching the subject of interest
      • Executing an investigation
      • Creating an investigation
      • Editing the options of an investigation
      • Combining logical conditions in investigations
      • Navigating through the results of an investigation
      • Properties of users and devices
    • Visualizing system activity in the Finder
      • Getting a quick overview
      • Graphically observing the activity of users and devices
      • Observing service performance
      • Viewing network connections
      • Viewing web requests
      • Viewing executions
    • Monitoring IT custom metrics
      • Creating a metric
      • Examples of metrics
      • Session performance
      • Device performance
      • Following the evolution of a metric
      • Finding the visuals of a metric
    • Monitoring IT services
      • Analyzing service quality
      • Creating a service
      • Following the evolution of a service
      • Specifying URL paths of web-based services
    • Engaging with the end user
      • Getting feedback from the end users
      • Types of campaigns
      • Creating a campaign
      • Editing a campaign
      • Types of questions
      • Controlling the flow of questions
      • Translating a campaign
      • Triggering a campaign manually
      • Limiting the reception rate of campaigns
      • Scrutinizing the results of a campaign
      • Continuously measuring the satisfaction of employees
    • Rating devices and users with scores
      • Computing scores
      • Creating a score
      • Checking and comparing ratings
      • Computing potential savings
      • Score XML Reference
      • Documenting scores
    • Remotely acting on devices
      • Scenarios for remote actions
      • Creating a remote action
      • Executing remote actions
      • Triggering a remote action manually
      • Writing scripts for remote actions on Windows
      • Writing scripts for remote actions on Mac
      • Example of self-healing scenario
      • Example of self-help scenario
      • Application control and remote actions
    • Organizing objects with categories
      • Classifying objects of the same type
      • Creating categories and keywords
      • Tagging objects manually
      • Tagging objects automatically
      • Importing tags from text files
    • Getting notified by the system
      • Receiving Engage campaigns
      • Receiving email digests
      • Receiving alerts
      • Creating a service-based alert
      • Creating an investigation-based alert
    • Building web-based dashboards
      • Introducing dashboards in the Portal
      • Creating a dashboard
      • Examining metrics in depth
      • Documenting dashboards
      • Assessing license use
      • Computing dashboard data
      • Reusing dashboard content
    • Importing and exporting authored content
      • Methods for reusing authored content
      • Manually sharing Finder content
      • Importing a content pack
      • Conflict resolution
      • Exporting a content pack
  • Library packs
    • Compliance
      • Device Compliance
    • Configuration Manuals
      • Overview (Configuration Manuals)
      • Installing A New Version Of A Library Pack
    • Digital Employee Score (DEX score)
      • DEX Score Installation And Configuration
      • Detailed Library Pack Changelog
    • Device management
      • Reduce logon duration
      • Group Policy Management
      • Hardware Asset Renewal
      • Hardware Asset Renewal Advanced
      • Application Auto-Start Impact
    • Remote Employee Experience
      • Remote Worker Experience
      • Home Networking
      • Change Log And Upgrade Process
      • Remote Worker Vs Office Worker Device Category
      • Remote Worker Insights
      • DEX V2 Upgrade Of Remote Worker
    • Persona Insight
      • Persona Insight - Overview
      • Persona Insight - Library Pack
      • Persona Insight - Score Only Pack
      • Persona Insight - Without Campaign pack
      • Persona Insight - Getting Started and Upgrade Procedure
      • Persona Insight - Configuration Guide
      • Persona Insight - Troubleshooting - Multiple devices on multiple engines
      • Persona Insight - Reference Guide
      • Persona Insight - Example Pack
      • Persona Insight - Device Sizing
        • Persona Insight - Device Sizing Overview
        • Persona Insight - Device Sizing Configuration
      • Persona Insight - Application Sizing
        • Persona Insight - Application Sizing Overview
        • Persona Insight - Application Sizing Configuration
      • Legacy Persona documentation
        • Persona Insight - Library Pack (V.1.0.0.0)
        • Persona Insight - Base Pack
        • Persona Insight - Base Pack Advanced
        • Persona Insight - Customization Guide (V1.0.0.0)
        • Persona Insight - Configuration Guide (V1.0.0.0)
        • Persona Insight - Reference Guide (V1.0.0.0)
    • GSuite
      • GSuite: Health
      • GSuite: Services
      • GSuite: Sentiment
      • GSuite: Advanced Health
    • Support
      • Support: Level 1
    • Shadow IT
      • Shadow IT
    • Malware Protection
      • Malware Protection
    • Office 365 Health
      • Office 365 Health: Overview
      • Office 365 Health: Services
    • Office 365 OneDrive
      • OneDrive Summary
      • OneDrive Operations
      • OneDrive Advanced Health
      • OneDrive Migration
      • OneDrive Sentiment
      • OneDrive Management
      • OneDrive Advanced Operations
    • Office 365 Teams
      • Teams Overall Configuration
      • Teams - Migration
      • Teams - Health
      • Teams - Advanced Health
      • Teams - Adoption
    • Microsoft 365 Apps
      • Microsoft 365 Apps - Operate
    • Employee Self Service
      • Overview
      • Configuration
      • Usage
    • Onboarding Experience Management
      • OEM - Overview
      • OEM - Configuration
    • Office 365 Outlook
      • Outlook Troubleshooting
    • Virtualization
      • Virtualization: Operate
      • Virtualization: AVD - Advanced
      • Virtualization: Citrix Advanced
      • Virtualization: Project
      • Virtualization: Troubleshooting
        • Virtualization: Troubleshooting: Configuration
    • Windows
      • Win10: Configuration
      • Win10: Migration
      • Win10: Feature Update
      • Win10: Quality Update
      • Windows Defender Management
      • Administrators Management
    • Windows 11
      • Windows 11 - Readiness
      • Windows 11 - Migration Pilot
      • Windows 11 - Migration
      • Windows 11 - Operate
    • Webex
      • Webex Operate
    • Zoom
      • Zoom Operate
    • Remote Actions
      • Get Performance Monitor Data
      • Skype For Business
      • Restart Device
      • Upload Logs to S3 using PreSigned URLs
    • Software Asset Optimization
    • Collaboration Optimization
      • Collaboration Optimization - Solution Overview
      • Collaboration Optimization - Configuration
      • Collaboration Optimization - Usage / Troubleshooting
    • Systems Management
      • Manage Configuration Drift
      • MS ConfigMgr - Client Health
        • MS ConfigMgr - Client Health - Summary
        • MS ConfigMgr - Client Health - Configuration Guide
      • Intune
        • Intune - Health
          • Intune - Health - Summary
          • Intune - Health - Configuration Guide
    • Return to the office
      • Return to the office - Planning
      • Return to the office - Readiness
    • Green IT
      • Green IT - Overview
      • Green IT - Configuration Guide
    • Hybrid Working
      • Hybrid Working Experience
      • Hybrid Working Experience - Installation and upgrade procedure
  • Integrations
    • Nexthink ServiceNow Service Graph Connector
      • Overview
        • Roles and Permissions
        • Modules
      • Installation and Configuration Guide
        • Pre-requisites
          • Configure Identification Rules
          • Import and setup the CMDB categories in Finder
        • Setup
          • Configure the connection
          • Configure import properties
          • Configure additional engines
          • Set up scheduled import jobs
      • Data transformation and mapping by default
      • How to customize the behaviour of the Connector
      • FAQ
        • Why ServiceNow Service Graph Connector?
        • What about Nexthink CMDB Connector?
        • Why is the name the primary key for the devices?
      • Troubleshooting
        • IRE identification issues
          • [No Choice found in the sys_choice table for the target table](integrations/nexthink-servicenow-service-graph-connector/troubleshooting/ire-identification-issues/ no-choice-found-in-the-sys_choice-table-for-the-target-table.md)
          • Identification rules not created
          • Discovery_source choice not created
        • Timeout Errors
          • ECCResponseTimeoutException
          • HTTP 0 error
        • MID server issues
          • java.lang.NullPointerException
          • MID Server memory issues
          • Not trusted certificates in Quebec release
        • Configure credentials issues
          • [Not allowing update of property authentication_choice](integrations/nexthink-servicenow-service-graph-connector/troubleshooting/configure-credentials-issues/ not-allowing-update-of-property-authentication_choice.md)
          • Invalid username/password combo (HTTP 401/403)
        • Configure Engines Issues
          • [The client secret supplied for a confidential client is invalid](integrations/nexthink-servicenow-service-graph-connector/troubleshooting/configure-engines-issues/ the-client-secret-supplied-for-a-confidential-client-is-invalid.md)
        • No Cis imported and no errors found in the log
    • Nexthink ServiceNow Incident Management Connector (IMC)
      • Installation and configuration guide (IMC)
      • Troubleshooting Guide (IMC)
      • Domain separation installation (IMC)
    • Nexthink ServiceNow CMDB Connectors
      • Installation and Configuration Guide
      • Troubleshooting Guide
      • Field transformation and normalisation examples
    • Nexthink Event Connector
      • High level overview
      • Installation and Configuration Guide
      • Troubleshooting guide
      • RPM installation
      • Splunk specific documentation
        • Upgrading from Splunk Connector to Event Connector
        • Splunk add-on installation and usage
    • Nexthink Chatbot SDK
      • Introduction and concepts
      • Installation, configuration and update guide
        • Installation and configuration
        • Update to newer version
        • Uninstallation
        • Authentication
        • Topics configuration
        • Remote action configuration
        • Advanced configuration
        • Additional resources and references
      • Dimensioning guide
      • Troubleshooting
      • Technical solution description
      • Downloads and release notes
  • Glossary and references
    • Search and information display
      • Search in Finder
      • Keyboard shortcuts for column display selection
      • Campaign display compatibility
      • Real-time and consolidated service data
      • Service errors and warnings
      • Errors and warnings for devices and executions
      • Types of widgets
      • Widget compute state in charts
      • Errors in the execution of remote actions
      • Top results of Cross-Engine investigations
      • Engine data history
    • Tooltips in the user and device views
      • Alerts tooltips
      • Warnings tooltips
      • Errors tooltips
      • Activity tooltips
      • Services tooltips
    • Database information and organization
      • Maximum supported values
      • Local and shared content
      • Device Identification
      • Local IP address of devices
      • Timestamping of events
      • Boot and logon duration
      • Application startup duration
      • Application not responding events
      • Memory and CPU usage
      • Status of TCP connections
      • Status of UDP connections
      • Network and port scan conditions
      • Binary paths
      • Maximum number of Binaries
      • Package Executable Mapping
      • Metro apps
      • Investigation with packages
      • Portal aggregation and grouping
      • Focus time metric
    • Security
      • Access rights and permissions
      • Active Directory authentication
      • Canonical domain names for Windows authentication
      • System alerts
      • Audit trail
      • Appliance hardening
      • STIG hardening
      • FIPS 140-2 compliance
      • Security bulletins
        • Is Nexthink affected by Okta breach
        • Is Nexthink affected by SolarWinds breach
        • Nexthink and Log4j - Security bulletin
        • CVE-2022-22965 - Security Vulnerability Spring4shell - Spring Framework
        • Version 6.22.2.10: Security Vulnerability Maintenance Release
        • The Collector V6.27.X Release – Security Bulletin
    • References
      • Components of the Collector
      • Server support
      • Compatibility mode
    • Glossary
      • Activity
      • Alert
      • Application
      • Binary
      • Campaign
      • Category
      • Connection
      • Dashboard
      • Destination
      • Device
      • Domain
      • Entity
      • Event
      • Executable
      • Execution
      • Focus time
      • Hierarchy
      • Installation
      • Investigation
      • Keyword
      • Metric
      • Module
      • Object
      • Package
      • Platform
      • Port
      • Printer
      • Score
      • Service
      • Session
      • System boot
      • User
      • User logon
      • Web request
      • Widget
  • API and integrations
    • Integrating with Nexthink
      • Event Connector
      • Getting data through the NXQL API
      • Bidirectional integration with the Finder
      • Count metrics API
      • Software metering API
      • Services API
      • List Engines API
      • GetSID API
      • Triggering campaigns via their API
      • Triggering remote actions via their API
      • Audit trail API
      • Integrating investigation-based alerts
      • Downloads
    • NXQL API
      • Introducing the NXQL API
      • NXQL Tutorial
      • NXQL language definition
      • NXQL Data Model
    • Integrations
      • Excel integration with NXQL
      • Power BI
      • Azure Data Lake Storage Gen2
      • Splunk Event Connector
    • ServiceNow
      • CMDB Connector
      • Incident Management Connector
      • Event Management

© Nexthink

  • Privacy policy
  • Responsible Disclosure Policy
On this page
  • Overview
  • The root element ScoreDef
  • UID
  • Name
  • Object
  • InObjectView
  • Status
  • SyntaxVersion
  • DataModelVersion
  • Platforms
  • ScopeQuery
  • ComputationSchedule
  • Thresholds
  • Composite and leaf scores
  • UID
  • Name
  • Description
  • Visibility
  • Weight
  • Computing a composite score
  • Computing a leaf score
  • Score XML validation

Was this helpful?

  1. User manual
  2. Rating devices and users with scores

Score XML Reference

Overview

Scores are defined in XML documents. This article details the format of XML files that hold the definition of a score.

The root element ScoreDef

As any other XML file, a score definition must begin with the XML header. Use utf-8 encoding:

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

The XML header is followed by the root element. The name of the root element for XML documents that hold a score definition is 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>

Along with the ScoreDef element, find the following attributes:

UID

A universally unique identifier for the score. It is a 128-bit integer number expressed in hexadecimal format with separators and available tools exist to generate them with low collision probability. Example: f54972e7-0f9c-46ce-8931-bbe31b06f7b4.

Name

The name of the score as shown in Finder.

Object

The type of object to which the score applies. It can either be user or device.

InObjectView

Whether the score should appear inside the User or Device view in the Finder or not. Note that the User and Device views can display a maximum of five scores each. Possible values are true or false.

Status

Whether the score should be calculated or not. Possible values are enabled or disabled.

SyntaxVersion

The version of the schema for the XML file. Currently fixed to 1.

DataModelVersion

The version of the Nexthink Data Model on which the score relies for its queries. Currently fixed to 12.

After the attributes, find the following elements inside ScoreDef:

Platforms

The platforms to which the score applies. Enumerate each supported platform within a Platform element. Possible values for the platform are windows, mac_os, or mobile. Example:

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

ScopeQuery

Define the scope of the query to retrieve users or devices by filtering the objects. Write a where clause in NXQL inside the Filtering element. For example, to filter out servers from a score on devices:

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

ComputationSchedule

The moment to compute all the leaf scores that have a computation input. It can be either an hour of the day, for computing the score every day at that hour, or a period, for computing the score more often. It applies only to those leaf scores whose input is a computation and not a field, as field-based scores are updated every minute. The main score is updated whenever a leaf score changes, be it of the computation input or of the field input type. To specify an hour of the day, insert the element At with a value between 0 and 23. To specify a period, insert the element Every with values 15min, 1h, or 6h. Example: 2

Thresholds

Optional: The limit values of the score that determine its status. Define up to three thresholds that the score has to exceed to be in a particular status. The Finder displays the score with a particular color depending on its status: red, yellow, or green. Specify the thresholds from green to red or from red to green (yellow is optional) always with the values in ascending order. Each Threshold element holds the Color attribute, as well as a Keyword element that defines the limit value of the threshold in its From attribute and the name of the corresponding status in the Label attribute. For a score to define no thresholds, declare exactly one threshold with the color none. Example:

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

Once the general elements of the score definition are laid out, add a single composite or leaf score element to the definition. This last element describes how to compute the score from the values stored in the Nexthink database. If you add a LeafScore element to your ScoreDef, the score will depend on one computation or on the value of one field only. On the other hand, if you add a CompositeScore element to the ScoreDef, a combination of several scores is used to compute the main score.

Composite and leaf scores

CompositeScore and LeafScore are the elements in the score definition that are used to compute individual scores.

The following attributes are common to the CompositeScore and LeafScore elements:

UID

A universally unique identifier for the score (similar to that of the ScoreDef element).

Name

The name of the score.

Description

A textual description of the score.

Visibility

Optional: Whether the score should be visible in the Finder, nowhere, or only in quantity metrics in the Portal. Possible values are visible, hidden, and visible only in quantity metrics. By default, a score is visible everywhere.

Weight

Optional: A floating point number with up to two decimal places that acts as a multiplier of the computed score when its immediate composite parent score performs a weighted average operation (see how a composite score is computed below).

In addition to the common attributes, both the CompositeScore and the LeafScore elements optionally include a Document element. The Document element holds the documentation of the score that is displayed in the corresponding score tab of either the device view or the user view, depending on the object to which the score applies. Besides the detailed description of the score, the documentation of a score may also contain:

  • Links to external HTTP resources (e.g. knowledge base, external documentation, etc).

  • Links to remote actions which can be manually triggered, to take appropriate action on devices that display a poor score.

Computing a composite score

A composite score results from the combination of its direct child scores by means of an operation. Each composite scores declares thus an Operation element that specifies how to combine its child scores. After the operation, find the list of child scores that contribute to the composite score:

<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>
    <!-- List of child scores -->
    <LeafScore ...
    <CompositeScore ...
    <LeafScore ...
    ...
    <!-- Optional documentation for the score seen in device or user views -->
    <Document ... 
</CompositeScore>

Find below the list of possible values for the Operation element:

Average

Compute the arithmetic mean of the direct child scores.

Min

Get the minimum direct child score.

Max

Get the maximum direct child score.

Sum

Compute the addition of the direct child scores.

WeightedAverage

Compute the arithmetic mean of the direct child scores after multiplying each child score by the quantity specified in its Weight attribute.

Multiply

Compute the multiplication of the direct child scores.

Computing a leaf score

A leaf score is a result of applying a normalization procedure to an input value coming from the Nexthink database. The input is either the value of a field that belongs to the user or the device objects or the result of a computation on devices or users expressed in the NXQL language.

Thus, a LeafScore is composed of an Input element and a Normalization element:

<LeafScore UID="[<unique identifier>]" Name="[<name of the score>]"
  Description="[<score description>]" Visibility="[visible|hidden]"
  Weight="[float]">
    <Input ...
    <Normalization ...
    <!-- Optional documentation for the score seen in device or user views -->
    <Document ... 
</LeafScore>

In its turn, the Input element encloses either a Field or a Computation element.

For an input of the field type, specify the name of the field to retrieve inside the Name attribute of the Field element. Type in the name of the field as stated in the NXQL data model. For example, to retrieve the WMI status of a device, write:

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

An input of the computation type is slightly more complex to define. First give a name, a description, and a unique identifier to the computation as attributes of the Computation element. Then write an NXQL query to extract information from the Nexthink database inside a child Query element. As attributes of the Query element, set the Output to be the aggregate or field in the query that should be passed as input to the leaf score and the DefaultOutputValue to the value returned when the previously specified output is undefined. The structure of a computation input is thus as follows:

<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>

Note that the embedded NXQL query must select the id of the objects retrieved (users or devices), as well as the field declared as output, if any. If an aggregate is declared as output instead, include the calculation of the aggregate in the query within a compute clause. For example, to compute the ratio of successful HTTP requests of a device during the last week for using it as the input to a leaf score, write the following Query element:

 <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>

Note the use of the keyword NULL as the default output value in the previous query. Whenever it does not make sense to return a value for the score if the underlying field or aggregate is undefined, write NULL as the default output value. In the previous example query, the ratio of HTTP requests is undefined if the device made no HTTP requests. Rather than force an artificial value for the score, it is preferable to return no value.

A leaf score with no value that is part of a composite score is discarded for the computation of the composite score. If a composite score or the main score cannot be computed because of a lack of underlying values, they have no value as a result. The Finder displays a dash sign (-) for scores with an undefined value.

In the case that the input to a leaf score actually gets a proper value, transform it to give it business significance by means of a normalization function. The purpose of scores is indeed to make sense out of the detailed measures in the Nexthink database. Normalize quantities, ratios, enumerations, or even strings to a numerical range, usually the range from 0 to 10, which makes it easier for you to understand the status of a user or device with respect to the measured input.

The Normalization element defines thus how to map the input values to the desired range. Depending on the type of the input, apply a different normalization function:

Type of input
Available normalizations

Numeric type

  • Step function

  • Piecewise linear function

Enumerated type

Direct mapping

String type

Direct mapping (with optional placeholders)

To normalize numerical input values by means of a step function, define a list of Ranges with input values in ascending order (attributed scores do not need to follow any particular order), as in the following example:

<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>

The example defines a step function for what it looks like a ratio input that returns:

  • A score of 0 for an input value between 0% and 60% (not included).

  • A score of 5 for an input value between 60% and 80% (not included).

  • A score of 10 for an input value equal to or greater than 80%.

As mentioned previously, scores do not necessarily grow with the input value. For instance, consider this alternative normalization where the score drops to zero for input values higher than 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>

The resulting step function returns:

  • A score of 5 for an input value between 0% and 60% (not included).

  • A score of 10 for an input value between 60% and 80% (not included).

  • A score of 0 for an input value equal to or greater than 80%.

To normalize numerical input values by means of a piecewise linear function, define a list of Ranges similar to those found in the step function, but this time with an additional To element that delimits a linear interval and specifies the final value of the score within the interval:

<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>

The example defines a piecewise linear function that maps our ratio input to a score that evolves linearly within each interval:

  • For an input value between 0% and 60%, the score ranges from 0 to 2.

  • For an input value between 60% and 90%, the score ranges from 2 to 9.

  • For an input value between 90% and 100%, the score ranges from 9 to 10.

  • For an input value equal to or greater than 100%, the score is 10.

As shown in the figure, linear interpolation is performed within each interval. For instance, an input value of 30% would receive a score of 1.

Note that the Value and Score attributes of a To element must be equal to those of the From element defined in the next range for the piecewise linear function to be continuous. The last range does not define a To element to avoid imposing a limit to the input value (in the case that our hypothetical ratio input could be higher than 100%).

For inputs of an enumerated type, the normalization function must directly map each possible input to a score, as in the following example:

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

Similarly, for inputs of the string type, the normalization function must map the possible inputs to a score. An input matches the value specified when it contains the string. You can use the wildcards:

  • *, as a placeholder for 0 or more characters.

  • ?, as a placeholder for a single character.

For example, this is a possible normalization function for an input that returns the Windows License Key of a device:

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

In the case of Enums and Strings, beware that the values are case-sensitive. Therefore, ensure that your definitions match the expected values as, for instance:

  • Value="Ok" is not the same as Value="ok".

Additionally, providing several values with the same score for Enums and Strings is not allowed because only the first value in the list will be considered.

When displaying a leaf score in the device or user views, the Finder shows the payload of the score; that is, the input value that resulted in a particular score. To improve the readability of the scores in the device and user views, when the input to a score has an obscure meaning, tag each normalization rule with a label that substitutes the raw input as the payload of the score. Use the Label attribute within the Range, Enum, or String elements. For example:

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

Score XML validation

  1. Log in to the Finder as a user with the right to manage scores.

  2. Select Scores in the left-hand side panel of the main window.

  3. Right-click anywhere in the Scores space to bring up a context menu.

  4. Choose Export > Score schema to file... from the menu.

  5. Select the location where to store the file in the dialog and press Save.

To write your own scores, take the existing scores that you can find in the Library as an example and validate the XML files that you create against this score.xsd schema file.


RELATED TASKS

Last updated 8 months ago

Was this helpful?

As a matter of fact, a composite score is itself composed of other composite or leaf scores, . Ultimately, all the nodes at the lowest level of the tree must be leaf scores.

See for the complete reference of the Document element.

The list of child scores is limited by the . Remember however that this limit includes the nested scores and that the maximum nesting of scores is 5 levels.

The structure and datatypes of XML files that describe scores are defined in an file that Nexthink provides. To get the schema file (score.xsd):

forming a tree of up to five levels
how to document scores
XML Schema Definition (XSD)
Computing scores
Creating a score
Documenting scores
maximum number of scores that you can simultaneously enable