Troubleshooting Guide (IMC)
Last updated
Was this helpful?
Version 6.30
Last updated
Was this helpful?
This guide aims to aid in troubleshooting issues that might occur with the Nexthink Incident Management Connector integration with ServiceNow. This document provides a detailed description of procedures that can help in analyzing problems, as well as guidance to debug and solve them.
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 Nexthink technology and ServiceNow technology, as well as some understanding of concepts such as REST messages, HTTP errors, and some basic security terms.
2022-09-05
Added “Cross-scope access policy errors after click on “Fix it” button”
2022-03-08
Added “Scores tabs caption not applied”
2021-09-30
Added “Self-Service portal Widget known Errors“
2021-03-26
Added “Not trusted certificates in Quebec”
2021-03-12
New version: v2.0.0
IMC can launch the new parametric remote actions.
The number of custom tables has been reduced.
Architecture has been improved.
Fix Scripts have been added for troubleshooting.
2020-12-03
New Section: “MID Server memory issues”
2020-09-01
New Section: “Scores displayed in incident form after deletion”
2020-05-26
New section: “No scores displayed on the Nexthink
panel”
2020-04-28
New Service Now store version 1.3.0
Integration with Agent Workspace: New Nexthink panel, which is feature parity with the Incident Form View.
New role to disable “Open in Finder”
2020-02-17
Added chapter “Finder custom actions”
2020-01-17
Added “Remediation Execution Error”
2020-01-15
Added section “General Upgrade Issues”
2019-12-30
New ServiceNow store version 1.2.1
Added Mac devices support
Added Cloud deployments troubleshooting
2019-10-10
New ServiceNow store version 1.1.2
Added snapshot creation support in Work Notes
If the data retrieval has failed and the log shows an HTTP 400 status error message, it usually means that the NXQL query executed is malformed, most likely due to some field not existing in the Nexthink device table. The error message looks like the following:
Method failed: (/2/query/) with code: 400
If this is the case, please check the available fields for the Nexthink device table, either by using Nexthink Finder or NXQL Editor, and verify that all the Device Properties and Score Definition fields involved exist in it. This sometimes happens when scores are changed but not re-imported in ServiceNow.
This error may also arise after a known issue that causes Score Queries to be generated incorrectly. In rare cases, after creating a Score Definition and attaching the XML file, the Score Query for Windows platforms may be duplicated or even triplicated. To solve this issue, please go to the device properties module, change one of the values in the platform column, set it back to its original value, and go back to the Score Query module. The queries should have been successfully re-created as expected.
If the data retrieval has failed and the log shows an HTTP 401 or 403 status error message related to a wrong user and password combination, it means that the authentication profile used to connect to the Engine is not properly configured. The error message looks like the following:
Method failed: (/2/query/) with code: 401 - Invalid username/password combo
If this is the case, please edit the Authentication Profiles used for the Engine and set the proper user and password.
Hint: The user and password to be used are those used to connect to the Web API V2.0, for instance, via the NXQL Editor.
Logs can also state an HTTP status code ‘0’ error message. This error arises when the Engine is not reachable for some reason, such as the Engine being shut down, the endpoint being erroneously configured, the DNS not being able to resolve the address, etc. The error message could look like the following:
Error from Nexthink API. HTTP status code '0' with query 'null'. Message: null; Error Message: The request failed: java.net.SocketTimeoutException: connect timed out when posting to https:///2/query
or:
Error from Nexthink API. HTTP status code '0' with query 'null'. Message: null; Error Message: The request failed: Unknown host
To fix this, please make sure that the Engine is up and running and configured with the correct address.
Verify that “Nexthink Incident Management Connector -> Properties -> Enables remediation (Nexthink Act) to be displayed in the Incident form, thus allowing the dispatch of remote actions” is set to true, and the “Score Definitions” have been refreshed after being activated.
The Score in question has remote actions configured in it.
In order to verify this, go to the XML file uploaded and look for a node with the tag “<RemoteAction.. ”>
The Configuration Item has defined both “NXT Engine” and “NXT Platform” fields with a value.
Please check that the logged-in user has the role “x_nexsa_imc.incident_remediator”.
If the remediation execution has failed and the log shows an HTTP 401 or 403 status error message related to a wrong user and password combination, it means that the authentication profile used to connect to Portal is not properly configured. The error message looks like the following:
Method failed: (/api/remoteaction/v2/run) with code: 401 - Invalid username/password combo
If this is the case, please edit the Authentication Profiles used for Portal and set the proper user and password.
Logs can also state an HTTP status code ‘0’ error message. This error arises when Portal is not reachable for some reason, such as Portal being shut down, the endpoint being erroneously configured, the DNS not being able to resolve the address, etc. The error message could look like the following:
Portal '<portal_name>' - HTTP status 0, The request failed:java.net.SocketTimeoutException: connect timed out when posting to https:///api/remoteaction/v2/run
or:
Portal '<portal_name>' - HTTP status code 0, with query 'null'. Message: null; Error Message: The request failed: Unknown host
To fix this, please make sure that Portal is up and running and configured with the correct address.
Since v2.0.0, IMC is able to launch Parametric Remote Actions. To do so, Nexthink v.29 is required, as the remote action feature of IMC v.2.0.0 cannot work with earlier versions of Nexthink. In this case, the popup won’t be shown, and the following message appears in the logs:
NexthinkIncidentManagementConnector::AbstractAjaxProcessor:getRemediationDetails : Error:
The HTTP code generated by the call to the API was 0.
To launch remediation actions, the device_uid of the Configuration Item is required. This field is retrieved within the Device Properties Score, meaning that this Score Definition must be active to perform the action. If this isn’t done, the popup will explain that the remediation could not be dispatched.
The following error is recorded in the System Logs:
NexthinkIncidentManagementConnector::RemediationAction:execute : Invalid value for the variable : device_uid
In the Agent Workspace view, the error is also shown on the screen.
Remember that the Score Definition for Device Properties must be created through the Setup Script (see Missing Score Definition for Device Properties).
This scenario has been observed in the corner case where the default Nexthink mapping fields have been replaced in the Nexthink Incident Management Connector properties and the name of the device is different in Servicenow CMDB tables and Nexthink DB.
In this case, when the remediation is launched, the request is successfully delivered to the portal, but the engine is never responding with the results of the remote action due to the CI name being unknown to the engine. Hence, the below comment is added to the work notes, but the ticket is never updated with the results:
This is a known issue that has been corrected in version 2.2.0 of the Nexthink Incident Management Connector. To avoid this issue, please, update your instance to the aforementioned version and it will be automatically resolved.
The user uploads the XML Score Definition to a new or existing Score Definition record in ServiceNow and the fields of the Score Definition are still empty. Checking the System Log, an error similar to the following may be seen:
org.mozilla.javascript.EcmaError: Cannot convert null to an object.
or:
com.ctc.wstx.exc.WstxUnexpectedCharException: Unexpected character 'r' (code 114) in prolog; expected '<'…
This issue is closely related to problems in the XML syntax. Hence, it is recommended to review the content of the XML file. It is a good idea to import the score using the Finder to ensure it works on the engine side and then use exactly the same file in the score definition record on Servicenow.
Score Definition for Device Properties cannot be created manually. It is automatically created by the Setup Script, by reading the configuration in the Device Properties table. Each time this table is updated the Score Definition is updated.
If the Discovery Engines - Devices was either a scheduled job or launched, and the status field of the Engine records does not change from IDLE/OK to PROCESSING after some time, it means that the discovery process is not happening.
If this is the case, please verify that the MID Server is properly configured and verified in the ServiceNow environment. If a MID Server is not necessary, please verify that the Engines configured in ServiceNow are up and running.
The same error may arise when a Portal MID Server is not properly configured, and remediation seems not to have been executed.
Also, please check that you have at least one table defined in the Device Tables table.
Sometimes, instead of showing the HTTP status code ‘0’ error message, the log shows the java.lang.NullPointerException. This error seems to be caused when the MID Server is not defined in the configuration for a given Engine and said Engine is not accessible. The error shown is:
java.lang.NullPointerException
To fix this, please make sure to define a proper MID Server to reach the Engine and check that it is up and running.
The same error may arise when a Portal MID Server is not properly configured, and remediation seems not to have been executed.
In Quebec, ServiceNow is more restrictive about how the MID Server deals with certificates. This means that if the connection to the Engine is done through a MID Server with a non-trusted certificate, the MID Server will not allow the communication, throwing the following error into the logs:
NexthinkIncidentManagementConnector::DataRetrieval:_processResponse : The request failed:
Request not sent to
uri= https://myURI:1671/2/query/?format=xml&hr=true&platform=windows,mac_os&query=(s elect%20(name%20last_seen%20platform)%20(from%20device)) : org.apache.commons.httpclient.HttpException: Session contains no certificates - Untrusted
For more details, refer to the official ServiceNow documentation:
If the Engines - Devices discovery process has failed and the log shows an error message similar to the following (user reported might vary):
User ‘peter.doe’ does not have proper role
Go to Scheduled Jobs > Discover Engines – Devices and configure the Run as parameter with a user holding the admin or x_nexsa_imc.manager role, and then re-execute the discovery process.
It might be necessary to modify the form layout of the scheduled jobs to be able to configure the Run as parameter (see the Configure Scheduled Job section at Nexthink Incident Management Connector – Installation and Configuration Guide).
When this message is shown at the top of the incident form, it usually means that even though the device queried had an Engine associated, said Engine does not seem to have it currently registered.
It might be necessary to re-run the Engines - Device discovery process to update the information.
Another problem will arise if the score definition has changed in Nexthink since the last time it was imported in ServiceNow. Please make sure the scores in ServiceNow are exactly the same as those defined in Nexthink.
When this message is shown at the top of the incident form, it means that the definition of the scores loaded in ServiceNow is not the same as the definition of the scores stored in Nexthink Engines.
To solve this, export the Scores files from Nexthink and import them again in ServiceNow as defined in the Installation and Configuration guide.
The user has changed the caption of a Score Definition and the change is not visible, for example, the score tab title has not changed. This happens sometimes because of the ServiceNow cache.
It is important to properly follow the steps in the Define Scores configuration section from the Installation guide, especially the third bullet point which is related to modifying the Document element in the XML file.
There are three options to solve this problem:
Reload a score definition: delete a score definition and load it again or load a new score definition.
Reload a device property: delete a device property and load it again or create a new device property.
Run the setup script: you must take into consideration that this will reset your connector to the default settings.
The user opens the Incident view and expects to see Scores for a Configuration Item, but the Score tabs do not display any information and there is no error message.
In this is the case, several actions can be taken:
Verify that there are Score Definitions created and they have Score XML definitions already imported. There should be at least one.
If the device is a Mac, check the score is available for macOS platform.
The Configuration Item for the incident must belong to one of the tables defined in the Device Tables module (or in a table inheriting from any of them), and it must have an Engine assigned.
Verify that the user has a proper role. The user must have, at least, the x_nexsa_imc.incident_viewer role. Please note that if roles were granted for a user logged on, this user should log off and log on again for changes to take effect.
Sometimes, especially after applying a patch to the ServiceNow instance, sections get “corrupted”. Navigate to System UI > Form Sections, filter by Table = Incident and Application = Nexthink Incident Management Connector, and check if the sections are duplicated there. If so, delete all the sections and recreate them. To recreate:
Delete current records on the "Score Definitions" module. Please make sure you have the XML files stored somewhere and store the names given to the tabs, if desired, because they will need to be reimported later.
Make sure "Nexthink Incident Management Connector" is selected as the current scope.
Go to the Incident form, right-click on the header and go to Configure > Form Design. Click on it and a new window will open.
There should be 11 sections belonging to the IMC. All of their names should have the prefix x_nexsa_imc_score_panel_ and it should be followed by a number (from 01 to 10), as shown in the screenshot below. Each section should have the associated formatter assigned.
Recreate the proper structure.
In order to refresh the Score Definition for the Device Properties, run the Setup Script.
Reimport the records on the "Score Definitions" module.
This scenario is similar to the above case, however, since IMC 2.0, the below error will be displayed in the incident form:
In this scenario it is required to follow the below steps:
Make sure "Nexthink Incident Management Connector" is selected as the current scope.
Go to the Incident form, right-click on the header and go to Configure > Form Design. Click on it and a new window will open.
There should be 11 sections belonging to the IMC. All of their names should have the prefix x_nexsa_imc_score_panel_ and it should be followed by a number (from 01 to 10), as shown in the screenshot below. Each section should have the associated formatter assigned.
Recreate the proper structure.
Refresh the incident form.
If the device is a Mac, check if the platform's field of the score definition is “windows mac_os” or “mac_os”. You can change the platform using the Nexthink Score Creator1. Make sure all metrics inside it are compatible with the Mac platform.
If this does not resolve the issue, refer back to the previous section for general tips, regardless of the platform.
The user opens the Incident view and expects to see Remediation panels for a Configuration Item (Device) when each Score is clicked, but no Remediation panel appears and there is no error message.
If this is the case, several actions can be taken:
Check if there are Score Definitions created and if they have Score XML definition already imported. There should be at least one. Verify that the XML imported contains a … section.
The Configuration Item for the incident must belong to one of the tables defined in the Device Tables module (or in a table inheriting from any of them) and it must have an Engine assigned.
Check if the user has a proper role. The user must have the x_nexsa_imc.incident_remediator role. Please note that if roles were granted for a user logged on, this user should log off and log on again for changes to take effect.
Also, note that the remediation panel works only for Windows devices.
The customer clicks on the Finder button (inside a Score tab) and the Finder does not open on the computer.
If this is the case, several actions can be taken:
In ServiceNow:
Check if there is a Portal defined and it is properly configured, especially the Finder Port field in the Finder tab.
On the user’s computer:
Make sure that Finder is installed and has NXT protocol associated.
When accessing the Incident form, no CI field is displayed. This is usually due to the user’s lack of the itil role.
If this is the case, several actions can be taken:
Grant the itil role to the user who experienced the issue.
If that user is logged on, they must log off and log back in to the instance.
When trying to run the process, an error message about cross-scopes appears.
To solve this, it is necessary to grant some cross-scope privileges for the tables in the Devices Tables module. Please check the Define devices tables section in the Installation and Configuration Guide.
If this error message is shown:
And in the logs, the message looks similar to the following:
NexthinkIncidentManagementConnector::DataRetrieval:_processResponse java.net.SocketTimeoutException: connect timed out when posting to...
Users should check the ACLs regarding MID Server (ecc_agent) and Authentication (sys_auth_profile). See the Roles and ACLs section in the Nexthink Incident Management Connector – Installation and Configuration Guide.
The user should check the ACLs, especially the one regarding reading cmdb_rel_person. See the Roles and ACLs section in the Nexthink Incident Management Connector – Installation and Configuration Guide.
If the triggering field value is set to a field that does not refer to cmdb_ci or one of its descendants, then an error message will appear, as shown below:
The solution is to set up the property field with a valid table.
Device Properties and Score Tabs must be shown if the user has the “imc.viewer” role and the visibility is managed by the “Score definition” records ([x_nexsa_imc_score_definition] table).
In some circumstances, and depending on the instance’s security configuration and enforcements, there may be cases in which a user with a role enabling access to the incident table default view cannot access the records in x_nexsa_imc_score_definition. This will cause the user to be impacted by a UI malfunction. In order to fix this, include an ACL in order to grant the role for reading access to the “Score Definition” table. The following template can be used as an example:
ACL
Grant Roles Access Scores from Incident
Type
record
Operation
read
Active
True
Name
Score Definition [x_nexsa_imc_score_definition]
-- None --
Description
Access Control in order to enable roles access to Score Definitions record to render the default
[incident] form
Requires role
Condition
Script
A User with the role x_nexsa_imc.disable_open_in_finder cannot see the Open in Nexthink Finder button. Please check the roles of the user.
If the Device properties and scores tab are correctly displayed on TOP or Global domain, but not displayed on the incident form for subdomains, it is likely that UI Sections have not been correctly created on the form. This would be due to overriding rules configured for the impacted subdomain.
In this case, we would need to note down the UI sections created on the global or TOP domain and re-create them on the subdomain.
For this purpose follow the procedure described below:
Go to the incident form on the global domain.
Verify that "Nexthink Incident Management Connector" is selected as the current scope.
Go to the Incident form, right-click on the header and go to Configure > Form Design. Click on it and a new window will open.
Take note of the UI sections created at the bottom of the form.
Create the same set of sections on the subdomain incident form. Pay special attention to the name of every section (the names are case sensitive and typos must be avoided) and ensure these are correctly linked to the corresponding formatter.
Click on the Save button in the top right corner.
Scores should be displayed now. In the event that the scores are still not visible, contact Nexthink Support for a deeper analysis.
It is possible that the scores are displayed in the incident form right after it is deleted, as shown in the example below:
This happens due to Service now caching the views and forms for better performance and not automatically refreshing every time a score is deleted.
If it is necessary to flush the cache immediately, follow the next procedure in order to force a cache renewal: (If this has to be done in a production instance, ensure you schedule this at the most suitable time, as performance might be affected).
To proceed with the cache flush, follow the steps shown below:
Log in as a user with an admin role.
Wait for the results to be displayed.
Navigate to the incident form and check that the tab is not displayed anymore.
If the tab is still visible and is listed in the incident form, ensure the access of the list of global ACLs attached in the section Roles and ACLs in the Nexthink Incident Management Connector - Installation and Configuration Guide are enabled in the ServiceNow instance ACL settings.
With the ServiceNow instance out-of-the-box configuration, the tabs are expected to be displayed in the incident form.
However, it is also possible that the sections are not displayed in tabs but directly in the incident form keeping the default section names instead of replacing them with the scores ones.
I.E:
To correct this behavior it is just necessary to enable the tabbed forms options in the system settings:
Click on the cogwheel located in the top-right corner
Click on the forms section in the left panel
Enable the Tabbed forms property.
It has been observed in some instances that the score tab captions are not always applied.
In other words, the tabs captions displayed are displayed as “x_nexsa_imc_score_panel_00”, “x_nexsa_imc_score_panel_01”, etc instead of displaying the score name.
I.E:
This behavior is caused due to one of the Servicenow system settings.
To avoid this scenario, click on the cogwheel on top-right corner to access the system settings. Then click on Forms and ensure the Related list loading configuration is set as “With the Form”.
I.E:
There are 3 options:
The Agent Workspace integration is not enabled: Check it in the Properties page of the Connector.
The user does not have the proper role. The user must have the x_nexsa_imc.incident_viewer role. Please note that if roles were granted for a user logged on, this user should log off and log on again for changes to take effect.
The Agent Workspace integration has been available since version 1.3.0. Please check the Connector version.
When the message “Error: No data retrieved. Please check the log for more details” is shown in the Nexthink panel, it usually means that even though the device queried had an Engine associated, said Engine does not seem to have the configuration item currently registered.
It might be necessary to re-run the Engines - Device discovery process to update the information. Another problem arises if the score definition has changed in Nexthink since the last time it was imported in ServiceNow. Please make sure the scores in ServiceNow are exactly the same as those defined in Nexthink.
This error message is shown when the property “Trigger field on the Incident form which fetches Scores” (x_nexsa_imc.trigger_field) has an invalid value or is empty. Please check this field on the Properties page of the Connector.
This message appears when the Display Nexthink panel button is pressed, but the Configuration Item field is empty. Close the message, fill in the Configuration Item and press the button again.
This happens when the Configuration Item is not found in Nexthink. Review the Configuration Item. If the Configuration Item has recently been added in Nexthink, it might be necessary to re-run the Engines - Device discovery process to update its information in the Connector.
This issue is often related to the upgrade procedure to version v1.3.0.
In this scenario, we recommend removing and creating the scores, as explained in the section “Nexthink Incident Management Connector” considerations in the Nexthink Incident Management Connector installation and configuration guide.
Processors are a mechanism to make ServiceNow trigger operations by using an HTTP request.
In order to maintain the maximum level of instance security, the nexthink_create_incident processor is deployed with the CSRF flag enabled, making it necessary to manage this flag before using this processor.
If the Engine discovery failed, the values for the status column in the Engine list are set to ERROR or PROCESSING_ERROR and in the system logs a message similar to the following will appear:
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
This error happens when Engines are not configured to use a MID Server to retrieve the data and the Engine does not have a valid SSL certificate. In such a case, please modify the system property named com.glide.communications.trustmanager_trust_all as it should be set to the true value.
If the Engine discovery failed, the values for the status column in the Engine list are set to ERROR or PROCESSING_ERROR and in the system logs a message similar to the following will appear:
javax.net.ssl.SSLPeerUnverifiedException: peer not authenticated
This error occurs when Engines are not configured to use a MID Server to retrieve the data and the Engine does not have a valid SSL certificate (e.g., self-signed). In this case, set the system property named com.glide.communications.httpclient.verify_hostname to false. This is not recommended for production environments. Modify this value only if you are aware of its implications
ServiceNow application management behaves in the same way as general ServiceNow upgrades, abiding by the following rule:
As soon as any out-of-the-box script or object is modified by the customer, it will opt-out of the next upgrade, being added to the “Skipped Changes to Review” list in the “Upgrade History Record”
For this reason, it is advised to follow ServiceNow Upgrade Guidelines, review the Upgrade History Record, review the skipped changes, and resolve each case (if any).
In order to review the status of an upgrade, follow the instructions below:
Go to the System Diagnostic -> Upgrade History module.
Locate the record pointing to Nexthink’s upgraded application and get into the register.
A tab named “Skipped Changes to Review” will appear with all the record updates that have not been applied due to local customization.
At this point, solve each conflict individually by following ServiceNow Upgrade Guidelines and admin criteria.
Be aware that Nexthink will only ensure the proper functionalities for OOB deployments. Any customization will be under the customer’s responsibility.
When executing the NXT-Delete UI Sections & Update Scores Fix Script, if the result log contains the following message:
Delete permissions must be given on the sys_ui_section. Follow the steps below to grant the permission:
As an admin user on the Global domain, navigate to sys_db_object.list.
Search by Name for the sys_ui_section table and access the Form Section record.
Click on the Application Access tab and check the Delete box.
Click on Update to save the changes.
Sometimes the self-service portal widget does not display the results of the last leaf score when informative banners are visible on the screen.
A demo of the error can be found below:
Banner displayed:
Widget:
As shown above, the last leaf score result is empty. This misbehavior can be fixed by following the next steps:
Close the banner by clicking on the X mark in the top-right corner.
Refresh the web page.
At this point, the widget should work as expected as the banner is not causing any more trouble to the application design. In the event the incident is still ongoing, contact support for a deeper analysis. It is important to provide as much detail as possible in order to resolve the issue.
Starting from version 2.4, an entry is inserted in table sys_journal_field after executing remediations from Service Portal towards the fix it button.
Therefore, in case this table does not allow the read, create and update accesses for all application scopes, the below errors will be displayed in the user interface:
I.E:
If the error messages are still displayed even though the application access checkboxes are active, the instance cache might not have been updated with the cross-scope rules.
Please, execute the below script in the 'Scripts - Background' module to clear the instance cache:
For further reference about this issue, please feel free to read the below ServiceNow KB article:
To solve this problem, the recommendation is to Import a self-signed certificate to MID Server JRE cacerts. ().
To solve this issue, please type “ ” in the Filter navigator input text box and hit the Enter key. This action will clean up the cache and the new caption will be visible in the Incident view.
Make sure all device properties have the proper platform defined. You can check each property in the .
Type “ ” in the filter navigator and press enter.
Should there be any further queries or if this scenario has not been resolved by applying the fix described above, please contact .
For this reason, ServiceNow puts in place a CSRF mechanism in order to disallow/allow requests from a domain different from “ ” without a token as a security feature. This question is described in the ServiceNow Docs and discussed in the Community.
Pay special attention to .
To resolve this issue is just necessary to set the application access permissions as displayed in the section of the
