Installation and configuration guide (IMC)

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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:

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.

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.

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.

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

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.

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:

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:

1. Create the OAuth Entity Profiles

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

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

ii. Remote Action service scope: