Installation and configuration guide (IMC)

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Introduction

This guide aims to provide comprehensive information on how to install and configure the Nexthink ServiceNow IMC integration, as well as basic maintenance guides. This document provides a detailed description of the processes needed for a successful installation.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please contact Nexthink Support for more information.

This document is intended for readers with a detailed understanding of both Nexthink technology and ServiceNow technology, as well as some understanding of concepts such as REST messages, business rules, scripting and some basic security terms.

Revision history

Date	History
2022-09-05	New version: v2.4 · Roles and ACLs section updated · Service Portal Widget information steps updated · New property to activate discovery process optimization for large CMDB
2022-03-08	New version: v2.3 · Device Properties list updated · Remote Action custom fields retrieved after successful remediation execution · Oauth Entity scopes updated · “Navigating in Nexthink Incident Management Connector” section updated with the new Remote Action workflow
2021-11-23	New version: v2.2.0 · Multi portal support · Non-parametric Remote Actions executed without displaying the modal window with parameters · Global ACLs list updated. Service Portal viewer added
2021-03-02	Added: · Fix scripts to upgrade to version 2.0.0 · Roles to execute the scheduled job properly · Self-Service Portal Widget
2020-12-11	New version: v2.0.0 · IMC can launch the new parametric remote actions. · The number of custom tables has been reduced. · Improved architecture has been improved.
2020-11-11	Rules for UI section, UI macros and UI formatters deleted from Global ACLs in Roles and ACLs
2020-08-21	Added new information regarding OAuthV2 configuration
2020-08-17	Updated Global ACLs for OAuthV2 authentication in Roles and ACLs
2020-05-26	· Section 9.2 "Nexthink Incident Management Connector” considerations updated for v1.3.0 · Section 7.2 Navigating in the Agent Workspace updated. · Section 6.11 Enable creation of Scores snapshots updated · Added note in Revision history section
2020-05-06	Version added to the ServiceNow store, v1.3.0 · Integration with Agent Workspace: New Nexthink panel, which is feature parity with the Incident Form View · New role to disable “Open in Finder”
2020-02-20	Updated Global ACLs for Agent Workspace in Roles and ACLs
2020-02-17	Fixed typos and formatting Added section 6.12 “Snapshots format”
2020-01-17	Section “Upgrade Considerations” visited in order to resolve conflicts
2019-12-30	New ServiceNow store version 1.2.1 · Added Mac devices support · Added snapshots creation in text format · Added Cloud deployments configuration
2019-10-10	New ServiceNow store v1.1.2 · Added snapshot creation support in Work Notes

Refer to the Nexthink ServiceNow CMDB Connectors documentation to see the ServiceNow Incident Management connector versions supported by Nexthink.

Overview

Nexthink Incident Management Connector for ServiceNow offers Nexthink customers the ability to integrate end-user IT data into the ServiceNow platform to increase the visibility of IT support teams during Incident Management operations.

With this application, ServiceNow users will be able to:

• Get real-time data about endpoint health using customized Nexthink Scores when opening or checking incidents.

• Save snapshots of Nexthink Scores in the Work Notes for future reference.

• Leverage all the power of Nexthink ACT to fix endpoint problems remotely.

Nexthink Scores can be loaded into the ServiceNow application in the form of an XML file. This XML file can be generated by using the Scores Export option available in Finder. Apart from the Scores, the XML to be loaded into the ServiceNow application may have defined remediation actions associated with some features.

For the Nexthink Scores data retrieval to be possible, the application provides a discovery tool that can be executed on-demand or periodically. This discovery tool checks which devices belong to which Engines inside the configured Nexthink environment and keeps that information stored in a database for future queries using Nexthink Web API 2.0.

Nexthink requirements

Nexthink Incident Management Connector integration requires a running implementation of the Nexthink product.

The following are the pre-requisites:

• An appliance with Nexthink version 6.12.2 or later

• Integrate license to use the Web API

• To use Remediations:

  • Act license

  • Nexthink version 6.29 or higher (for parametric remote actions)

  • Finder access to export Nexthink Scores XML definitions that will be imported into the ServiceNow application.

In addition, if OAuth V2 is required for Engines and/or Portal authentication, ensure the OAuth V2 configuration requirements explained in sections Register Portals and Register Engines are met.

Apart from this, please, note that the Nexthink scores will only be displayed in the default view of the incident table form.

Main ServiceNow Components

The main components of this integration in ServiceNow are described in the next sections.

Custom Table Inventory

The application creates 5 custom tables. A detailed description of each table is explained below.

All of them should be allocated to the entitlements of the instance subscription. You can have more information about custom table allocations in the ServiceNow Product Documentation.

Score Definitions

The table x_nexsa_imc_score_definition contains the different Score groups that will be visualized when checking an incident, including a special score to render the Device Properties. The only fields which can be manually modified by users are Name, Caption, Active, and Display in Service Portal. The rest are internally modified by the application when attaching the XML Scores configuration file associated with it.

By default, the application comes with no Score Definitions defined. After running the Setup Script, the Score Definition for the Device Properties will be automatically created (see Execute setups). The platform of a Score Definition can be windows, mac_os, or both. This is detected automatically when loading the score.

Score Definitions table

Device Properties

Along with the Scores, a group of standard device fields can be configured to be displayed when checking incidents. The table x_nexsa_imc_score_header allows users to define which Nexthink device table fields will be imported into the Incident form.

For each device property to be specified, this table defines the corresponding field in the Nexthink device table (including custom fields), the caption to display on the Incident form, and the order in the list. Table columns are shown in the next impression.

Device Properties table

By default, IMC comes with a set of 13 device properties (see above screenshot Device Properties table). This table is populated by using the application Setup Script, as will be explained in the following sections. Some properties are specific to Windows devices. For a full reference, check the Nexthink NXQL data model for the device table.

Device Tables

Within the table x_nexsa_imc_device_table, the CMDB tables that contain the devices that will be taken into consideration for the retrieval of the data are recorded.

The property x_nexsa_imc.allow_extending_device_tables controls which devices will launch the data retrieval process in the Incident form: either only those stored directly in the tables included in this module (property set to false) or both the aforementioned devices, as well as those stored in tables inheriting from/extending the tables included (property set to true).

For instance, if the Computer table (cmdb_ci_computer) is included in this module, and the property is set to false, only devices in the Computer table will trigger the process in the Incident form. However, if the property is set to true, devices belonging to the table Personal Computer (cmdb_ci_pc_hardware), which inherits from Computer, or devices belonging to other extending tables will also trigger the data retrieval process.

The columns of the table are shown in the following screenshot (Device Tables table). This table contains only two fields: a reference to the dictionary of tables table (sys_db_object) and a string field that stores the internal name of the table.

Device Tables table

By default, the application comes with the Computer (cmdb_ci_computer) table defined and the property set to true.

Score Query

The table x_nexsa_imc_score_query is used as a cache for the necessary NXQL query to retrieve the Scores information to be displayed on the Incident form. It will contain just two records (one for a Windows & Mac properties query, another for only a Windows properties query).

This section is not modifiable by users (see Figure Score Query table below). Every time a Score Definition or Device Property is modified, this record will be automatically updated by the application.

Score Query table

By default, this table will contain an empty query since no device properties or Scores come pre-loaded.

Endpoints

The table x_nexsa_imc_endpoint contains all the configurations to connect to both Nexthink Engines and Portals. To facilitate the configuration, the Application provides 2 modules (views) for this table:

Portals

This view of the table x_nexsa_imc_endpoint allows users to configure which Portals will provide the Remediation API endpoints for the Incident form. The different fields to be filled in are shown in the following screenshot Fields for the Portal table.

Fields for the Portal table

A Portal is used to launch remote actions and to connect to Nexthink Finder. Please, note that the Authentication fields change depending on the Authentication type selected, which can be Basic or OAuth 2.0.

Portal view for OAuth 2.0

The Remediation Port field can be left empty when an out-of-the-box configuration is in place. By default, the Remote Actions API is listening on port 443, so this is the port the connector uses to send remediation requests to the portal. If the port has been customized on the Portal side and the Remote Action API is listening to a different port, it must be specified in the form.

Another consideration is that the MID Server field is not mandatory when defining a new portal with “Basic” authentication type. Only those portals located inside an intranet or those that are not accessible from the Internet would need it.

If necessary, please follow your proxy instructions or ServiceNow instructions on how to set up a MID Server.

ServiceNow MID Server installation instructions

Note: Users from the previous version of the Connector likely remember the Finder Connection table. To simplify the configuration, this table does not exist anymore. To configure the Finder Connection to a Nexthink Portal, please configure the port in the Finder tab.

Finder Port

Please, note that since version 2.2.0, it is possible to create more than one portal, unlike in previous versions where only a portal is allowed to be created and is set as the default portal.

This is no longer necessary. In case that more than one portal is created, the remote action requests are executed to the portal that is linked to the engine where the CI is mapped to.

Engines

This view lets users configure which Engines will provide the Scores information for the Incident form. The different fields to be filled in are shown in the screenshot Fields for Engine (Endpoint table) displayed below. It is possible to define as many Engines as necessary.

Fields for Engine (Endpoint table)

With the Portal field, it is possible to relate any Engine to a specific portal. This field is mandatory, therefore, please ensure a portal is available before creating a new engine.

Please note that the Authentication fields will change depending on the Authentication type selected: Basic or OAuth 2.0.

Engine with Oauth 2.0

MID Server observations made in the previous section (Portals) apply to this case as well.

Additionally, for those using Nexthink in a Cloud environment, and WEB API V2.0 service listening on a different port other than 443, it is mandatory to declare the port in the field “port” of the new Engine form. If the default port is not customized, the field should remain empty. In this case, it is not necessary to install a MID Server because the Engine will be reachable over the internet. The figure Engine cloud configuration example shows an example of the configuration for this scenario.

Engine cloud configuration example

New fields

For normal operation of the integration, the addition of 3 new fields to one of the ServiceNow tables is required, as shown in Table 1.

ServiceNow table	Field added
cmdb_ci	x_nexsa_imc_nxt_engine
cmdb_ci	x_nexsa_imc_nxt_platform
cmdb_ci	x_nexsa_imc_nxt_last_seen

ServiceNow table modified and new field added

Please note that this is the default base table, predefined in the integration, where endpoint information is stored. Please remember that all tables used to store devices in ServiceNow must be contained or inherited from those configured in Devices Tables, as mentioned in previous sections.

Business rules

To reduce the possibility of making mistakes during the initial configuration or during normal operation, several business rules have been defined. These business rules monitor that conditions such as the following, among others, are met:

• Only one Device Properties Score Definition is created.

• The Score Query content is reloaded after modifying a Score Definition.

• The number of Device Properties is not greater than the limit (20, by default).

• A Device Property cannot be left blank if it is not a custom field.

• The Score Query content is reloaded after modifying a Device Property.

• Score Query cannot be deleted.

• The number of Score Queries is not greater than two.

• No more than one attachment for every Score Definition can be uploaded_._

• The Score Definition field is updated after modifying a Score Definition.

• Device Tables must inherit from cmdb_ci.

• There is a minimum of one Device Table record.

• Validate the enable remediation property.

• Validate the REST timeout property.

• No Portal deletion if an engine is linked

Setup scripts

The script under this module performs the default configuration, loading the default records in the tables Device Properties and Device Tables. The Score Definition to show the Device Properties is also created with this script.

Client script

The script under this module allows loading the necessary UI Scripts to display Nexthink Data in the incident form. This has a limitation and unfortunately, the application will only display the Nexthink scores in the default view of the incident form.

Roles and ACLs

Nexthink Incident Management Connector integration creates 6 new roles to manage the application:

Role	Description
x_nexsa_imc.manager	This role is intended for general application configuration.
x_nexsa_imc.incident_viewer	This role allows users to access the Incident form and check endpoint Scores
x_nexsa_imc.incident_remediator	In addition to the incident_view role capabilities, this role allows users to execute remote remediation actions through the remediation panel on the Scores view. In case of parametric remote action it will be executed with the default values
x_nexsa_imc.advance_remediator	In addition to the incident_view role capabilities, this role allows users to execute remote remediation actions through the remediation panel on the Scores view. In case of parametric remote action a modal window will be displayed to customize the input parameters.
x_nexsa_imc.disable_open_in_finder	This role will disable the Open in Finder button.
x_nexsa_imc.service_portal_viewer	This role is necessary to be able to see the self-service portal widget.

Please note that only users with the admin role can modify the definition or code of the business rules, scripts and any other ServiceNow artefacts.

Additionally, remember the itil** role** is necessary for any user dealing with CIs on the Incident form.

x_nexsa_imc.manager role does NOT include the x_nexsa_imc.incident_viewer, x_nexsa_imc.advance_remediator or x_nexsa_imc.incident_remediator role_._

ServiceNow administrators will NOT be able to test the application without explicitly being given the required x_nexsa_imc roles.

The roles permissions are summarized in Table 2: Roles description.

Section	admin	x_nexsa_imc.manager	x_nexsa_imc.viewer	x_nexsa_imc.remediator | x_nexsa_imc.advance_remediator	x_nexsa_imc.disable_open_in_finder	x_nexsa_imc.service_portal_viewer
Execute scheduled jobs	X
Manage business rules	X
Manage score definitions	X	X
Manage device properties	X	X
Manage device tables	X	X
Manage score query
Manage portal endpoints	X	X
Manage engine endpoints	X	X
Manage properties	X	X
Execute setup scripts	X
Execute remote actions				X
Execute remote actions in agent workspace				X
View score tabs			X
View score tabs in agent workspace			X
Create scores snapshots			X
Create scores snapshots in agent workspace			X
Hide open in finder button					X
Hide open in finder button in agent workspace					X
See the self-service portal widget						X

Roles description

Note: ACLs control the information displayed on ServiceNow. Please note that it may be necessary to modify some ACL rules based on your ServiceNow configuration to include the required IMC roles. If this is not done, some system tables and their associated records cannot be shown when performing the initial setup or the scores tab may not appear in the incident form.

Note: The user that will run the scheduled job (indicated in the field run as) must have the necessary permissions to read the following tables:

• ecc_agent

• sys_auth_profile

• cmdb_ci

• sys_db_object

• oauth_entity_profile

For more information about this, see the section Configure Scheduled Job.

Note: The self-service portal widget user must have the necessary permissions to read the following tables:

• sys_auth_profile

• oauth_entity_profile

• cmdb_ci

• ecc_agent

• sys_db_object

Apart from this, it is also required to provide access to write and create records in the sys_journal_field table.

For more information about this, see Install Service Portal Widget.

The Global ACLs required to be added for the Incident Management Connector are described in Table 3: List of ACLs to be enabled.

Type	Operation	Target name	Field	Role	Condition
Record	Read	ecc_agent	None	x_nexsa_imc.manager x_nexsa_imc. incident_remediator x_nexsa_imc.advance_remediator x_nexsa_imc. incident_viewer x_nexsa_imc.service_portal_viewer
Record	Read	ecc_agent	*	x_nexsa_imc.manager x_nexsa_imc. incident_remediator x_nexsa_imc.advance_remediator x_nexsa_imc. incident_viewer x_nexsa_imc.service_portal_viewer
Record	Read	sys_auth_profile	None	x_nexsa_imc.manager x_nexsa_imc.incident_remediator x_nexsa_imc.advance_remediator x_nexsa_imc. incident_viewer x_nexsa_imc. x_nexsa_imc.service_portal_viewer
Record	Read	cmdb_rel_person	None	x_nexsa_imc.manager x_nexsa_imc.incident_viewer
Record	Read	sys_scope	None	x_nexsa_imc.manager
Record	Read	sys_scope	*	x_nexsa_imc.manager
Record	Read	sys_app	None	x_nexsa_imc.manager	Name = Nexthink Incident Management Connector
Record	Read	sys_store_app	None	x_nexsa_imc.manager	Name = Nexthink Incident Management Connector
Record	Read	oauth_entity_pr ofile	None	x_nexsa_imc.manager x_nexsa_imc.incident_viewer x_nexsa_imc.service_portal_viewer
Record	Read	oauth_entity_pr ofile	*	x_nexsa_imc.manager x_nexsa_imc.incident_viewer x_nexsa_imc.service_portal_viewer
Record	Read	cmdb_ci	None	x_nexsa_imc. service_portal_viewer
Record	Read	sys_db_object	None	x_nexsa_imc. service_portal_viewer
Record	Read	sys_db_object	*	x_nexsa_imc. service_portal_viewer
Record	Create	sys_journal_field	None	x_nexsa_imc. service_portal_viewer
Record	Write	sys_journal_field	None	x_nexsa_imc. service_portal_viewer

List of ACLs to be enabled

Apart from this, for further details, included in the application, the below ACLs are added to the sys_security_acl table:

Type	Operation	Target name	Field	Role
client_callable_script_include	Execute	AWPanelAJAXUtilites	N/A	x_nexsa_imc.incident_viewer
Record	Write	cmdb_ci	x_nexsa_imc_nxt_engine	x_nexsa_imc.manager
Record	Write	cmdb_ci	x_nexsa_imc_nxt_platform	x_nexsa_imc.manager
ui_page	Read	finder_error	N/A	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator
client_callable_script_include	Execute	IncidentScoresRefresher	N/A	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator
client_callable_script_include	Execute	NexthinkIncidentWriterGA	N/A	x_nexsa_imc.incident_viewer
client_callable_script_include	Execute	NexthinkUserInteractionsScoreGA	N/A	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator
ui_page	Read	nexthink_contact_support	N/A	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager
Processor	Execute	nexthink_create_incident	N/A	itil
client_callable_script_include	Execute	RelatedDevicesPopulator	N/A	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator
client_callable_script_include	Execute	RemediationExecutorGA	N/A	x_nexsa_imc.incident_remediator
UI Page	Read	remediation_error	N/A	nexsa_imc.incident_remediator
UI Page	Read	remediation_ok	N/A	nexsa_imc.incident_remediator
Record	Read	x_nexsa_imc_device_table	N/A	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager
Record	Create Write Delete	x_nexsa_imc_device_table	N/A	x_nexsa_imc.manager
Record	Read	x_nexsa_imc_device_table	internal_name	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager itil
Record	Read	x_nexsa_imc_endpoint	N/A	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager x_nexsa_imc.service_portal_viewer
Record	Create Write Delete	x_nexsa_imc_endpoint	N/A	x_nexsa_imc.manager
Record	Read	x_nexsa_imc_endpoint	*	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager x_nexsa_imc.service_portal_viewer
Record	Create Write Delete	x_nexsa_imc_endpoint	*	x_nexsa_imc.manager
Record	Write	x_nexsa_imc_endpoint	count_views_serviceportal_widget	x_nexsa_imc.service_portal_viewer
Record	Write	x_nexsa_imc_endpoint	data_loads_agent_workspace_counter	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager
Record	Write	x_nexsa_imc_endpoint	data_loads_incident_do_counter	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager
Record	Write	x_nexsa_imc_endpoint	user_interactions_agent_workspace_counter	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager
Record	Write	x_nexsa_imc_endpoint	user_interactions_incident_do_counter	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager
UI Page	Read	x_nexsa_imc_finder_error	N/A	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator
UI Page	Read	x_nexsa_imc_NexthinkAWPanel	N/A	x_nexsa_imc.incident_viewer
UI Page	Read	x_nexsa_imc_nexthink_contact_support	N/A	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager
UI Page	Read	x_nexsa_imc_NXTRemediationParams	N/A	x_nexsa_imc.incident_remediator
UI Page	Read	x_nexsa_imc_remediation_error	N/A	x_nexsa_imc.incident_remediator
UI Page	Read	x_nexsa_imc_remediation_ok	N/A	x_nexsa_imc.incident_remediator
Record	Read	x_nexsa_imc_score_definition	N/A	x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager Itil
Record	Write Create Delete	x_nexsa_imc_score_definition	N/A	x_nexsa_imc.manager
Record	list_edit	x_nexsa_imc_score_definition	is_device_properties	N/A
Record	add_to_list	x_nexsa_imc_score_definition	template	admin
Record	list_edit	x_nexsa_imc_score_definition	template	admin
Record	Write Create Delete	x_nexsa_imc_score_header	N/A	x_nexsa_imc.manager
Record	Read	x_nexsa_imc_score_header	N/A	x_nexsa_imc.manager x_nexsa_imc.incident_viewer
Record	Read	x_nexsa_imc_score_query	N/A	x_nexsa_imc.manager
Record	Write Create Delete	x_nexsa_imc_score_query	N/A	x_nexsa_imc.manager x_nexsa_imc.incident_viewer x_nexsa_imc.service_portal_viewer

List of ACLs included in the application

Properties

The set of system properties created by the integration are shown in Table 4: System properties created by the integration.

Name	Type	Default value	Description
x_nexsa_imc.max_device_properties_fields	Integer	20	Sets the maximum number of device properties field to be configured
x_nexsa_imc.glide.script.block.client.globals	true | false	false	Set the use of DOM to access elements in the Nexthink section of the Incident form. Please do not change the value of this property to true (it MUST be false).
x_nexsa_imc.rest_timeout	Integer	60	Timeout in seconds for HTTP responses when using REST messages with Nexthink Web API 2.0
x_nexsa_imc.enable_remediation	true | false	false	Enables use of remediation actions (only for Windows devices)
x_nexsa_imc.allow_extending_device_tables	true | false	true	Allows tables extending those included in the "Device Tables" module to trigger the scores retrieval process
x_nexsa_imc.snow_mapping_field	string	name	Field in ServiceNow CI table where the corresponding Nexthink field is mapped
x_nexsa_imc.nxt_mapping_field	string	name	Field in Nexthink device table to be mapped to the corresponding ServiceNow field
x_nexsa_imc.nxt_mapping_field_type	string	string	Type of Nexthink device table field
x_nexsa_imc.snapshot_on_creation	true | false	false	Adds status score info in the incident work note when it is created
x_nexsa_imc.snapshot_on_demand	true | false	false	Adds a button to store status scores in the incident work note
x_nexsa_imc.trigger_field	string	cmdb_ci	Triggers field on Incident form which fetches Scores
x_nexsa_imc.enable_agent_workspace	true | false	true	Enables Agent Workspace integration
x_nexsa_imc.discovery_large_cmdb	true | false	false	Enables discovery manager optimization for large CMDBs
x_nexsa_imc.enable_support_telemetry	true | false	true	Enables Support Telemetry program
x_nexsa_imc.workflow_time_slices	string	Default timer slices	Specifies the frequency to query the Nexthink database to find out if a remote action has been executed.
x_nexsa_imc.plain_text	x_nexsa_imc.plain_text	N/A	(Not included by default, it has to be manually created) In case is set as true, the snapshots will be created as a plain text comment in the incident worknotes.

System properties created by the integration

Scheduled Job

A Scheduled Job is included with Nexthink Incident Management Connector to run the device-Engine mapping discovery process. It is necessary to set the mapping so that connection information is available for every device when retrieving Scores in the Incident form.

Processor

The processor exposes a custom URL endpoint to open a new ServiceNow Incident. This processor is called from a Nexthink Custom Action, where the CI is passed as a parameter to the processor.

Service Portal Widget

In release 2.0.0, a service portal widget has been included. This widget, called NXT-Self Service Portal Score, allows the employee to observe, through certain metrics, the status of some components of their device. If a leaf score can be improved, help links will be displayed, or remote actions can be triggered that can help improve these metrics, and therefore, the overall digital experience. This widget has an educational function with the objective of generating good employee practices, in order to improve the digital experience of the company. To install the widget in the Service Portal, see Configure Service Portal Widget.

Nexthink Components

The integration also provides a way to open ServiceNow Incidents from a Nexthink Custom Action. Therefore, for this part of the integration to work properly, it is also necessary to install this Custom Action.

Custom Action to create tickets from the Finder

An XML file with the Custom Action is provided by the integration. Please refer to the Configure Custom Action to create Incidents from the Finder section to properly set the Custom Action.

Nexthink Custom Action

Please note that, for a ticket to be properly opened in ServiceNow, the user currently logged-in to ServiceNow (or the one used for the login) must include the ITIL role.

For security reasons, the processor that creates the ticket through the custom action is protected against CSRF attacks by default. A detailed explanation of what must be done is on the next page.

If this feature is required, it is necessary to deactivate the CSRF protect checkbox under System Definition > Processors > nexthink_create_incident file.

Nexthink Create Incident Processor

Initial Configuration

Once the application has been installed, an initial configuration is necessary. Please follow the next steps in ServiceNow, in the given order, to achieve a successful configuration. To carry out this process the user must have the manager or admin roles assigned.

Assign appropriate roles to users

First, a general permission policy for all the users accessing the application must be established. For this, the appropriate application roles must be assigned to each user according to how the application will be utilized (see Roles and ACLs).

If the user assigned with roles is currently online, it is necessary to log off and log in again for the changes to take effect.

Configure Nexthink–ServiceNow Mapping

By default, the integration provides a “name–name” mapping, meaning that the Nexthink device name must match the ServiceNow CI name for the integration to work properly. However, this mapping can be modified according to specific needs. Once the field, both in Nexthink and Service now, has been chosen to provide the unique mapping, modifications can be made in the Properties module.

Please be sure the Nexthink field selected for the mapping is unique per device, otherwise, this could lead to inconsistencies.

For a complete list of available Nexthink fields and types, check the device table on the Nexthink NXQL data model.

Properties for Nexthink–ServiceNow mapping sample (different than the default).

Configure authentication profiles

Before going on to the next step, it is necessary to configure authentication profiles to be used by the application when interacting with Nexthink. Since the introduction of the Incident Management Connector v1.4.0, it is possible to configure the connection towards the Engines and Portal using Basic or OAuth V2 authentication types.

These credentials are intended for:

• Engines Web API 2.0: To extract data from the engines. See Introducing The Web API V2 for more details.

• Portal Remediation API: To execute remote actions. Details in Triggering Remote Actions Via Their API.

Depending on which authentication type we choose to connect, there are two different procedures to follow.

Basic

A new entry must be created in the sys_auth_profile_basic completing the fields as shown below:

ServiceNow field	Value
Name	Name to identify the Authentication type
Username	Identifier of a Nexthink user with access to WEB API v2.
Password	Password of the user.

OAuthV2

A new application registry in table oauth_entity must be created, as well as two Entity profiles in oauth_entity_profile and two entity scopes in oauth_entity_scope. These must be related accordingly. In order to complete this configuration, the steps listed below must be completed.

1. Create the application registry

a. Search "oauth_entity.list" in the Filter navigator.

b. Click on "new."

c. Select "Connect to an OAuth Provider (simplified)."

d. Use the parameters below to fulfill the form:

ServiceNow field	Value
Name	Name to identify the application registry
Client ID	Servicenow uses the client ID in combination with the client secret below to get an access token from the OAuth service provider.
Client Secret	The client secret that will provide the user with access to the appliance when it is used in combination with the Client ID.
Token URL:	The token provider that allows connections to your appliance via OAuth V2. For example: “https://token.provider.example.com/oauth2/token”
Default Grant Type	Client Credentials

1. Create the OAuth Entity Profiles

a. Go to the "OAuth Entity Profiles" tab and create two new rows fulfilling the following fields:

ServiceNow field	Value
Name	Name to identify the OAuth Entity Profile
Grant type	Select Client Credentials

*Please, note that each entity profile will be linked to an OAuth Entity scope to connect to the Nexthink appliance, therefore, using names referencing the Engine and the portal connections is recommended.

b. Go to the “OAuth Entity Scopes” tab and create the following scopes:

i. NXQL service scope:

ServiceNow field	Value
Name	Name to identify the OAuth Entity scope
OAuth scope	service:nxql

ii. Remote Action service scope:

ServiceNow field	Value
Name	Name to identify the OAuth Entity scope
OAuth scope	service:remoteaction

iii. Telemetry service scope:

ServiceNow field	Value
Name	Name to identify the OAuth Entity scope
OAuth scope	service:telemetry

c. Link the scopes to the profiles.

Go to the "OAuth Entity Profiles" tab and click on the name of the profile created to connect to the engine. Add a new row on the “OAuth Entity Profile Scopes” and select the Scope created for the NXQL connection.

Repeat this step with the Portal Entity profile, but link this one to the Remote Action service scope.

Register Portals

Add the Nexthink Portal used for remote remediation action execution. Since v2.2 it is possible to add as many portals as necessary. For this, it will be necessary to:

1. Click on the

Portals module.

Portals module

1. Click on the

New button and fill in the form.

New Portal

The Portal form works the same way as the Engine form. If the authentication profile is updated, the form will display different fields. The next table shows how to fill in this form when using Basic authentication type.

ServiceNow field	Tab	Value
Name
URI
Active		true/false (true by default)
Remediation Port		(leave blank for the default, which is 443) or set it to the custom port for customized instances.
Authentication type	Authentication	2 options: Basic or OAuth 2.0
Auth Profile	Authentication	(authentication profile with proper credentials, see sections above)
MID Server	Authentication	(only if necessary)
Finder Port	Finder	(usually 443)

Endpoint table fields to be populated for creating a portal with Basic Authentication profile.

On the other hand, if the authentication type “OAuth 2.0” is selected the following fields will be displayed.

ServiceNow field	Tab	Value
Name
URI
Active		true/false (true by default)
Remediation Port		(leave blank for the default, which is 443) or set it to the custom port for customized instances.
Authentication type	Authentication	2 options: Basic or OAuth 2.0
OAuth Profile	Authentication	(OAuth entity Profile for the portal, see section above 6.3.2.a)
OAuth Requestor profile	Authentication	(Must be fulfilled with a user with role oauth_admin)
Finder Port		(usually 443)
Finder URI (without protocol)		DNS or IP of the Portal. It will be used to setup the “Open in Finder” button, only if the portal is referenced by the Finder Connection

Endpoint table fields to be populated for creating a portal with OAuth 2.0 Authentication profile.

1. Click on the

Submit button to save that Portal.

1. Repeat this process if further portals are required for your integration.

Register Engines

Add the Nexthink Engines from where the data will be retrieved. For this, it will be necessary to:

1. Click on the Engines module.

Engines module

1. Click on the button and fill in the form.

New Engine

The next table shows how to fill in this form:

ServiceNow field	Tab	Value
Name		(same as in Engine configuration in Portal)
URI (without protocol)
Active		true/false (true by default)
Portal		Link to the Nexthink portal related to this Engine.
Port		(usually 1671 for on-premise environments, 443 for cloud environments)
Authentication type	Authentication	2 options: Basic or OAuth 2.0, as explained below
Status	Engine Properties	Idle
Connection	Engine Properties	Disconnected

Endpoint table fields to be populated for creating an engine.

By default, the form will display the Authentication type “Basic.” Therefore, the two following fields will be displayed as well:

ServiceNow field	Value
Auth Profile	(authentication profile with proper credentials, see previous section)
MID Server	(only if necessary)

Endpoint table fields to be populated for creating an engine with Basic Authentication type.

However, if we modify the Authentication type and we set the value “OAuth 2.0”, the form will be updated. The fields in the table above will disappear and two new fields will be displayed.

ServiceNow field	Value
OAuth Profile	(OAuth entity Profile for the engine, see above section – step 2.a)
OAuth Requestor profile	(Must be fulfilled with a user with role oauth_admin)

Endpoint table fields to be populated for creating an engine with OAuth 2.0 Authentication type.

At this point, is also important to note that in the event that “OAuth 2.0” is set as the authentication type, the field URI (without protocol) must be completed with the URI of the API gateway that is used to send requests to the corresponding engine.

For example, in the following case, to configure engine 1, we must populate the URI field with the string “api.gateway.example.com/nxql/engine-1/”. Given the configuration, the API gateway will route the requests to the correct engine.

API gateway example

1. Click on the

Submit button to save the Engine.

1. Please repeat this process to add as many Engines as necessary. Note that the application is multi-engine, making it possible to retrieve and process data from several Nexthink Engines at the same time.

Configure Scheduled Job

Below are the steps to configure the user who will run the Scheduled Job in charge of the device-Engine mapping.

1. Click on the

Scheduled Jobs module to display the application scheduled job named Discover Engines – Devices.

1. Click on the

Discover Engines – Devices record on the list.

1. If the

Run as attribute is not shown on the form:

a. Open layout configuration. Right-click on the gray header and browse Form Layout.

b. If not in the Global application, select Edit this section in Global.

Edit section in Global

c. Select the Run as field to be shown on the form and click the add button.

Select form layout field

d. Save the selection.

Save form layout configuration

e. Back in the Scheduled Job form, pick the user who will be running it. Note that this user must perform the following operations:

• Read the tables: sys_db_object, sys_auth_profile and ecc_agent apart from the tables of the connector.

• Write the fields x_nexsa_imc_nxt_engine and x_nexsa_imc_nxt_platform of the table cmdb_ci apart from the tables of the connector.

• Decrypt passwords to take the password from the sys_auth_profile table and communicate with the API.

The recommendation, if this user cannot be an admin user, is to utilize a user with the roles itil, web_service_admin and x_nexsa_imc_manager.

Pick Run as user.

User selection.

f. Save changes by clicking on Update.

Scheduled Job update.

Execute setup script

The next step would be to execute the Setup Script to load the default configuration to be run by the application.

1. Click on the

Setup Scripts module to display the Scheduled Script Execution named Default Configuration Setup.

Setup Scripts module.

1. Click on the

Default Configuration Setup record.

Default Configuration Setup.

1. Click on the

Execute Now button to load the initial configuration.

The execution of this script will load the default Device Properties to be considered when endpoints scores are displayed (see Device Properties), set a default table for the devices to be stored (see Device Tables) and create the Score Definition for the Device Properties.

Enable/disable remediation

To enable/disable the remediation feature on the application, the user must appropriately toggle the value of the x_nexsa_imc.enable_remediation property (in the Properties module).

Define Scores configuration

In order to configure the Scores to be displayed on the Incident form, it is first necessary to properly load them into the application. Here is a detailed description of the steps involved:

1. Open Finder and export the Scores that must be loaded into the ServiceNow application to an XML file.

Finder Scores

Finder Scores: Export to file.

Finder Scores: Save XML file.

1. If necessary, configure all the Scores formats that require some special transformation. For this, a

Format attribute must be inserted in the required Input element of the XML Scores configuration, see the example below.

Format="percent">

<Field Name="disks_smart_index" />

</Input>

There are several formats that can be applied to transform retrieved values, such as:

• second

• millisecond

• microsecond

• byte

• mhz

• permill

• percent

• bps

To select the appropriate format, please check the NXQL Data Model of the field corresponding to the one shown in the attribute Name if the input is of type Field, or in the attribute Output if the score is of type Computation.

1. If necessary, configure all the Scores that have a remediation panel available.

For this, a Document element must be inserted inside every Score mentioned. Every Document element must be composed of Header and Sections elements to properly format the panel. The most important element to specify inside the panel is RemoteAction which contains the IDof, a remote action to be invoked through the Portal API. Please note that a new attribute ‘Name’ has been added to the RemoteAction element. See the example below:

<Document>

<Header>S.M.A.R.T is a monitoring system included in computer hard disk drives (HDDs) and solid-state drives (SSDs) that detects and reports on various indicators of drive reliability.</Header>

<Sections>

<Section>

<Title>Step 1: It can be an overheating problem</Title>

<Description>It is necessary to increase fan speed.</Description>

<RemoteAction UID="364bd31c-39a3-4ee3-b4a6-c9e83d731707" Name="Increase fan speed" />

</Section>

</Sections>

</Document>

1. Back in the ServiceNow instance where the application is installed, click on the

Score Definitions module.

Score Definition: Module.

1. Click on

New to insert a new score definition record.

Score Definition: New Score Definition.

1. Fill in the

Name, the Caption, and the Order fields. Make sure Active is checked and click on Submit.

Score Definition: Submission.

1. Back in the

Score Definitions list, click on the score definition just created. Note that if you are not in the application scope then the score tab will be empty and it will not work.

Score Definition: Select the new score.

1. Attach the XML file with the score definition. The following images provide a detailed view of the next steps to take.

Score Definition: Attachment.

Score Definition: Attachment file selection.

Score Definition: Attachment file loading.

Score Definition: Attachment close.

Score Definition: Attachment update.

1. The fields of the Score Definition are automatically populated (the content will vary depending on the score uploaded).

Score Definition: Attachment update.

Enable creation of Scores snapshots

By default, the Incident Manager Connector dynamically loads the Nexthink Scores in tabs every time the incident ticket is opened.

It is also possible to store the Nexthink Scores in the Work Notes thanks to the “Take snapshot” button.

The snapshots are saved in the Work Notes tab with the format represented in Figure Scores snapshot saved in the Work Notes.

Scores snapshot saved in the Work Notes.

In order to save the snapshots, it is necessary to have previously loaded the Score tabs in the incident.

The snapshots can be enabled by setting one or both of the following properties to true, available in the Properties section in the Incident Management Connector.

1. “Set true to store a snapshot when incident is created”: When this property is enabled, a snapshot is automatically stored in the Work Notes when a new ticket is submitted manually. Since the snapshot is stored using the work_note field, if any comment is added to this field before creating the ticket, it will be overwritten with the snapshot content. Thus, it is required to create the ticket first and then add the comment in another work note once the incident is already created. Apart from that, this functionality is only available for the Incident view.

2. “Set true to allow snapshot button (snapshot on demand)”: This allows for the creation of a snapshot of the scores after the Incident is submitted to be stored in the Work Notes, at any time during the incident life. This is done by pressing the “Snapshot” button in the Incident view or pressing the “Take snapshot” in the Agent Workspace Nexthink Panel.

Properties to enable score snapshots.

These properties are disabled by default when the Incident Management Connector is installed.

When the ”snapshot on demand” property is enabled, the snapshot button will be displayed for a submitted incident. In other words, the button will not be displayed until the Incident form is saved into a record.

After the “submit” button is clicked, the snapshot button will be displayed on the top right corner of the Incident form or on the top right corner of the Nexthink Panel in the Agent Workspace Incident form.

a) Incident form

Incident form.

b) Agent workspace

Agent Workspace.

Snapshots formats

Snapshots will be inserted in the incident’s Work Notes as HTML or Text depending on the property “Allow support for embedding HTML code by using the** [code] _tag_” (At _System Properties -> UI Properties),**_ as it restricts the insertion of HTML in the Journal fields, the snapshot will look like below Figure Snapshot inserted as Text in the event of the UI Property being disabled.

Snapshot inserted as Text.

In the event this property is changed to false, snapshots previously recorded as HTML will be rendered as HTML text, impacting their legibility. The snapshots taken after the change will be automatically saved in text format.

However, since IMC v2.2, it is possible to create a new IMC property to override the UI property configuration. In case it is necessary, it is possible to create the property x_nexsa_imc.plain_text within the Nexthink Incident Management Connector scope with the below settings:

Field	value	Comment
Suffix	plain_text
Name	x_nexsa_imc.plain_text	Fulfilled automatically
Description	Property to override the "Allow support for embedding HTML code by using the [code] tag"
Type	true | false
Value	[true] | [false]	Set true to store snapshots as plain text comments or false to store using HTML format.

For further clarification, the above property will always prevail over the default UI property. Therefore, in case any inconsistencies are found between the format of the snapshot and the UI property "Allow support for embedding HTML code by using the [code] tag", please, double-check if there is any property called x_nexsa_imc.plain_text in the sys_properties table.

Define device properties

As mentioned earlier, in addition to the scores loaded by users, a series of standard device properties can be retrieved from Nexthink to be displayed on the Incident form. Those properties can be edited by accessing the Device Properties module. Take special care when defining the platform for each device property (see the Nexthink Data Model1 if you have any doubt).

Device Properties module.

To configure the records of this table, it is necessary to specify the following fields:

ServiceNow field	Value
Field	Nexthink device table field (including custom fields) to retrieve for the Incident form
Caption	Text to label the field when displayed on the Incident form
Order	Order in which the field will be displayed on the Incident form
Platform	Options: Windows – Windows & Mac

Fields to be populated to create a new Device Property

Define device tables

Users can also configure the tables in which devices are expected to be stored or the tables from which a custom device table must inherit (see Device Tables). Only devices stored in these tables (or extending from them, depending on the value of the x_nexsa_imc.allow_extending_device_tables property) will launch the scores retrieval process in the Incident form.

Device Tables module.

To configure the records of this table, it is necessary to specify the next field only:

ServiceNow field	Value
Table	ServiceNow table directly containing devices or from which other extending tables will also be considered (according to property value).

Fields to be populated to create a new Device Property.

It is possible that the tables inserted in this Device Tables module (or tables inheriting from those included here) will need some cross-scope access privileges to be granted. In order to achieve this:

1. Navigate to Application Cross-Scope Access, under the System Applications menu.

2. Create 4 new cross-scope privileges for each table (Read, Write, Create and Delete).

ServiceNow field	Value
Source Scope	Nexthink Incident Management Connector
Target Scope	Global
Target Name
Target Type	Table
Application	Nexthink Incident Management Connector
Operation	Read / Write / Create / Delete
Status	Allowed

Cross-scope privileges configuration.

Define Engine-Device discovery configuration

It is extremely important at this point in the configuration to be certain that every endpoint has an Engine associated with it so that when it is loaded from an incident form, Nexthink Scores can be queried and retrieved. This can be achieved by executing the utility Discover Engines - Devices included in the Scheduled Jobs module.

Scheduled Jobs module.

Discovery Engines - Devices.

Basically, this artifact can be executed in two ways:

• On-demand: Click on Execute Now. The utility will be executed once.

Discovery Engines – Devices on demand.

• Scheduled: The user can set up a particular schedule for the utility to be executed (daily, weekly, etc.).

Discovery Engines – Devices scheduled.

In this case, please remember to have the Active checkbox selected.

Please note that if an endpoint is moved from one Engine to another, the discovery process must be run again to update the Engine associated with it. The Scheduled mode comes in handy when users do not want to manually execute the process, but allows the system to automatically run the process once a day, a week, etc.

To check the Engine associated with every endpoint, users only have to access the devices table (for instance, cmdb_ci_computer) and check the NXT Engine field.

Engine associated with devices.

In addition, it is important to remark, that in version IMC 2.3 or lower, this scheduled job expects every configuration Item to be registered at most only in one of the tables configured in the “device tables” configuration. This job has a mechanism to manage duplicates within the same tables, but if the CI is duplicated in different tables the script will only perform the mapping for one of them.

On the other hand, starting from version IMC 2.4, there is a new system property added to the configuration UI page to allow enabling a new Discovery method.

I.E:

x_nexsa_imc.discovery_large_cmdb system property

This property is configured as “false” by default, but in case it is enabled, a new version of the discovery manager optimized for large CMDBs will be executed when the scheduled job Discover Engines - Devices is executed.

Please, note that it is only recommended to enable it on instances where performance issues are experienced during the discovery scheduled job is running. In any other case we strongly recommend to keep the property set as false

Besides, this new process allows mapping all duplicated devices with their respective Nexthink engines even if they are stored in different tables.

Shortcut for CI assignment

Sometimes it is critical to know which device belongs to the caller that opened the incident. To simplify this task, the connector provides two ways to auto-populate the Configuration Item field based on the Caller field. To achieve this, two new buttons can be configured to be displayed beside the Caller field in the Incident form.

New CI assignment buttons.

The first button shows all the configuration items assigned to the caller, according to the Assigned To field of the configuration item itself.

Panel to show devices assigned to the caller.

The second button shows all the configuration items related to the caller, according to the information stored in the cmdb_rel_person table.

Panel to show devices related to the caller.

In both panels, you can simply right-click on the desired CI, and click on the ‘Assign as CI’ action.

Assign as CI action.

To activate these buttons, ensure the global scope is selected in the application picker in the header, right-click over the Caller field in the Incident form and navigate to ‘Configure Dictionary’.

Configure Dictionary option.

In the Attributes section, concatenate the desired option to the ref_contributions attribute. Please note this must be done in the Global scope.

Attribute	Value
ref_contributions	x_nexsa_imc_user_show_assigned_devices
ref_contributions	x_nexsa_imc_user_show_related_devices

Note that the manager can decide to implement none, one, or both of them.

If the Attributes section contains any previous configuration with other attributes apart from ref_contributions, please, keep in mind that the values assigned within every attribute must be separated using semicolons (highlighted in blue below) and every attribute is split from each other using commas (highlighted in red below).

Attributes section.

Configure triggering field in the Incident form

By default, the Incident Management Connector looks for the device properties and scores when the user enters a value in the cmdb_ci field in the Incident form. The picture Default triggering field shows the default field in the Incident form2.

Default triggering field.

You can change the triggering field on the properties page as shown in the below screenshot Default triggering field define in the Properties section.Just be sure that the new field is a reference to cmdb_ci or one of its descendants.

Default triggering field defined in the Properties section.

For example, we can create a new field named “x_nexsa_imc_computer” in the Incident form. The property must change accordingly, as shown in the below sample.

Modified triggering field.

In the incident form, the field that would refresh the score would be the one you selected. For example:

Using a new triggering field.

2 SN Utils is a Chrome add-on that allows watching in the technical name of a field on the form. Although it is not necessary, we have used it in these examples to provide a better understanding.

Configure Custom Action to create Incidents from the Finder

Creation of Incidents is possible from the Finder, by adding a new Custom Action, which can be found in the Product download page of the Incident Management Connector.

To add the new Custom Action, go to the Custom actions menu in Finder, double click on the “Create ServiceNow Incident” one, and modify the URL to point to the desired ServiceNow instance. From now on, when you execute this Custom Action on a given device, a new browser window will be opened with a ServiceNow incident. This incident will have the device selected in Nexthink as CI.

Custom actions menu on Nexthink Finder.

Disable Open in Finder Button

Adding the role x_nexsa_imc.disable_open_in_finder will disable the Open in Finder Button which is shown in the Nexthink tabs.

Open in Nexthink Finder in the Incident View.

Incident view without Open in Nexthink Finder.

Support Telemetry program

The Support Telemetry program aims to provide your organization with a better support experience by sharing information with your Nexthink appliance about the actual configuration and use of the application. Support Telemetry collects the following data points: application configuration, application performance, and feature usage (more details in the online documentation).

With the help of this data, the Nexthink Support team will be able to respond to your organization’s requests more efficiently, as the necessary information will already have been provided to them.

This feature is currently available for Oauth 2.0 and basic connections. However, in case the connection type setup in the portal or portals is Oauth 2.0, please, ensure the scope service:telemetry is configured in the OAuth entity profile.

I.E:

Oauth entity profile

Oauth Entity Scope detail

Install Service Portal Widget

The installation of the NXT-Self Service Portal Score widget consists of two main steps: creating the Service Portal Score definition and configuring the Service Portal page to add the widget.

Please remember that the device for which the score will be retrieved must be assigned to the user accessing the Service Portal on ServiceNow. If version 2.3 or lower is installed, please, note that the widget will not be displayed if more than one computer is assigned to the same user. From IMC v2.4 on, the widget will also be displayed for end-users with more than one device assigned.

Assign a device to a user.

Also, remember to give the users that will use the widget the role nexsa_imc.service_portal_viewer. This user will also need permissions to read the tables cmdb_ci, oauth_entity_profile, sys_db_object and sys_auth_profile. If the user does not have them, an error will be displayed and the widget will not be shown. Apart from this, due to the ServiceNow role management, it is important to note that the widget will also be displayed for users with admin role.

To configure the Score Definition, it is required to follow the below steps:

• Make sure that the Service Portal Score definition has been added to the Finder. Please follow the section Define Scores configuration for further reference.

• On your ServiceNow instance, to create the score definition, navigate to the Score Definitions module.

Score Definitions menu.

• Click on New to create a new record.

Button to create a new record.

• Complete the Name and Caption fields with any value. (Service portal Widget would be a good example)

Empty Score Definitions form.

• Check the Display in Service Portal checkbox.

Display in Service Portal checkbox.

• Click on the Submit button.

  

  Score Definition form without attachment.
• Back in the Score Definitions list, click on the score definition just created to reopen the record.

Service Portal Score record.

• Click on the Manage attachments button.

Manage attachments button.

• Browse for the XML file containing the Score Definition and select it. The remaining fields in the form will be completed automatically.

Score Definition after attachment is loaded.

As can be seen on the above screenshot, the self-service score is just available for Windows devices only out-of-the-box. In case it is necessary to leverage the score for macOS devices as well, please, go to the Customizing the Service Portal Widget Score definition section for further reference.

The next step involves configuring the Service Portal page in which the widget will be displayed.

• Navigate to Service Portal Configuration.

Service Portal Configuration menu.

• Click on Designer.

Designer option for Service Portal.

• Search for the page on which the widget should be displayed. If it is the main page displayed when opening the Service Portal, click on Index.

Service portal index settings.

• In the left-side column, on the Widgets tab, look for the NXT-Self Service Portal Score widget.

Widget to be added.

• Drag the widget into the position of your choice on the page. After a few seconds, the widget will be loaded onto the page:

  

  Widget already installed.
• To use the widget, navigate to Service Portal Home.

Service Portal menu.

In versions 2.0.0 to 2.3, the widget will be displayed, featuring the name of the computer assigned to the user accessing the Service Portal (Please, note that the widget will not be displayed if the user has more than one device assigned in cmdb_ci).

Widget initial state.

However, starting from v2.4, the widget will display different information based on the given status:

• If the user has no devices assigned the below message is displayed:

• In case there are no active engines configured in the x_nexsa_imc_endpoint:

• When just one device is assigned to the user, the name of the CI will be displayed. The widget will work following exactly the same logic as in previous versions:

• If more than one device is assigned to the user the widget will display a combo box where the user’s devices are eligible to be selected:

Once the box is clicked, the device list is displayed as below:

Finally, right after clicking on any of the devices, the button to retrieve the data from Nexthink, which is at first disabled, will be enabled and display the message Click here to improve your digital experience.

To retrieve the information for the computer, click on the button mentioned above. After a few seconds, the information for the score will be displayed.

Score retrieved by the widget.

For scores that need some improvement, a button appears offering the user the option to launch a Remote Action by clicking it. Click on the Fix it button to execute it and after a few seconds, a modal window will be displayed informing the user that the remediation was requested correctly.

Remote action sent successfully.

Please bear in mind that although the remediation may have been executed, the results may not be immediately reflected in the score, depending on its computation time and other factors.

Apart from this, it is important to know that starting from IMC 2.4, a journal message is created in table sys_journal_field every time that a Remote Action is executed from the widget. Thus, it is important to activate the “can read“, “can create“ and “can update“ application access for this table as displayed below:

Application access permissions for table sys_journal_field

Apart from this, it is also required to create the ACL rules to allow the users with Service Portal Viewer role to create and write records in the sys_jounal_field table as explained in the “Roles and ACLs“ section.

Customizing the Service Portal Widget Score definition

The default Service portal widget score can be installed in the Nexthink appliance towards the library using the following link: Employee Self Service. Although, the score has been designed for a standard case that might not be applicable to all scenarios.

In case it is required to edit the score XML content, it is important to understand the procedure to create or edit a score. In summary, ther

• Scores creator tool

• Alternatively, Edit the XML file using a text editor

It is always recommended to use the Scores creator tool. Editing the XML code manually using a text editor is only advisable for quick local changes and only for XML fluent people.

Custom score example

IMPORTANT:

Please, bear in mind that it is only allowed to include one leaf score under every composite score. If more than one leaf score is included within a composite score the widget will not be accurate.

In case of doubt, please, feel free to reach the Nexthink support team for further clarification.

The most interesting part for editing the content of the service portal widget will be located in the leaf score side (select it on the top-left corner of the editor), within the document section:

Leaf Score configuration in Score creator panel

Document Section in the Score creator display

Document Section in the XML code

If the Figure Document Section in the Score creator display is taken as an example, the score will have the following behavior:

• If the value of the leaf score is higher than 7 and lower than 10. (Green status)

  • The message set in the description section will be displayed along with the green check:

Leaf score in green status

• If the value of the leaf score is higher than 3 and lower than 7. (Yellow status)

  • Apart from the message set in the description section and the warning icon, the URL set in the HTTP content section will be displayed as a link.

Leaf score in yellow status

• If the value of the leaf score is lower than 3. (Red status)

  • The message set in the description section and the failure icon will be displayed. In addition, the remediation set in the RemoteAction content section will be executed if the Fix it button is pressed

Leaf score in red status

To summarize, the score will always display:

• The description message, the status icon, and the Fix it button if the score result is red.

• The message, the icon, and the link for helping the user to fix the issue by himself if the score result is yellow.

• The message and the status icon if the result is green.

• A green check and no message if the leaf score value is blank.

In other words: It is not possible to display any link if the result is green or red, to request a remote action if the result is yellow or green, to offer more than one remote action if the result is red, or to display more than one link if the result is yellow.

At this point, it is important to clarify that the score does not always have 3 different thresholds. For example, in case there is a score measuring if the anti-malware software is running on a particular device, there can only be 2 possible scenarios:

• Yes - Green status

• No - Red status

Similarly, the thresholds of the score can be modified. It is possible to adjust the values taken as a reference to set the status color of a leaf score. To achieve this, it is necessary to modify the settings under the Normalization section of the leaf score.

Field computation and Normalization sections in the Score Creator

With the above screenshot, we can conclude that:

• Red status: Any value between 0 and 23000000000 incoming from the field system_drive_free_space will be assigned with a value between 0 and 3 based on this scale.

• Yellow status: Any value between 23000000000 and 30000000000 incoming from the field system_drive_free_space will be assigned with a value between 3 and 7 based on this scale.

• Green status: Any value larger than30000000000 incoming from the field system_drive_free_space will be assigned with a value between 7 and 10 based on this scale.

All these scales and score values are customizable to adjust to every situation. Please, ensure the scale makes sense in order to avoid any misbehavior of the widget.

How to activate the score for the macOS platform

By default, the score that can be installed through the Nexthink Library (Link) is only available for Windows devices.

In case is necessary to enable it for macOS devices as well, it is necessary to follow the below procedure.

1. Open the Scores creator tool

2. Load the XML file of the score

3. Click on the first composite score in the left panel

   
4. Check the macOS option

   
5. Click on Save score

   
6. Upload the XML file in both Finder following the last 6 steps of this procedure.

7. Update the attachment of the score definition of the Self-Service score with the new XML file generated following this procedure.

Navigating in Nexthink Incident Management Connector

Navigating in the Incident form

Please, note that, as informed in the Nexthink Requirements section the Nexthink scores will only be displayed in the default view of the incident table from.

Once the user has some scores or properties defined to be visualized when opening or creating an incident for an endpoint, the Create New module can be selected for this purpose.

NOTE: To be able to visualize the scores and remediation panels, a Configuration Item pointing to the device must be selected.

Incident main form view.

Once a Configuration Item is selected, the Scores and device properties will be retrieved and displayed on tabs below the main view form. Please note that the device must have the properly associated Engine (see Define Engine–Device discovery configuration) and the related list loading configuration should be set as “With the form“ for the tabs to work as expected. For further information about this last point, please refer to the Scores tabs caption not applied section in the troubleshooting guide.

The Device Properties tab contains a list with the device properties previously configured (see Device Properties). Additionally, a button to access Finder using NXT protocol is provided just below the icon that represents the device platform (Windows or Mac). For Mac devices, some fields have no meaning. In order to provide a consistent display, we set the value for those fields as “Not applicable for macOS devices.”

Device Properties tab.

The scores tab contains a list with the score–payload associated with each feature of the group. The view, in this case, resembles that of the Finder (structure, colors, etc.). As in the Device Properties tab, a button to access Finder using NXT protocol is provided. Please note that the Scores displayed for an endpoint are those applied when opening the Incident form.

Scores tab without remediation action available.

When clicking on a feature, users with the role x_nexsa_imc.incident_remediator or x_nexsa_imc.advance_remediator will see a remediation panel on the left if some remediation action is available. Remediations for Mac devices are not currently supported by Nexthink, so the panel will not appear for Mac devices.

Scores tab with remediation action available.

If a remediation action must be performed, the user only needs to click on its link on the right panel. At that point, a query to the Portal will be triggered to retrieve the information about the remote action and once the response is received two different scenarios could occur:

• If the user has _x_nexsa_imc.advance_remediator_** role and the input parameters of the remediation are customizable:** A pop-up window will be shown to the user to choose the values of the input parameters.

Parametric remote action popup.

In the event there is an issue retrieving the parameters of the remote action from the portal, the following error will be displayed:

Parametric remote action popup.

When everything is properly configured, the Submit button will launch the remediation. A message with the result of the operation will be shown.

Remediation execution.

• If the user has just _x_nexsa_imc.incident_remediator_** role or the input parameters of the remote action are not customizable:** No modal window will be displayed with the input parameters and the above message with the results of the operation will be shown. The remote action will be launched using the default parameters returned from the portal.

Note: device_uid is needed to launch remediations. This field is retrieved within the Device Properties Score, meaning that this Score Definition must be active to perform the action. If it is not active, the popup will explain that the remediation could not be dispatched.

Remediation not dispatched.

After remediation is successfully dispatched, a workflow is triggered internally to periodically check the status of a launched remote action and a work note is created to confirm the execution of the same. On each iteration, the Nexthink Engine related to the Configuration Item will be queried. If the remediation has finished, the result is retrieved, saved into the Work Notes of the incident and the workflow is finished.

Remote Action execution work notes

On the other hand, if there is no result after a week, the remediation will be considered to have failed, finishing the workflow. This process is explained in the below picture: Flow of remediation.

Flow of a remediation action.

As defined in the “Enable creation of Scores snapshots” section, there are two properties to allow score snapshots to be saved in the Work Notes.

• If the “snapshot after creation” property is set to true, the status of the scores will be stored as a Work Note when an incident is submitted manually.

• If the “snapshot on demand” property is set to true, the status of the scores will be stored as a Work Note when using the snapshot button in the Incident form.

Please note that the snapshot button will only appear on the default view.

Work Notes view with Scores Snapshot stored.

Navigating in the Agent Workspace

If the Agent Workspace integration is enabled in the Connector properties, users with role x_nexsa_imc.incident_viewer will see the Display Nexthink Panel button when viewing an incident in Agent Workspace.

Display Nexthink panel.

NOTE: To be able to visualize the scores and remediation panels, a Configuration Item (an existing device in Nexthink Appliance) must be selected.

Selecting Configuration Item in Agent Workspace.

Once the Configuration Item is selected, when the user presses the button Display Nexthink panel, the Connector will retrieve the Device Properties and the Scores from Nexthink. Meanwhile, a popup will be shown to inform the user.

Nexthink Panel loading.

Once the information has been retrieved, it will be shown on the Nexthink panel. Please note that the device must have the proper Engine associated with it (see Define Engine–Device discovery configuration).

Device Properties in Nexthink panel.

Please, note that the “Display Nexthink Panel” button will always be displayed even though the CI declared in the Configuration Item field does not belong to Nexthink. If this button is pressed for a non Nexthink CI, the following error will be displayed.

Error message

If the user has the role x_nexsa_imc.incident_remediator or x_nexsa_imc.advance_remediator, a remediation panel will be displayed within the score if any remediation action is available for it. Remediations for Mac devices are not currently supported by Nexthink, so the panel will not be displayed for Mac devices.

Remediation panel in Agent Workspace.

If a remediation action must be performed, the user will proceed in the same way that is required for the incident form. (click on its link on the right panel).

At that point, a query to the Portal will be triggered to retrieve the information about the remote action and once the response is received two different scenarios could occur:

• If the user has _x_nexsa_imc.advance_remediator_** role and the input parameters of the remediation are customizable:** A pop-up window will be shown to the user to choose the values of the input parameters.

Parametric remote action popup in Agent Workspace.

If there is any issue retrieving the parameters of the remote action from Portal, the following error will be displayed:

Error Message

When everything is properly configured, the Submit button will launch the remediation. A message with the result of the operation will be shown.

Remediation

• If the user has just _x_nexsa_imc.incident_remediator_** role or the input parameters of the remote action are not customizable:** No modal window will be displayed with the input parameters and the above message with the results of the operation will be shown. The remote action will be launched using the default parameters returned from the portal.

This procedure works in the same way as explained for the incident form. Hence, at this point, a workflow is triggered to confirm if the remote action execution has finished and an execution confirmation work note is created:

Execution confirmation work note

Once the remediation has been successfully executed, the results of the same are displayed in another work note:

Remediation results worknote

Note: device_uid is needed to launch remediations. This field is retrieved within the Device Properties Score, meaning that this Score Definition must be active to perform the action. If it is not active, the popup will explain that the remediation could not be dispatched and an error will be shown.

Error Message

After remediation has been successfully dispatched, a workflow is triggered internally to periodically check the status of a launched remote action. On each iteration, the Nexthink Engine related to the Configuration Item will be queried. If the remediation has finished the result is retrieved, saved in the Work Notes of the incident and the workflow ends. On the other hand, if there is no result after a week, the remediation will be considered to have failed, finishing the workflow. This process is explained in Figure Flow of a remediation action within the Navigating the incident form section.

If the Snapshot on-demand property is enabled, the Take Snapshot button will be available.

Take Snapshot in Agent Workspace.

The snapshot will be displayed in the Agent Workspace view as well.

Snapshot in Agent Workspace.

NOTE: Most of the messages shown to the user within the Agent Workspace are customizable through System UI Messages.

System UI Messages.

To customize it, look for the desired Message and edit its text. It is also possible to translate the message to other languages.

UI Message.

NOTE: To assure the Connector retrieves the right message, please, do not change the Key value or delete it.

The following table shows the UI Message available:

Key	Initial Value
Device information is not available in the device table.	Device information is not available in the device table.
Device table is not allowed.	The device table is not allowed.
Device table is not valid.	The device table is not valid.
Error: Cannot retrieve trigger field. Please review the value of the property x_nexsa_imc.trigger_field.	Cannot retrieve trigger field. Please review the value of the property x_nexsa_imc.trigger_field.
It is impossible to retrieve scores. Please check the log for more details.	It is impossible to retrieve scores. Please check the log for more details.
It is not possible to decode Server Response.	It is not possible to decode Server Response.
It is not possible to place the data due to no target div.	It is not possible to place the data due to no target div.
no_scores_received_with_data	Error: No data retrieved. Please check the log for more details
param [ci_sys_id] required	CI is not in Nexthink DB.
Retrieving Data	Loading the scores, it will take a few seconds.
Snapshot was taken successfully.	Snapshot was taken successfully.
Snapshot was not taken due to an error.	Snapshot was not taken due to an error.
There is no engine defined for this CI.	There is no engine defined for this CI.
There is no information about the device.	There is no information about the device.
There is no platform defined for this CI.	There is no platform defined for this CI.
The user doesn't have enough roles.	The user doesn't have enough roles to display the panel.

Additional Maintenance/Debugging Operations

Modify system property value

When working in ServiceNow, sometimes it is necessary to change a system property. In ServiceNow, a property is simply a key-value pair (for example, see Properties) and there is a large set of them defined in the system.

To modify the value of a property, simply follow the next steps:

1. Input sys_properties_list.do in the search-box menu.

   

   Filter navigator
2. Look up the property to modify by name.

   

   Search property name
3. Double-click on the property value on the list.

   

   Modifying a system property value (I)
4. Modify the property value and click on the confirmation button.

   

   Modifying a system property value (II)

System Log

Sometimes, and especially when an error arises, it may be necessary to check the messages printed on the system log. To access the system log, type system log in the filter navigator and scroll down until the System Log -> All menu module is reached.

System log menu module search.

All system log messages will then be displayed on a list. It is highly recommended to sort the entries by creation date or filter out messages to check the desired messages.

Descending sort of messages by creation date.

Check messages starting by “MID”.

In order to check possible application errors, it is recommended to filter out messages not starting with “Nexthink”.

Upgrade Considerations

General “ServiceNow application upgrade” considerations

ServiceNow application management behaves in the same way as general ServiceNow upgrades, obeying the next rule:

• As soon as an out-of-the-box script or object is modified by the customer, it will be opted-out the next upgrade, being added to the “Skipped Changes to Review” list in the “Upgrade History Record”

For this reason, it is recommended to follow ServiceNow Upgrade Guidelines, reviewing the skipped changes within the Upgrade History Record, and resolving each case as it occurs.

• Upgrade your instance - docs.servicenow.com

• Please, pay special attention to Phase 4 - Upgrade and validate the development instance.

All the items on the “Skipped Changes to Review” pending to be resolved may have their conflicts addressed individually, by following Service Now Upgrade Guidelines and the “Admin” criteria. Nexthink will ensure the complete functionality only if all the conflicts are “Reverted to Base System” or “Resolved” appropriately.

Resolving Conflicts.

“Nexthink Incident Management Connector” considerations

As a general suggestion, it is always recommended to back up the configuration before an upgrade.

Prior to the Mac support release (Incident Management Connector version 1.1.3), an upgrade was automatically applied, without changes to the configuration except for the new features that were created with the default values.

Upgrades from version 1.1.2 or newer

For an upgrade from version 1.1.2 or older to version 1.1.3 new columns are added to score queries and device properties to add Mac devices support. This might require two additional steps that must be done manually as described below:

• Step 1: Review your _device properties. There is_ an additional platform column that can take values Windows or Windows&Mac. By default, after upgrading, all of them are marked as Windows&Mac, as shown in the below snapshot Default configuration after upgrading for Device Properties table, since most of the properties in Nexthink are compatible with both devices. Please check the Nexthink NXQL data model for the device table in order to set the platform correctly for each device property.

• Step 2: Upgrade the NXQL queries. From now on there are two NXQL queries to be launched by Update, one with properties and scores available for Windows&Mac devices and another for properties and scores that are present only in Windows. After upgrading you need to correctly generate both queries by taking one of these approaches:

  • Option 1: Execute the Setup Script Take into consideration that device properties will be set to default.

  • Option 2: Load (or reload) a Score Definition Score queries will be regenerated correctly after that.

The Score Queries list should look like below picture: Default configuration after upgrading for Device Properties table.

• Step 3: Restore the Form Layouts configuration that was modified before the upgrade.

Default configuration after upgrading for Device Properties table.

Score Query Example.

Upgrades to v1.3.0 or newer

If the Nexthink Incident Management Connector application is updated to version v1.3.0 or older, please, note that you might find that the scores are not displayed on the Agent Workspace Incident form by default.

In this case, it is necessary to complete the two tasks listed below:

• Delete and create the scores again on the Nexthink Incident Management Connector > score definition section:

  • Step 1: Click the name of the score that needs to be re-created.

  • Step 2: Download the score file from the score record. Click on the download link in the top left corner.

    

    Download Score File.
• Step 3: Delete the Score.

  • Click on the “Delete” button in the top right corner.

Delete Score.

• Step 4: Create the Score. Please, follow the section Define Scores configuration for further reference.

• Step 5: Repeat this process in case there are more scores

• Confirm permissions are provided on the System Security > Access Control (ACL) section

  • For this task, you can find more detailed information in the section Roles and ACLs.

Upgrades to v2.0.0 or newer

Nexthink Incident Management Connector v.2.0.0 deletes the specific tables for Engines (x_nexsa_imc_engine) and Portals (x_nexsa_imc_portal) which are replaced by the new Endpoint table (x_nexsa_imc_endpoint). The Engines and Portal registered in the connector can be migrated by executing the Fix Script NXT- Restore Portal & Engines (see section).

The Finder Connection table (x_nexsa_imc_finder_connection) has also been deleted in IMC v2.0.0, this configuration is now done through the Portal view.

In addition, in this version, the logic affecting Score Definitions has been modified. That means access to tables UI Section, UI Element, and UI Macro is no longer required, therefore, the section Roles and ACLs on this guide has been updated to remove the required ACL rules from Table 3: List of ACLs to be enabled.

Fix Scripts

To complete the upgrading process to version 2.0.0, two Fix Scripts have been created.

NXT-Delete UI Sections & Update Scores

The Fix Script NXT-Delete UI Sections & Update Scores is included with the upgrade to version 2.0.0 and is used to upgrade the Incident form to be compatible with the new architecture of the application. It also recreates the score definitions created for the previous versions of the connector.

Please bear in mind that in order to execute this Fix script the user needs to have delete permission on the sys_ui_section table.

To execute the script, follow these steps:

• Navigate to Fix Scripts under the Scripts section.

Fix Scripts menu.

• Click on the Fix Script NXT-Delete UI Sections & Update Scores.

Fix Script record.

• Set the Active flag to true (a check should appear on the checkbox) and save the record.

Active the fix script.

• Click on the Run Fix Script button.

Run Fix Script button

• Click on the Proceed button.

Run fix script button.

• After the script finishes executing, click on the Close button.

Execution log of fix script.

NXT- Restore Portal & Engines

The Fix Script NXT- Restore Portal & Engines moves the Portal and Engines records created on previous versions of the connector from the old x_nexsa_imc_portal and x_nexsa_imc_engine tables to the new x_nexsa_imc_endpoint table. It also deletes the legacy records. Please bear in mind that the architecture of version 1.3.1 of the connector allowed for more than one Portal record to be created, while version 2.0.0 only allows for one. Before executing the script make sure that only one Portal exists on the x_nexsa_imc_portal table. If this is not done, the execution will fail.

As the script needs to be created for the Global application to be able to delete tables, it is not included with the application and needs to be added manually by installing the Update Set attached to the application’s page on the Nexthink community (link).

To install the Update Set follow these steps:

• Navigate to Retrieved Update Sets, under System Update Sets.

Retrieved Update Sets menu.

• Click on Import Update Set from XML.

Upload XML file for Update set.

• Click on Choose File and browse for the .xml Update Set. When finished, click on the Upload button.

Upload XML file

• The Update Set will be uploaded, and its status will be Loaded. Enter the record and click on the Preview Update Set button.

Preview Update Set button.

• After the preview process has finished correctly, click on the Commit Update Set button.

Commit Update Set button.

• The status of the Update Set will be changed to Committed. Next, navigate to Fix Scripts under the Scripts section.

Fix Scripts menu.

• Click on the Fix Script NXT-Restore Portal & Engines.

• Set the Active flag to true (a check should appear on the checkbox) and save the record.

Activate the fix script.

• Click on the Run Fix Script button.

Run Fix Script button.

• Click on the Proceed button.

Run script.

• After the script finishes executing, click on the Close button.

Execution log of fix script.

Upgrades to v2.2.0 or newer

All the upgrades and new features included in the Nexthink Incident Management Connector Application will not override any functionality or configuration from the previous versions. As long as the steps included in the previous section Upgrades to v2.0.0 or newer are applied for instances where the application version is 1.3.1 or lower, there are no further actions to be taken.

Support

Nexthink provides support for the application downloaded from the ServiceNow store in accordance with the terms and conditions of the Support and Maintenance Agreement applicable between the customer and Nexthink. Contact Nexthink Support for assistance.