Introduction

This guide provides comprehensive information on how to install and configure the Nexthink CMDB Connector integration with ServiceNow, 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 report them to us via Nexthink support portal. This document is intended for readers with a detailed understanding of Nexthink technology and ServiceNow technology and some understanding of concepts such as REST messages, business rules, scripting, and some basic security terms.

These configuration instructions must be executed by a ServiceNow certified professional

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.

Supported versions of ServiceNow

  • Quebec

  • Paris

  • Orlando

Latest release

V1.2.0 (November 2020)

  • Support of ServiceNow Identification and Reconciliation Engine (IRE)

Version: 1.2.0

 Last Revision: 2020-09-17

Revision history

Date

History

2010-10-02

Section Configure Global ACLs updated

2020-10-01

Removed the “Enable Business Rules” section

2020-09-17

Updated documentation for CMDB v1.2.0

2020-09-07

Updated Custom table inventory information

2019-12-18

Added Cloud deployments configuration

2019-10-11

New ServiceNow store version 1.1.0

Added field normalization support

Nexthink CMDB Populator installation and configuration guide

Overview

Nexthink CMDB Populator integration with ServiceNow offers Nexthink customers the ability to integrate end-user IT data from Nexthink Engines into the ServiceNow platform. Configuring the Nexthink CMDB Populator application is possible by selecting the set of information about different Configuration Items (devices, services, etc.) that will be populated into ServiceNow. Additionally, the relationships between these Configuration Items (CI) can be imported to ServiceNow.

The integration provides a default set of ServiceNow CMDB tables and fields to be populated with the corresponding information from Nexthink, thus offering a set of predefined mappings. For each CI type the integration admits three actions: update, insert and delete/deactivate. These actions can be enabled or disabled independently. Likewise, the integration allows leveraging the import of specific fields associated with a given CI type.

In addition to the default mappings, the flexible design of the integration allows the configuration of different CMDB ServiceNow tables and fields to be populated.

Furthermore, starting in version 1.2.0, the application supports Identification and Reconciliation Engine (IRE), which better manages the orchestration of imports, providing a centralized framework to perform identification and reconciliation processes across different data sources. For further details, refer to the Identification and Reconciliation Engine (IRE) section in this guide.

For installation guidelines, go to the Initial Configuration section.

Main ServiceNow components

Nexthink CMDB Populator integration requires a running implementation of a Nexthink product. These are the supported versions:

  • At least one instance of Nexthink Engine V6.7 or later, to import data into ServiceNow via Nexthink Web API V2.0.

  • A Nexthink Finder V6.7 or later, to configure the Web API V2.0 categories.

The following main components are part of the Nexthink CMDB Populator integration.

Custom table inventory

The application creates 18 custom tables:

  • 12 are used to manage the import sets and should not be allocated to any subscription.

  • 6 should be allocated to subscription entitlements to configure the integration.

    • 4 are used to configure the integration.

    • 2 are used for informative purposes.

More information about custom table allocations can be found in the ServiceNow Product Documentation. and in the table below:

Label

Name

Import Set Service

x_nexsa_cmdb_pop_import_set_service

Import Set Software

x_nexsa_cmdb_pop_import_set_software

Import Set User

x_nexsa_cmdb_pop_import_set_user

Import Set

WindowsServer

x_nexsa_cmdb_pop_import_set_windowsserver

Import Set Workstation

x_nexsa_cmdb_pop_import_set_workstation

Import Set User - Service

x_nexsa_cmdb_pop_import_set_user_service

Import Set User -

WindowsServer

x_nexsa_cmdb_pop_import_set_user_windowsserver

Import Set User -

Workstation

x_nexsa_cmdb_pop_import_set_user_workstation

Import Set

WindowsServer - Service

x_nexsa_cmdb_pop_import_set_ windowsserver_service

Import Set

WindowsServer - Software

 

x_nexsa_cmdb_pop_import_set_windowsserver_software

Import Set Workstation -

Service

x_nexsa_cmdb_pop_import_set_ workstation_service

Import Set Workstation -

Software

x_nexsa_cmdb_pop_import_set_workstation_software

Engine

x_nexsa_cmdb_pop_engine

CI Type

x_nexsa_cmdb_pop_ci_category

CI Type Field

x_nexsa_cmdb_pop_ci_category_field

CI Relationship

x_nexsa_cmdb_pop_ci_rel

Stats

x_nexsa_cmdb_pop_stat

References

x_nexsa_cmdb_pop_reference

CI Types

This table defines the different CI types to be imported and how this import process will operate. The columns of the table are shown in the illustration below. As shown, 3 possible actions can be performed for each CI type: Can insert, Can Update, and Can Delete/Can Deactivate. By modifying the value of these columns, the desired action can be activated or deactivated.

Furthermore, the integration allows for modification of the destination ServiceNow table for each CI type, which in turn provides greater flexibility. Be aware that, as a constraint, the user-defined tables to be filled-in must inherit from the standard cmdb_base ServiceNow table (or sys_user for users). This way, the integration can leverage the ServiceNow CMDB capabilities.

By default, the application defines 5 CI types to be imported: services, software, users, workstations and Windows servers.

CI Types table

CI Types Fields

For each previously defined CI type, this table defines the set of fields that are going to be imported during the integration process. The columns of the table are shown in the illustration below.

The CI Types table allows the user to:

  • Configure the fields so they can be imported for each CI Type.

  • Select the destination ServiceNow field.

  • Choose the source Nexthink field.

  • Decide whether the field is going to be considered a primary key or not.

  • Use a given Transformation, if applicable.

  • Enable or disable Fields as desired.


By default, the integration provides 40 different fields to be imported and distributed among the different CI types.

CI Type Fields and some of the default values

Note that the integration provides a set of predefined transformations (not to be confused with the Field Normalization plugin, see the Using the Field Normalization plugin section for more information) to be applied to the Nexthink value before being imported into the associated ServiceNow field. Some transformations are very field-specific, while others are more general. This must be taken into consideration if a flexible configuration is used. Transformations should be applied in a coherent and careful manner. A misplaced transformation can lead to import inconsistencies or worse, to the failure of the whole import process.

Additionally, be aware that PK fields cannot have any transformation associated because they are used to uniquely identify records. In the event a PK requires a transformation, refer to the Using the Field Normalization Plugin section of this guide.

CI Relationships

Relationships that are to be imported are defined in the CI Relationships table, as shown in the illustration below. As depicted, it is possible to enable or disable each relationship by simply setting the Is Enabled field accordingly.

Additionally, it is possible to decide if the relationship (previously inserted from Nexthink) must be deleted from ServiceNow when it does not exist in Nexthink anymore. This can be done with the Is Deletable column. Note that setting this field to true, allows the relationships to be kept completely up to date, but this implies higher processing, which in turn increases the duration of the population process.

By default, the application makes the 7 different relationships available, as shown below.

CI Relationships table with default values

Engines

Using this table, it is possible to select which Nexthink Engines will provide information to the ServiceNow CMDB. The different fields to be filled-in are shown in the illustration below. As many Nexthink Engines as needed can be defined in this table, meaning that the integration supports multi-engine implementations of Nexthink software.

Fields for the Engine table

Note that the MID Server field is not mandatory when defining a new Nexthink Engine. Only those engines located inside an intranet or not accessible from the Internet using Basic authentication would need it. Thus, unless either a proxy or a MID Server has been set up, the cloud instance of ServiceNow will not be able to retrieve data. Follow your proxy instructions or ServiceNow instructions on how to set up a MID Server.

Stats

The Stats table is filled with the number of items updated, inserted and deleted for the different CI types and relationships after each import process, see illustration below. The Job run field is increased for each import, thus allowing previous executions to be monitored

Please note that for some relationship population statistics, the Items deleted column will show the 0 value, instead of the expected number of relationships deleted. Due to how ServiceNow works with default configuration, if one of the CIs of a certain relationship is deleted during the CI Type population process, ServiceNow automatically deletes the existing relationships for such an element. Therefore, when the CI relationships population runs after the CI types population finishes, expected relationships will have already been deleted.

Stats table with some sample data

References

Similar to the Stats table, this table is purely informative. Occasionally during the import process, the integration needs to create new records in tables different from those defined in the CI Types and CI Relationships tables. This is because some fields in ServiceNow are implemented as references to other tables. For instance, the field Manufacturer in the Workstation table is a reference to a given record in the standard core_company table.

Therefore, the References table informs the user about unexpected records that have been created, thus allowing the information of the newly created record to be completed if desired.

Be aware that this table does not reflect any reference inserted using IRE. The Identification and Reconciliation Engine will manage these insertions on its own and they will not be reported in this table.

New fields

For the normal operation of the integration, especially for the delete/deactivate action, the fields listed on the table shown below are added to the ServiceNow tables (both CMDB and system).

ServiceNow table

Fields added

cmdb_ci_computer

x_nexsa_cmdb_pop_is_deletable x_nexsa_cmdb_pop_is_nxt

cmdb_ci_spkg

x_nexsa_cmdb_pop_is_deletable

x_nexsa_cmdb_pop_is_nxt

cmdb_ci_service

x_nexsa_cmdb_pop_is_deletable

x_nexsa_cmdb_pop_is_nxt

cmdb_rel_person

x_nexsa_cmdb_pop_is_deletable

x_nexsa_cmdb_pop_nxt_relation

cmdb_rel_ci

x_nexsa_cmdb_pop_is_deletable x_nexsa_cmdb_pop_nxt_relation

 

cmdb_software_instance

x_nexsa_cmdb_pop_is_deletable x_nexsa_cmdb_pop_nxt_relation

x_nexsa_cmdb_pop_type

 

sys_user

x_nexsa_cmdb_pop_is_deletable x_nexsa_cmdb_pop_is_nxt

x_nexsa_cmdb_pop_last_discovered

Note that these are the default tables that are predefined in the integration for basic operation. In the event that different tables are going to be configured, these new fields should exist for such tables.

Business rules

To help with the installation, configuration and operations of the connector, several business rules have been defined. These business rules monitor actions such as the following:

  • Checking that the desired import actions (update, insert or delete) have the proper permissions in the corresponding ServiceNow table.

  • Checking that at least one primary key field has been defined for each CI type.

  • Checking the maximum number of fields (and primary key fields) allowed for each CI type.

  • Checking that the ServiceNow field selected actually exists in the corresponding CI type associated table.

  • Avoiding the creation of duplicate CI type fields.

  • Avoiding using the same ServiceNow table for two different CI types.

  • Avoiding transformations to be applied to primary key fields.

  • Avoiding the creation of new, or deletion of existing, CI types or relationships.

  • Avoiding the creation of new, or deletion of existing, CI type fields. This business rule is disabled by default and should be enabled after the initial configuration.

Setup scripts

The script under this module performs a basic default configuration, thus populating the tables' CI types, CI type fields and CI Relationships with the default data to allow the ServiceNow administrator to configure the data that will be imported to the CMDB tables.

Import sets, data sources and scheduled imports

The Nexthink CMDB Populator integration provides one import set, data source and scheduled import for each of the CI types and relationships that can be imported.

Import sets are a special type of ServiceNow table intended to be used during the import process. They act as a staging area, receiving the raw data to be imported from the data source and mapping the data into the destination ServiceNow table.

Data sources define where and how the data is retrieved before being inserted into the import set. Alongside transformation maps, they define how data will be transformed during the mapping process from the import set to the destination table.

Scheduled imports specify that a given import operation will be executed at a regular interval, which can be defined (daily, weekly, periodically, etc.). By default, the scheduled imports provided by the integration are inactive, as they will be executed programmatically by a different script (see the section below for further information).

Scheduled scripts

The execution of these scripts starts the import process, as they call the corresponding scheduled imports. Therefore, two scheduled scripts are defined: one for the CI types (SI Nexthink) and another one for the CI relationships (SI Nexthink Relationships).

Be aware that the scheduled scripts can be configured to be executed automatically upon a given frequency (daily, weekly, monthly, on-demand, etc.). However, both scripts are inactive by default in the integration, thus allowing the customer to define the desired periodicity. Apart from this, it is also important to note that the scheduled script must be executed in all cases by a user or service account with an admin role.

Roles

Nexthink CMDB Populator integration creates two new roles to manage the application, the x_nexsa_cmdb_pop.manager and the x_nexsa_cmdb_pop.stats_viewer roles. Additionally, a user or service account with admin rights is also required.

Role

Task

admin

  • Execute the scheduled script to trigger the data import process.

  • Activation of Business Rules

x_nexsa_cmdb_pop.manager

Configure the application :

  • Setup CI Type, CI Type fields and CI Relationships tables

  • Activate/deactivate CI Type and Relationship insertion

  • Configure set of fields that will be imported

x_nexsa_cmdb_pop.stats_viewer

View the Stats table

Be aware that depending on the existing Access Control Lists (ACLs) that are applied in your instance, some may need to be modified to include the x_nexsa_cmdb_pop.manager role. If not modified, some system tables and their associated records might not be shown when performing the initial setup.

Properties

The set of system properties created by the integration are shown in the table below.

Name

Application

Type

Default value

Description

x_nexsa_cmdb_pop.run_rel_i mport_cascade

Nexthink CMDB Populator

true | false

true

Set to true to allow execute CI Relationships population automatically when CI Types population finish.

x_nexsa_cmdb_pop.rest_time out

Nexthink CMDB Populator

Integer

600

Timeout in seconds for HTTP responses when using REST messages.

x_nexsa_cmdb_pop.platform

_windows

Nexthink CMDB Populator

true | false

true

Set to true to specify Windows as target platform in the NXQL query.

x_nexsa_cmdb_pop.platform

_macos

Nexthink CMDB Populator

true | false

true

Set to true to specify MacOS as target platform in the NXQL query.

x_nexsa_cmdb_pop.nxql.bet ween.to

Nexthink CMDB Populator

String

midnight

Sets the “to” date up to which the data will be obtained for some queries.

x_nexsa_cmdb_pop.nxql.bet ween.from

Nexthink CMDB Populator

String

midnight- 7d

Sets the start date from which the data will be obtained for some queries.

x_nexsa_cmdb_pop.ire_disco very_source

Nexthink CMDB Populator

String

x_nexsa_c mdb_pop. ire_discov ery_source

IRE Discovery Source value for items retrieved by Nexthink CMDB Connector with IRE activated. This value should be included in the choice list at table "Configuration Item" [cmdb_ci] and field "Discovery source"(.discovery_source).

x_nexsa_cmdb_pop.insert_ch oices

Nexthink CMDB Populator

true | false

false

Set to true to allow insert new values in sys_choice table.

x_nexsa_cmdb_pop.enable_n ormalization

Nexthink CMDB Populator

true | false

false

Enable Field Normalization for CI table keys.

x_nexsa_cmdb_pop.enable_ir e

Nexthink CMDB Populator

true | false

false

Enable IRE for inserting, updating and deactivating Configuration Items.

x_nexsa_cmdb_pop.devices_ per_batch

Nexthink CMDB Populator

Integer

50

Number of devices to be queried per batch (for relationships only).

Nexthink components

For the integration to work properly, it is also necessary to install a content pack composed of different items. The installed Nexthink components are explained in the following section.

Finder categories

To provide even more flexibility to the integration, three new categories are included in Finder:

  • Devices

  • Packages

  • Users

Newly created Finder Categories for devices, packages and users

Each category has three keywords defined, shown below, allowing the expected behavior of every single object to be selected during the import procedure. This way, objects tagged with the to analyze keyword are skipped from the process, as they will need further analysis before being considered for import. Those objects with the ignore keyword will be ignored during the import process, and only objects with the synchronize tag will be taken into consideration by the integration.

Refer to the Configure Nexthink categories section to learn how to properly set the categories.

Default keywords and auto-tagging conditions for the device category

Finder metrics

The integration provides nine new metrics, one for each type of object (devices, packages and users) and the corresponding keyword in the new categories created (to analyze, ignore and synchronize). This makes it possible to know how many objects will be imported the next time the import process is run. The new metrics installed are shown in the illustration below.

Newly created metrics to keep track of the number of objects imported

Portal dashboard

The new metrics are shown in a new dashboard module in Portal as shown below.

Metrics are shown in a Portal dashboard

Initial configuration

Once the application has been installed, an initial configuration is needed. For a successful configuration, follow the next steps in ServiceNow in the same order in which they are presented. A manager role is required to carry out the configuration process.

Grant permissions to ServiceNow tables

In order to allow the application to insert the aforementioned new fields, refer to the table below. It shows the list of tables that should be made accessible from all application scopes, in addition to all necessary permissions.

ServiceNow table

Permissions to be granted

cmdb_rel_type

Read/Create

cmdb_rel_user_type

Read/Create

sys_choice

Read/Create/Update/Delete

sys_attachment

Read

Please note that Create permission for the tables cmdb_rel_type and cmdb_rel_user_type will only be necessary if the user wants to create custom relationship types. Similarly, sys_choice will need Create, Update and Delete permission only if the user wants to enable choice list values insertion through the provided property (x_nexsa_cmdb_pop.insert_choices).

Additionally, to allow the integration to store information from Nexthink into the CMDB, it is necessary to make some tables accessible from all application scopes and configure some permissions for them. Depending on the population required (insert, update and/or delete), it will be necessary to configure different permissions.

See the table below for the list of CMDB tables and permissions needed by the integration when using the default configuration.

ServiceNow table

Permissions to be granted

cmdb_ci_computer

Read/Create/Update/Delete

cmdb_ci_service

Read/Create/Update/Delete

cmdb_ci_spkg

Read/Create/Update/Delete

cmdb_ci_win_server

Read/Create/Update/Delete

cmdb_rel_ci

Read/Create/Update/Delete

cmdb_rel_person

Read/Create/Update/Delete

cmdb_software_instance

Read/Create/Update/Delete

sys_user

Read/Create/Update/Delete

This is the whole list of permissions needed when the import actions (insert, update and delete) are selected for all the tables. Depending on the specific requirements, only some permissions will be needed. For instance, if for a given CI type it is only necessary to insert data, then it will only be necessary to grant the Create permission, in addition to the Read permission, which is mandatory.

Note that these are the default tables defined to populate data from Nexthink to ServiceNow. If tables other than default tables are configured by the user, these permission policies must apply for them. Be aware, if different tables are to be used, only tables inheriting from cmdb_base table (or sys_user for users) can be used.

Configure Global ACLs

To allow users with role x_nexsa_cmdb_pop.manager to completely configure the connector, some ACLs at Global scope should be created/modified.

These configurations should be managed with care. If for any reason there is concern regarding these elevated privileges, you can rely on an admin user role to perform the configurations.

The full list of necessary ACLs is:

ACL Number

Table (Entity)

Operation

Requires Role

Comment

CMDB-Global-ACL-

001

ecc_agent

Read

x_nexsa_cmdb_pop.manager

 

CMDB-Global-ACL- 002

ecc_agent.name

Read

x_nexsa_cmdb_pop.manager

OOB there is an ACL at ecc_agent.*

CMDB-Global-ACL-

003

oauth_entity_profile

Read

x_nexsa_cmdb_pop.manager

 

CMDB-Global-ACL- 004

 

oauth_entity_profile.name

Read

 

x_nexsa_cmdb_pop.manager

OOB there is an ACL at oauth_entity_profile.*

CMDB-Global-ACL-

005

sys_data_source

Read

x_nexsa_cmdb_pop.manager

 

CMDB-Global-ACL-

006

sys_db_object

Read

x_nexsa_cmdb_pop.manager

 

CMDB-Global-ACL-

007

sys_db_object.label

Read

x_nexsa_cmdb_pop.manager

OOB there is an ACL at sys_db_object.*

CMDB-Global-ACL-

008

cmdb_rel_type

Read

x_nexsa_cmdb_pop.manager

 

CMDB-Global-ACL- 009

sys_auth_profile

Read

x_nexsa_cmdb_pop.manager

 

Engine

In order to allow x_nexsa_cmdb_pop.manager to completely configure the Engine, it will be necessary to enable ACLs:

  • CMDB-Global-ACL-001

  • CMDB-Global-ACL-002

  • CMDB-Global-ACL-003

  • CMDB-Global-ACL-004

  • CMDB-Global-ACL-009

CI Types

In order to allow x_nexsa_cmdb_pop.manager to completely configure the CI Types, it will be necessary to enable ACLs:

  • CMDB-Global-ACL-005

  • CMDB-Global-ACL-006

  • CMDB-Global-ACL-007

CI Relationships

In order to allow x_nexsa_cmdb_pop.manager to completely configure the CI Relationships, it will be necessary to enable ACLs:

  • CMDB-Global-ACL-005

  • CMDB-Global-ACL-006

  • CMDB-Global-ACL-007

  • CMDB-Global-ACL-008

Important Note about ACLs on Instances

All these ACLs are under the instance admin responsibility and depending on the current instance configuration may need additional changes.

It is important to pay special attention to masking the current table.* ACLs, specifying them in case new table.field level ACLs are being set.

Configure Engine authentication

Before taking the next step, it is necessary to declare an authentication profile to be used when retrieving Nexthink information. If configuring the engines using Basic authentication is required, the proper credentials must be inserted in a record in the sys_auth_profile_basic table, as shown in the illustration below.

Example of authentication profile defined for the integration

The credentials are used, for instance, when executing queries in the NXQL editor. If different Nexthink Engines have different credentials, one authentication profile for each credential will be needed.

If planning to connect to the engines via Oauth 2.0, it is necessary to create an OAuth profile following the procedure enclosed in the ServiceNow official documentation.

Define Platforms

The CI Type Fields available to be imported depend on the platforms selected in the Properties module. Each platform has an associated data model in NXQL. Choosing both Windows and macOS platforms may result in errors when writing queries in NXQL as certain fields do not exist for both platforms.

Be sure to select the appropriate platform(s) according to the fields that need to be imported.

Properties to define the platforms

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

Register Engines

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

  1. Click on the Engines module.

  2. Click on the New button and fill out the form. The table below shows how to fill out this form:

ServiceNow field

Value

Common fields

Name

<engine_name>

Endpoint

https://<your-engine-ip>:1671/2/query/ for on-premise instances ornhttps://<your-engine-ip>:443/2/query/ for cloud ones.

Authentication Type

<Basic/Oauth 2.0>

Status

Idle

Fields available only if Basic authentication type is selected

Mid Server

<my_midserver> (not needed for cloud deployments)

Profile Auth

<auth_profile> (authentication profile with proper credentials, see previous section 5.2)

Fields available only if Oauth 2.0 authentication type is selected

Oauth Profile

<Oauth_2.0_profile> (Oauth 2.0 authentication profile, see previous section 5.2)

Oauth Requestor Profile

<Oauth_requestor_profile> (User with oauth_admin role)

  1. Click on the

Submit button to save this engine.

Repeat this process to add more engines if necessary. Note that the application is multi-engine and is able to retrieve and process data from several Nexthink Engines at the same time.

Execute setup script

Once the application has been installed on the ServiceNow instance, it is necessary to execute the setup script:

  1. Click the Setup Scripts module to display the Scheduled Script Execution named Settings Tables Setup.

  2. Click the Settings Tables Setup record.

  3. Click on the Execute Now button to load the initial configuration.

This script will basically fill in the new tables created by the application as well as insert necessary records in some CMDB tables.

Define population configuration

Once engines have been configured, it is necessary to configure what kind of information will be imported from Nexthink and how. Although a default configuration is loaded with the Setup Script, CI Types, CI Type Fields, and CI Relationships tables can be configured to select the data to be imported.

To change the default configuration for CI Types:

  1. Click the CI Types module.

  2. If necessary, change the value for the SN Table column depending on the table where the CI type data retrieved from Nexthink will be stored in ServiceNow. Please remember that only tables inheriting from the cmdb_base table (or sys_user for users) can be used.

  3. Change the value for the Can Update column if it is necessary that data existing in both CMDB and Nexthink is updated.

  4. Change the value for the Can Insert column if it is necessary that data existing in Nexthink and not in CMDB is inserted.

  5. Change the value for the Can Delete/Can Deactivate column if it is necessary that data existing in CMDB (previously inserted from Nexthink) and not in Nexthink is deleted.

This procedure will not work on users with admin permission. If attempting to delete a user with an admin role, the message “NexthinkCMDBPopulator::BR Admin User not deletable :setAbortAction : User [USER] can't be deleted due to it has admin role” will be displayed in logs.

In the event that some enabled permissions are not compatible with the current configuration of the associated ServiceNow table, a message will appear noting the issue.

To change the default configuration for CI Types Fields to be imported:

  1. Click the CI Type Fields module.

  2. If necessary, change the value for the CI Type column depending on the CI Type that the field belongs to.

  3. If necessary, change the value for the Name column depending on the field name.

  4. If necessary, change the value for the SN Field column depending on the ServiceNow field that the field definition is associated to.

  5. If necessary, change the value for the NXT Field column depending on the Nexthink field that the field definition is associated to.

  6. If necessary, change the value for the Is PK column if the field will act as a primary key.

  7. If necessary, change the value for the Transformation column if some standard transformation is required for the field. This field should be set carefully as there may be unexpected results if an unsuitable option is chosen.

  8. Change the value for the Is Enabled column if the field must be retrieved from Nexthink to ServiceNow.

Note that there is a limit of 30 enabled fields and 3 enabled primary key fields for each CI type definition. Setting up these records, the ServiceNow user can select which CI Types information will be populated from Nexthink.

To change the default configuration for CI Relationships to be imported:

  1. Click the CI Relationships module.

  2. If necessary, change the values for the Is Enabled column if the relationship must be retrieved from Nexthink to ServiceNow.

  3. If necessary, change the values for the Is Deletable column if the relationship (previously inserted from Nexthink) must be deleted from ServiceNow when it does not exist in Nexthink anymore. Remember that setting this field to true could increase the duration of the population process.

With these permissions, the ServiceNow user can select which CI Relationships information will be populated from Nexthink to ServiceNow.

Configure Nexthink categories

This is a key step in the population of the ServiceNow CMDB. It defines what the conditions are to import users, devices, and software. For this purpose, there are three categories included in Finde: one for devices, another for packages and one for users, as shown below.

ServiceNow CMDB categories

From Nexthink Finder, by default, some useful auto-tagging conditions are defined for the to analyze keyword, while the other two keywords are empty. For a basic configuration, please copy the to analyze conditions into the synchronize keyword and then delete them from to analyze.

Conditions to export to ServiceNow CMDB

Notice that this basic configuration is not recommended in a production mode since it will import data that might not be useful from the CMDB point of view, thus overloading the system.

Tips for creating conditions in the Categories

CMDB experts should be asked some of the following questions based on what information is required to be populated:

  1. Users: Do you want to only add users that appear in the Active Directory? If yes, then create rules to exclude those without Active Directory information, otherwise, non-real users created by software installations, for example, could be populated.

  2. Devices: Do you want to add all devices, or are there any specific devices you want to keep out?

  3. Software packages: Do you want to add every piece of software available in the devices, including all updates and packages, or do you want to focus on specific applications like Office, SAP, etc? We recommend including only those that are useful from the CMDB perspective.

This step is mandatory for the application to operate properly, otherwise, no data will be transferred to ServiceNow, or too much data without business value will be imported into ServiceNow.

Optional configuration

Configure email notifications

It is possible to configure email notifications in order to receive statistical reports regarding import processes executed by users. To achieve this, enable Email sending in System Properties.

  1. Click the standard Email Properties module under the System Properties separator.

  2. Under Email sending enabled, check Yes, then configure users/groups to send the statistical reports by email.

  3. Click the System Notification module.

  4. Edit the Nexthink Last Stats Report record.

  5. Click the Who will receive tab.

  6. Add users or groups.

Configure related lists

By default, some related lists for computers, services and users’ views are not enabled due to ServiceNow default configuration. Because of this, some additional configuration for layout views must be completed to enable the related lists offered by the integration.

Enable existent tabs

All the related lists can be configured in the same way:

  1. Navigate to the desired view.

  2. Right-click on the gray top header.

  3. Select Configure -> Related Lists.

  4. Move the corresponding related list to the selected set.

  5. Save the change.

Please follow these instructions for any additional related lists.

Computer view

Navigate to any Computer record. For this view, the Services Consumed related list is available, which shows information about the services that the device is consuming.

Service view

Navigate to any Service record. For this view, two related lists are available:

  • Users Relationships, a list that provides information about users utilizing the current service.

  • Consumed by, a list that displays information about computers that are using the current service.

Configure tab for User view

The user view belongs to the Global scope making it impossible to install the related list for this view. To create and enable the related list that displays information about which services are consumed by the user:

  1. Click the Relationships module, under the System Definition menu.

  2. Change your scope to Global.

  3. Click the New button and fill in the fields as indicated below.

  4. Save the new record.

Name

Consuming Services

Application

Global

Applies to table

User [sys_user]

Queries from table

People Relationship [cmdb_rel_person]

Query with

(function refineQuery(current, parent) { current.addQuery("user", parent.sys_id);

})(current, parent);

Now, open the User view. It is crucial to remain under the Global scope when performing the following steps:

  1. Right-click on the User header area.

  2. Select the Configure -> Related Lists option.

  3. Move the Consuming Services relationship to the selected set.

  4. Save the change.

After this configuration, you will see the new tab in the tabs area where you can view the services consumed by the current user.

Configure relationship types

If the user wants to handle custom relationship types rather than the default types, it is recommended to use the following schema:

ServiceNow table

Records to add

Relationship

Parent descriptor

Child descriptor

 

cmdb_rel_type

WindowsServer-Service WindowsServer-Software Workstation-Service

Workstation-Software

NXT-WindowsServer-Consumes NXT-WindowsServer-HasInstalled NXT-Workstation-Consumes

NXT-Workstation-HasInstalled

NXT-IsConsumedBy-WindowsServer NXT-IsInstalledOn-WindowsServer NXT-IsConsumedBy-Workstation

NXT-IsInstalledOn-Workstation

 

cmdb_rel_user_type

User-Service

User-WindowsServer

User-Workstation

NXT-Consumes

NXT-Uses-WindowsServer

NXT-Uses-Workstation

NXT-IsConsumedBy

NXT-WindowsServer-IsUsedBy

NXT-Workstation-IsUsedBy

This schema should already be included with the application. If new records for relationship types need to be created, Create permission must be granted to cmdb_rel_type and cmdb_rel_user_type tables. Additionally, CI Relationship table records must be updated accordingly, and the Relation Type field must be appropriately set once the new relationship types are created.

Configure scheduled scripts

Scheduled scripts can be defined to run based on specific needs. Be aware that although the CI Relationships import can be performed separately, executing such an import without a prior execution of the CI Types import can lead to inconsistencies.

The simplest approach is to activate the CI Types import, define the desired periodicity and allow the cascade import (see the section below for more information). Therefore, the CI Relationships import will be automatically executed after the finish of the CI Types import. Please note that if the execution of these scripts is scheduled, it is necessary to configure them to be run as a user or service account with admin role.

Allow cascade import

As explained, the x_nexsa_cmdb_pop.run_rel_import_cascade property allows the CI Relationships import to be automatically launched after the finalization of the CI Types import. The property should be set as needed.

Redefine CI Types mapping

If the mapping for a particular CI Type like a ServiceNow table to store data or an association between Nexthink and ServiceNow fields needs redefining, it is necessary to contact Nexthink Professional Services.

Using the Field Normalization plugin

The reconciliation of existing data in CMDB and data imported from Nexthink using the CMDB Connector is possible via the usage of the Field Normalization plugin available in ServiceNow.

The Field Normalization plugin allows the definition of transformation rules for certain fields in specified tables. This makes it possible to apply the transformation rules before the data from Nexthink is inserted in the tables, lowering the impact on import process performance.

The Field Normalization plugin is optional and can be activated in the same way as other plugins in ServiceNow.

System Definition Plugins.

When downloading the plugin, do not check the case “load demo data,” as the demo examples may interfere with existing tables.

Click on Activate.

Field Normalization plugin activation

Wait until the installation finishes. You can verify that the Field Normalization plugin is present in the menu bar.

To enable normalization for Nexthink data imported by the CMDB connector:

  • For fields that are not primary keys, there is no need for additional configuration steps in the Nexthink CMDB connector to apply the normalization.

  • For CI primary keys: It is necessary to enable normalization in the Connector Properties, “Enable Field Normalization for CI table keys”, as shown in the illustration below. Be aware that if data existed before the creation of the transformation rules, it will have to be updated with those transformations to avoid inconsistencies. This is critically important if the transformation affects primary keys.

Enabling normalization for CI keys

All transformation primary keys defined in CI Type Fields should be handled with care to avoid duplicates. For example, removing a domain name from two different email addresses that have the same username (name@domain1 and name@domain2) will result in the same string “name” thus creating a conflict.

For examples on how to use Normalization, please check the Using Normalization and Normalization examples document.

For more information about the Field Normalization plugin, refer to the ServiceNow official documentation.

Changes in the Nexthink Incident Management Connector configuration

The Incident Management Connector uses device identification to retrieve the score and device properties from Nexthink. When the related CI type is transformed due to normalization, it is necessary to make certain changes to the configuration of the CI type used to send the original device identifier to the Engines.

When creating normalization rules for the device CI primary key it is mandatory to add a raw field in the rule to store the original Nexthink data for CI Type Fields defined as primary keys.

You can use any field as a raw field ensuring that both the original and the raw field are of the same type (e.g., String, 40 characters long). If it is necessary to use a new field as a raw field, it can be created on the corresponding table like any other field.

In the properties section, you must indicate which fields are used for establishing the communication between ServiceNow and Nexthink (refer to the section Nexthink - ServiceNow mapping). The property "ServiceNow CI table field where the corresponding Nexthink device field is mapped" must contain the original data, so the name of the Raw field must be written there.

Identification and Reconciliation Engine (IRE)

Introduction

The Identification and Reconciliation Engine, also known as IRE, is a centralized framework to perform identification and reconciliation processes across different data sources. IRE uses identification rules, reconciliation rules and IRE data source rules when processing incoming data before inserting that data into the CMDB.

The IRE is mainly used to:

  • Reconcile the insertion of CMDB data coming from different sources.

  • Avoid storing duplicated data on the CMDB.

  • Establish precedence rules at register or field level.

  • Block modification from some sources due to the same CIs being inserted into the tables from different data sources.

Please note that the IRE module is designed to work over the CMDB tables only. This means that it will insert, update or deactivate data for only those CI Types that are based on CMDB tables (I.E: Workstation, WindowsServer, Service and Software). Since the User CI type is out of the CMDB hierarchy, it cannot be used to insert, update or deactivate any CI on the sys_user table. In addition, if any CI Type is edited to insert data in a table out of the CMDB hierarchy, it will be affected in the same way.

If further information is needed about the IRE, refer to the official ServiceNow documentation.

Pre-requisites

Before starting to insert CIs using the IRE module, it is important to note that this tool requires compliance with the following pre-requisites:

  • The plugin com.snc.cmdb.scoped should be activated.
    It can be activated in System Definition > Plugins > search for com.snc.cmdb.scoped and click on install.

Enabling plugin CMDB for scoped applications
  • The Sys_choice discovery source created for cmdb_ci table.
    A sys choice must be created to populate the field discovery source for each CI in the cmdb_ci tables. To fulfill this requirement, it is necessary to go to the sys_choice table and create a new choice with the following details under the global scope:

Table

Configuration Item [cmdb_ci]

Element

Discovery_source

Language

en

Label

<Label> (I.E : Nexthink CMDB Connector)

Value

nexthink_cmdb_connector

  • Identification rules for every required CI types (Computer, Software and Service)
    This is one of the key parts of the IRE system. It is used to uniquely identify an inbound CMDB payload. After identification, the system will decide to create a new CI or update an existing one rather than creating duplicates based on this information.

These identification rules can be created in the Configuration > CI Class Manager section.

  1. Click on hierarchy.

  2. Search for the table in which the rule will apply.

  3. Click on it on the results pane.

  4. Click on identification rule.

In this section, an identification rule and an identification entry must be created. Although the whole process can be found on the official ServiceNow documentation, an example of how to create a rule to import software packages can be found below.

  1. Go to Configuration > CI Class Manager.

  2. Click on Hierarchy.

  3. Search "software" and click on the table displayed on the results panel.

  4. Go to the Identification Rule section.

  5. Click on the Add button and create a rule using the following parameters:

Create Identification Rule menu
  1. Click on the Add button under the identifier entries

section.

  1. Select the option Use attributes from main table

‘Software’ and click on next.

  1. Move the Primary Key fields defined for this CI Type in the CI Type Fields table from the available

column of the criterion attributes to the Selected column. (In this example Name and Version are the default fields).

  1. Set priority (I.E: “050”).

Edit identifier entry menu

10. Click on save.

11. The results should look like this:

Example of Identification Rule created for software CI

Please, keep in mind that this is just an example and Identification Rules may need to be created for other CI types, such as workstations or services, depending on the setup planned for the instance.

How to activate IRE usage

The IRE module can be activated on the Nexthink CMDB Connector > Settings > Properties module.

It is only required to mark the checkbox under the Enable IRE for the inserting, updating and deactivating Configuration Items property.

How to deactivate a CI using IRE

In contrast to legacy mode where the CI records are deleted from the CMDB tables, the IRE module does not allow any logic to automatically erase any CI itself. If this is the case, IRE will allow the record to be deactivated.

The deactivation of the records is based on the configuration of the two new fields added to the CI Types table:

  • Deactivate Field

  • Deactivate Value

If the column Can Delete/Can Deactivate is set to true, the next time the scheduled script is executed, IRE will check if any of the CIs with the field Is NXT are set to true, and the column Most Recent Discovery populated is not received on the payload. If this is the case, IRE will update the column configured in the Deactivate Field for that CI type with the value set in the Deactivate Value to mark that record. Since IRE is updating the CIs that match with the aforementioned conditions, in addition to configuring the Can Delete/Can Deactivate field, it is also necessary to set the field, Can Update, to true.

In the event it is necessary to truly delete the CI from the table, the ServiceNow administrator will need to filter the CIs marked and remove them manually.

For example, to deactivate the workstations, it is necessary to set the following configuration on the CI Type table:

Example of Identification Rule created for software CI

In summary, the field Can Delete/Can Deactivate has been activated for the Workstations and is configured to fulfill the field short_description on the cmdb_ci table with the string “To be deleted”. Thus, to allow IRE to update the value of the field configured, it is also required to set the field Can Update to true.

On the other hand, with the CIs on the computer table below:

Example of Identification Rule created for software CI

The next execution of the scheduled script, the CI *ANNIE-IBM will not be included in the payload. Therefore, the field description will be updated similar to the image below:

Example of Identification Rule created for software CI

At this point, the ServiceNow administrator would need to create a filter to find all CIs with this description and make a decision about what should be done with them.

Be aware that as explained in the introduction of the IRE module, the IRE module (and thus, the deactivation procedure) will only apply changes on CIs stored within the CMDB tables. If the CI Type is storing data in a table out of the CMDB table (I.E: sys_user), the CI will not be deactivated.

Running the application

In order to run the application, simply configure the Scheduled Script as needed. The import process can also be launched manually if needed. To do so:

  1. Click on the Scheduled Scripts module.

  2. Select the necessary import option: SI Nexthink or SI Nexthink Relationships.

  3. Click on the Execute Now button.

Special import conditions

Some of the objects/relationships to be imported from Nexthink are subject to special conditions. These considerations are explained below.

Workstations

Only Nexthink devices with device_type different from server and mobile will be considered.

Servers

Only Nexthink devices with device_type equal to the server will be taken into consideration.

Software

Only Nexthink packages with status equal to installed are to be taken into account.

Users

Only Nexthink users with type different from system will be imported. Please note that the admin user will never be deleted from ServiceNow (even if it was updated by the integration).

Workstations-Users & WindowsServer-Users

The link between the users and the devices is done using the user_activity table. This activity represents either a logon or an interaction between the user and the device (through mouse or keyboard).

Upgrade considerations

Note that if the application is upgraded, it might be necessary to carry out the whole configuration process again to reconfigure the data that will be populated to ServiceNow. In addition, it might be necessary to restore the Form Layouts configuration that was modified before the upgrade and also to investigate, in the upgrade history table, if any change has been skipped. If this is the case, it would need to be committed.

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. If you have any questions please contact us via Nexthink support portal.