Domain separation installation (IMC)
Last updated
Last updated
This guide provides comprehensive information on how to install and configure the Nexthink Incident Management Connector in a ServiceNow instance with Domain Separation enabled. Following the process explained here, the Connector will work in different domains.
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 and ServiceNow technologies, especially the Domain Separation concepts and the Nexthink Incident Management Connector itself. The configuration instructions must be executed by a ServiceNow certified professional.
Nexthink Incident Management Connector, officially, does not support multi-domain. However, according to the ServiceNow Domain Support Levels, the Connector is at Level 0 - Data only: "It enables the separation of tenant data only in an application. It is not domain separated in the truest sense, because the logic to route data to domains in the application is absent. All data created is placed in the current domain of the session creating the data." Every custom table includes the domain field, enabling the Connector to be run in different domains.
Since there are as many scenarios for Domain Separation as ServiceNow instances with it enabled, this document covers only the most frequent one: Nexthink Incident Management Connector working in final domains. That is A1, A2, and B in the following picture:
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.
Nexthink Incident Management Connector requires a running implementation of the Nexthink product with the following pre-requisites:
An appliance with Nexthink version 6.12.2 or later
Integrate license to use the Web API
Act license to use Remediations. In addition, parametric remote actions require Nexthink version 6.29 or higher
On the other hand, the Connector must be installed in a ServiceNow instance with Domain Separation enabled. To do so, please follow the official ServiceNow documentation.
Following this process, Nexthink Incident Management Connector will work in a ServiceNow instance with Domain Separation enabled. The Connector itself is installed in the Global domain, however each final domain will have its own Engine and Finder records to connect to the appropriate Nexthink instance and also its own Score Definitions. All other components and records of the Connector remain at the Global domain (meaning that they will be visible to all the domains in the instance, please review the Considerations and Recommendations section for the details).
The process has 2 main parts:
First, Nexthink Incident Management Connector 2.0.0 must be installed in a ServiceNow instance with Domain Separation enabled. This can be achieved via:
Fresh installation of the Connector through the ServiceNow Store.
Upgrade from a previous version as detailed in Upgrading to IMC 2.0.0.
Next, it is necessary to configure the Connector to work with Domain Separation. The most relevant steps are:
Global setup for all the domains: Properties, Device Tables and Device Properties
Creation of specific records within a domain: Engine, Portal and Score Definition
Run Discovery and test the application
There is a highly recommended extra step: secure the Connector's custom tables — whose records remain in the global domain — so only the appropriate users can see and manage them. Generally, only MSP administrators should have the ability to perform these operations.
To clarify the sequence of the process, the following diagram shows the main steps and when they should be completed:
As explained above, it is highly recommended to secure everything related to Nexthink Incident Management Connector that remains in the global domain. Only MSP administrators should be able to manage domains.
Connector's properties cannot be specified per domain. When a property is changed, it will affect all domains. Before starting Nexthink Incident Management Connector domain separation, it is best to plan how these properties will be configured.
The Default Configuration Setup Script inserts all the required data. Since the Connector logic does not take domains into consideration, everything is done globally. This has two implications:
Customizations done globally are overwritten and restored to the initial status.
Customizations done in a domain could be lost since the record will be created/updated in global.
As a recommendation, use this Setup Script only at the beginning of the process after installing the Connector.
Nexthink Incident Management Connector uses the Scheduled Script Discover Engines - Devices to determine which CIs are present in the Nexthink Engines. This is key to the functionality of the Connector since the Engine is needed to query all the CI data from the incident form. The script only updates the fields NXT Engine and NXT Platform of the tables included in Device Tables.
As is the case with all the logic, the Discovery process is domain agnostic. Its behavior depends on the user who launched it (normally specified in the "Run As" field). The process queries all Nexthink Engines (that the user can see) to determine if any of the CIs (that the user can see) are related and, if they are, updates the record. With this, there are two recommended scenarios:
Both Discovery script and user are located in the global domain: Set in the "Run As" field an MSP administrator user can see all the Engines and CIs in the ServiceNow instance. Therefore, when Discovery runs, it will update the information for all the customers/domains. This is the easiest option to configure.
Specific Discovery script and user per domain: For MSPs that prefer to distinguish the Discovery process per customer (for instance, to define different schedules). To do so, two things are required:
Specific admin user per domain
Specific Discovery script per domain
Go to Nexthink Incident Management Connector → Scheduled Jobs and click on Discover Engines - Devices.
If the field "Run As" is not visible, enable it:
Configure → Form Layout (this must be edited within the Global scope)
Move the field “Run As” to the Selected column.
Change the name, adding something related to the domain, such as "Discover Engines - Devices: Domain A1."
Select in the "Run As" field the specific admin user of this domain.\
To create a new record, remember to select Insert and Stay from the Additional Actions menu instead of pressing the Update button.
To avoid confusion, it is recommended to remove the first (generic) Discovery script when every domain has its own Discovery created.
Be aware that CIs with the same values according to Nexthink - ServiceNow Mapping (defined in the Connector's properties), are considered the same for the Discovery and could lead to bad functionalities. To avoid this situation, make sure CIs for different domains differ.
The table x_nexsa_imc_device_table defines in which CMDB tables the devices stored will be considered for the data retrieval process. Due to the definition of this table, it is not possible to duplicate a selected table, even for different domains. Therefore, the configuration done in this table will be shared for all the domains in the instance.
Recommendation: While the table can be modified, ensure that only MSP users can see it and modify it since the changes will affect all the domains.
Similarly, as explained for the Device Tables, the definition of the Device Properties table does not allow for duplicated values. Thus, all these records must be left global and shared for all the domains in the instance. In practice, this means that fields shown in the Device Properties tab are the same for all the domains. With this in mind, it is recommended to ensure that only MSP users are allowed to see and modify the records of this table.
As with the other tables, the Score Definition table does not duplicate the value for the name field. There are two cases:
Score Definitions that are not Device Properties: As a good practice, the recommendation here is to add in the name value something related to the domain, like "L1 Checklist - Domain A1" so names won't be duplicated between domains. The caption field, which defines the text that users will see in the tab, allows for duplicated values: "L1 Checklist"\
The Device Properties Score Definition cannot be duplicated, leading to two options:
Deactivate the Score: it won't be shown in any domain. Before doing this, please consider that this tab is needed to retrieve the data required to launch remediations. Use this option only if remediations are disabled in the Connector's properties.
Share the Score (Recommended): Leave the score as it is created by the Setup Script and double-check the fields that will be shown here makes sense for all the domains (see the Device Properties section)
Following the process described in this document, there is nothing to change regarding Score Queries: each domain will have its own score queries according to the Score Definitions.
Before installing Nexthink Incident Management Connector, domain separation should be enabled in the ServiceNow instance by installing the Domain Support - Domain Extension Installer plugin. The request can be made from the HI Service Portal Service Catalog. You can find more information on the ServiceNow official documentation.
Once activated, navigate to Domain Admin → Domains. You will find a default MSP domain called TOP, which is the immediate child of the global domain and can be renamed or deleted as appropriate. When creating a new domain, pay special attention to the fields Type and Parent:
The Type will have to match the Type field in any company that is created for that domain. For final domains, it is recommended to set both the Domain and the Company to the customer type.
Setting the Parent will determine the hierarchy of the Domains.
The structure of the domains created for the instance can be verified by navigating to Domain Admin → Domain Map.
A Company needs to be created for each final domain — as in ServiceNow, CIs are separated by domain using the Company field out-of-the-box and configuration will be performed at final domains. Open each domain record and on the Companies tab create a record. As mentioned before, the Type field corresponding to the company's field should be set to true (as stated above, for companies in final domains this implies checking the Customer checkbox).
For instances with domain separation enabled and version 1.3.1 of Nexthink Incident Management Connector installed, the configuration for the connector will be global for all domains. That implies that retrieving the score information for CIs in any subdomain will load the information for all score definitions, not only those scores defined for a particular subdomain. To separate score definitions by domain, it is required to upgrade the Connector to version 2.0.0; to do so, please follow the instructions in the section Upgrading to IMC 2.0.0 in this same document.
Create the corresponding users for each subdomain and assign them the required roles (please see the section Roles and ACLs of the documentation for more information) and configure the properties as appropriate. While users are kept domain separated from the box, properties will be changed on the global domain. For instance, setting a property in Domain A2 will also modify it for Domain A1 and up to Global.
Bear in mind that if the subdomains require a different MID Server, each subdomain will also require a user with the mid_server role assigned.
The default records for Device Properties and Device Tables are loaded by executing the Default Configuration Setup setup script.
Click on the Setup Scripts module and open the Default Configuration Setup record.
Finally, click on the Execute Now button.
Portals are used for the execution of remote actions.
Engines are used to retrieve the data used for the scores.
For the Open in Finder button in the Incident form to work, a Finder connection needs to be created. Click on the Finder Connection module and create a record with the following fields:
Click on Submit to save the record.
The Nexthink tabs displayed when creating are defined by the records created in the x_nexsa_imc_score_definition table. Click on the Score Definitions module and create a new record per score to be displayed.
The form will only include a Name field to be completed. After entering the value, save the record and attach the XML Scores configuration file associated with it. The remaining fields in the form will be completed using the file that was attached.
Finally, to assign an NXT Engine and NXT Platform to CIs, the Discover Engines - Devices Scheduled Job needs to be configured and executed. Open the record by clicking on the Scheduled Jobs module and Discover Engines - Devices record. If the attribute Run as is not displayed, configure the Form Layout to add it to the form.
Set the Run as field to a user with the admin role and either click on the Execute Now button or configure a scheduling condition to set when the job runs. If the process is successful, the field Status in the Engines will be updated to Ok and the fields NXT Engine and NXT Platform of the devices will be updated accordingly.
After this configuration is finished, the Connector is ready to be used. Bear in mind that users and CIs will be domain separated from the box, but all Score tabs, properties, and remaining configured records will be located at the global domain. Therefore, any CI discovered by the Scheduled Job that is used on an incident form will see all score definitions.
Bear in mind that Nexthink Incident Management Connector needs to be installed on the global domain, as it will flow down to all domains created on the instance (even for those added or removed after the installation).
Create the corresponding users for each subdomain and assign them the required roles (please see the section Roles and ACLs of the documentation for more information) and configure the properties as appropriate. While users are kept domain separated from the box, properties will be changed on the global domain. For instance, setting a property in Domain A2 will also modify it for Domain A1 and up to Global.
The default records for Device Properties and Device Tables are loaded by executing the Default Configuration Setup setup script.
Click on the Setup Scripts module and open the Default Configuration Setup record.
Finally, click on the Execute Now button.
All Device Properties and Device Tables records will be created in the global domain and should remain there. Changing the domain of a record in the Device Properties table will result in the Device Properties score definition working incorrectly, which will, in turn, cause the execution of remediations to not be available for all remaining domains.
New records for the Device Tables table can be created manually, but they must be kept at the global domain.
Portals are used for the execution of remote actions.
Only one Portal can be created for each subdomain. Portals should only be visible from their original domain or a parent domain (i.e. global can see all records).
Engines are used to retrieve the data used for the scores.
Engines should only be visible from their original domain or a parent domain (i.e. global can see all records).
All Names must be different (including from score definitions created in other domains) and should contain a reference to the subdomain to be more easily identifiable (e.g. "Overall IT Satisfaction A1"). On the other hand, the captions can be repeated as they are only used to give a name to the tab displayed on the incident form.
Please refer to the Discovery section of this guide to configure the script correctly.
The following considerations should be taken into account when using this configuration for a ServiceNow instance:
The application properties are defined on the global domain; therefore, any change made on a subdomain will be applied to the configuration of all the remaining subdomains.
The setup script should be launched only once or the records will be recreated and customizations will be lost. If it is executed after configuring the connector, the Score Queries for that domain will be copied onto the other subdomains. Please recreate Score Definitions to refresh the Score Queries and repeat any customizations done to Device Tables or Device Properties.
The Nexthink Incident Management Connector will be installed even on subdomains where the client may not use it. It is important to remember that users in this subdomain should not be assigned any "x_nexsa_imc" roles to avoid confusion by restricting access to the application's tables and ensuring the correct behavior of the incident form.
This chapter describes the upgrading process to Nexthink Incident Management.
Connector version 2.0.0. It assumes a previous version is already installed in the ServiceNow instance. An admin user is recommended for these steps since some special privileges are required within the instance.
The very first thing to do is to save the configuration of the Connector. Select your preferred backup method, for instance, screenshots. Below there is a list of the elements to store:
Discovery setup: scheduled and "Run As" user. Go to Nexthink Incident Management Connector → Scheduled Jobs and select Discover Engines - Devices
Business Rules: Although they all should be enabled, it is best to double-check them. Nexthink Incident Management Connector → Business Rules
Score Definitions: For each Score Definition, remember to save both the name and the Score XML attached to it. Nexthink Incident Management Connector → Settings → Score Definitions
Device Properties: Only for the customizations, the OOB properties will be recreated during the configuration of the Connector. Nexthink Incident Management Connector → Settings → Device Properties
Device Tables: Again, only if anything has been customized here. Nexthink Incident Management Connector → Settings → Device Tables
Portals: Make sure to save the whole configuration, including the DNS or IP, the Finder Port, mid server, and authentication profile. Nexthink Incident Management Connector → Settings → Portals
Engines: Per engine, store DNS or IP, Port, _Auth Profile (_both user and password will be required later), and MID Server. Nexthink Incident Management Connector → Settings → Engines
Properties: Go to Nexthink Incident Management Connector → Properties
Other customizations: Any other customizations (UI Scripts, Client Scripts) should be annotated to be able to replicate them after the upgrade.
As explained in the ServiceNow official documentation, go to System Applications → All Available Applications → All. Look for Nexthink Incident Management Connector and click Update.
Nexthink Incident Management Connector 2.0.0 provides two run Fix Scripts to facilitate the upgrade:
NXT-Delete UI Sections & Update Scores: This script deletes old UI Sections created in previous versions and automatically updates the Scores Definitions. It must be executed from the Global application scope.
NXT- Restore Portal & Engines: Since version 2.0.0, Portals and Engines are stored in the same table, x_nexsa_imc.endpoint. This Script reads the old tables, creates the appropriate records in the new one, and finally removes the unnecessary tables. Before running this script, double-check there is only one portal, otherwise it will not work (version 2.0.0 allows only one portal). It has to be executed from the Nexthink Incident Management Connector application scope.
To run them:
Log in to the ServiceNow instance with a user with an admin role.
Change to the appropriate scope:
NXT-Delete UI Sections & Update Scores: Global
NXT- Restore Portal & Engines: Nexthink Incident Management Connector
Go to Nexthink Incident Management Connector → Scripts → Fix Scripts.
Click the Fix Script name.
Set the Active field to true, save the record and reopen it.
Press the Run Fix Script button
After updating version 2.0.0 of the Nexthink Incident Management Connector successfully, certain configurations needs to be updated for the connector to work correctly.
To create the Device Properties score definition, the Setup Script will have to be executed again. Be sure that any customization done to Device Properties, Device Tables, and Properties is saved before performing this step, as described in this section.
Click on the Setup Scripts module and open the Default Configuration Setup record. Finally, click on the Execute Now button. The score queries will be updated correctly when the score definitions are moved to the correct subdomain, so it's unnecessary to recreate them yet.
After executing the NXT-Delete UI Sections & Update Scores fix the script, the score definitions created on the global domain need to be edited and moved to the appropriate final domain. Please remember to not change the Device Properties score definition. It should be kept in the global domain. It is recommended to use a user with the x_nexsa_imc.manager role created at the same final domain in which you want to configure the score definition so that only the correct Domain will be available to be chosen. Navigate to the Score Definitions module to see a list of all the records. If the Domain field is not displayed, make it available by clicking on the Personalize list button (gear icon) and move the domain row to the Selected column by clicking on it on the Available list and clicking on the right arrow.
Confirm by clicking on OK.
Double click on the Name field and modify it to add a reference to the final domain in which the score definition needs to be kept (e.g. for a score affecting subdomain A1, change the name to Overall IT Satisfaction A1). Double click on the domain to also edit it and select the final domain (as it is being modified by a user at that domain, only the correct one should be available).
The Portal record that was created on version 1.3.1. should have been moved correctly to the new Endpoint table in version 2.0.0. Please remember that, as indicated in our documentation, the change in the connector's behavior dictates that although having more than one Portal defined as possible for the previous version, only one record should be kept before executing the NXT- Restore Portal & Engines fix the script.
Enter the record from the subdomain to which it should be configured and edit the Form layout to add the Domain field to the selected fields. Save the configuration and enter the record. Change the domain of the Portal from global to the final domain that is being configured.
The Engine record that was created on version 1.3.1. should have been moved correctly to the new Endpoint table in version 2.0.0.
Enter each record and change the Domain field from Global to the final domain that is being configured. The Portal field will also be mandatory for this version. The domain field was added to the Endpoint table in the previous section. Please refer to it if it is not displayed when configuring the engines.
Because the table in which the Engines are stored has changed from version 1.3.1. to version 2.0.0, the Discovery process needs to be run again, as the reference to NXT Engine contained in the appropriate CIs is lost.
Navigate to the Scheduled Jobs module and execute the Discover Engines - Devices script by following the instructions in the Discovery section of this guide.
After the process has been executed correctly, the connector will be ready.
This section gathers who should be able to perform what within Nexthink Incident Management Connector:
Read and modify Properties.
See and run Setup Script.
See and run Discovery process. Unless a specific Discovery per domain has been created, as explained in Discovery; in this case, each Discovery can be run by the administrator of each domain.
See and manage Device Table records.
See and manage Device Properties records.
See and manage Device Properties records in the Score Definition table.
See Score Queries (since they are handled internally by the Connector, they should not be manipulated).
See and manage Score Definitions (except the Device Properties one).
See and manage Engines within the domain or in global.
See and manage Portals within the domain or in global.
Read Score Definitions.
Read Engines.
Read Portals.
See CIs within the domain.
Log in as an admin user working in the Global application scope Go to Domain Admin → Domains and click New
Complete the form:
Parent: Choose the desired domain as the parent.
Type: Domains, where Nexthink Incident Management Connector is used, are typically Customer type.
Active: Be sure this field is enabled, Click on Submit.
Select the new domain through the Domain Picker.
Go to Nexthink Incident Management Connector → Settings → Portals and click New.
Complete the form:
In addition to the usual fields, take into consideration:
Domain: It must be the new domain.
Default Portal: Do not mark this portal as the Default portal.
Select the new domain through the Domain Picker.
Go to Nexthink Incident Management Connector → Settings → Engines and click New.
Complete the form:
Please, pay attention to:
Portal: Must be the specific portal for the domain (see Create Nexthink Portal for the new domain)
Domain: The new domain
Must be maintained as Active
Select the new domain through the Domain Picker.
Go to Nexthink Incident Management Connector → Score Definitions and click New.
Name: Since duplicated names are not allowed in this table, please add something related to the domain name.
Caption: This will be shown in the Connector tabs. In this case, it is better to not distinguish between domains so the user in each domain will have the feeling of own ServiceNow instance.
Domain: This is the new Domain.
Maintain the Score Definition as Active.
Remember to attach the Nexthink Score file, the other fields will be filled automatically.
When a domain is removed, all the information that was stored at that domain is moved to its most immediate parent domain (e.g., Engines set to Domain A1 would be moved to Domain A). To avoid this behavior, it is recommended to delete these records:
For all CIs that were set to the Domain to be deleted and not saved, deleting the records will stop the records being moved to a higher domain.
Navigate to cmdb_ci.list and — if it is not already displayed — add the domain field to the view by clicking on the Personalize List button (gear icon) and moving the Domain option to the Selected column using the right arrow. Click on OK to save the changes.
Click on the Search column search row button (magnifying glass icon) and enter the search box for the Domain column the name of the domain to be deleted. Press the Enter key.
Select all records to be deleted, click on the dropdown list Actions on selected rows... at the bottom of the page → Delete and confirm.
Using a user with the x_nexsa_imc.manager role assigned to it that was created on the domain to be deleted, navigate to the Score Definitions module. If a user with those characteristics is unavailable, impersonate or log in as a user with the x_nexsa_imc.manager role with visibility over the domain to delete and change to it.
Select all records — except for the Device Properties score definition —, click on the dropdown list Actions on selected rows... at the bottom of the page → Delete and confirm.
Then, navigate to the Portals module, select the only record there and delete it following the same steps.
Finally, navigate to the Engines module, select all Engines created for that final domain and delete them.
Navigate to sys_user.list. Add the domain field by clicking on the Personalize List button (gear icon) and move the Domain option to the Selected column using the right arrow. Click on OK to save the changes.
Click on the Search column search row button (magnifying glass icon) and enter the search box for the Domain column the name of the domain to be deleted. Press the Enter key.
Select all records to be deleted, click on the dropdown list Actions on selected rows... at the bottom of the page → Delete and confirm.
Firstly, the Company that was created for the domain needs to be deleted. Navigate to Organization → Companies and search for the company's name using the search bar at the top of the page. Alternatively, add the Domain field to the list and filter by the domain to be deleted.
Select all records to be deleted, click on the dropdown list Actions on selected rows... at the bottom of the page → Delete and confirm.
Finally, to delete the domain itself, navigate to the Domains module, enter the record for the domain to be deleted and click on the button labeled Delete.
To verify that the process was correct, navigate to Domain Map and verify that the diagram has been updated correctly.
| ServiceNow field | Value |
|---|---|
Name
Portal
Reference to the Portal record
