Installation and configuration guide (IMC)
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
Introduction
This guide aims to provide comprehensive information on how to install and configure the Nexthink ServiceNow IMC integration, as well as basic maintenance guides. This document provides a detailed description of the processes needed for a successful installation.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please contact Nexthink Support for more information.
This document is intended for readers with a detailed understanding of both Nexthink technology and ServiceNow technology, as well as some understanding of concepts such as REST messages, business rules, scripting and some basic security terms.
Revision history
Date | History |
---|---|
2022-09-05 | New version: v2.4 · Roles and ACLs section updated · Service Portal Widget information steps updated · New property to activate discovery process optimization for large CMDB |
2022-03-08 | New version: v2.3 · Device Properties list updated · Remote Action custom fields retrieved after successful remediation execution · Oauth Entity scopes updated · “Navigating in Nexthink Incident Management Connector” section updated with the new Remote Action workflow |
2021-11-23 | New version: v2.2.0 · Multi portal support · Non-parametric Remote Actions executed without displaying the modal window with parameters · Global ACLs list updated. Service Portal viewer added |
2021-03-02 | Added: · Fix scripts to upgrade to version 2.0.0 · Roles to execute the scheduled job properly · Self-Service Portal Widget |
2020-12-11 | New version: v2.0.0 · IMC can launch the new parametric remote actions. · The number of custom tables has been reduced. · Improved architecture has been improved. |
2020-11-11 | Rules for UI section, UI macros and UI formatters deleted from Global ACLs in Roles and ACLs |
2020-08-21 | Added new information regarding OAuthV2 configuration |
2020-08-17 | Updated Global ACLs for OAuthV2 authentication in Roles and ACLs |
2020-05-26 | · Section 9.2 "Nexthink Incident Management Connector” considerations updated for v1.3.0 · Section 7.2 Navigating in the Agent Workspace updated. · Section 6.11 Enable creation of Scores snapshots updated · Added note in Revision history section |
2020-05-06 | Version added to the ServiceNow store, v1.3.0 · Integration with Agent Workspace: New Nexthink panel, which is feature parity with the Incident Form View · New role to disable “Open in Finder” |
2020-02-20 | Updated Global ACLs for Agent Workspace in Roles and ACLs |
2020-02-17 | Fixed typos and formatting Added section 6.12 “Snapshots format” |
2020-01-17 | Section “Upgrade Considerations” visited in order to resolve conflicts |
2019-12-30 | New ServiceNow store version 1.2.1 · Added Mac devices support · Added snapshots creation in text format · Added Cloud deployments configuration |
2019-10-10 | New ServiceNow store v1.1.2 · Added snapshot creation support in Work Notes |
Refer to the Nexthink ServiceNow CMDB Connectors documentation to see the ServiceNow Incident Management connector versions supported by Nexthink.
Overview
Nexthink Incident Management Connector for ServiceNow offers Nexthink customers the ability to integrate end-user IT data into the ServiceNow platform to increase the visibility of IT support teams during Incident Management operations.
With this application, ServiceNow users will be able to:
Get real-time data about endpoint health using customized Nexthink Scores when opening or checking incidents.
Save snapshots of Nexthink Scores in the Work Notes for future reference.
Leverage all the power of Nexthink ACT to fix endpoint problems remotely.
Nexthink Scores can be loaded into the ServiceNow application in the form of an XML file. This XML file can be generated by using the Scores Export option available in Finder. Apart from the Scores, the XML to be loaded into the ServiceNow application may have defined remediation actions associated with some features.
For the Nexthink Scores data retrieval to be possible, the application provides a discovery tool that can be executed on-demand or periodically. This discovery tool checks which devices belong to which Engines inside the configured Nexthink environment and keeps that information stored in a database for future queries using Nexthink Web API 2.0.
Nexthink requirements
Nexthink Incident Management Connector integration requires a running implementation of the Nexthink product.
The following are the pre-requisites:
An appliance with Nexthink version 6.12.2 or later
Integrate license to use the Web API
To use Remediations:
Act license
Nexthink version 6.29 or higher (for parametric remote actions)
Finder access to export Nexthink Scores XML definitions that will be imported into the ServiceNow application.
In addition, if OAuth V2 is required for Engines and/or Portal authentication, ensure the OAuth V2 configuration requirements explained in sections Register Portals and Register Engines are met.
Apart from this, please, note that the Nexthink scores will only be displayed in the default view of the incident table form.
Main ServiceNow Components
The main components of this integration in ServiceNow are described in the next sections.
Custom Table Inventory
The application creates 5 custom tables. A detailed description of each table is explained below.
All of them should be allocated to the entitlements of the instance subscription. You can have more information about custom table allocations in the ServiceNow Product Documentation.
Score Definitions
The table x_nexsa_imc_score_definition contains the different Score groups that will be visualized when checking an incident, including a special score to render the Device Properties. The only fields which can be manually modified by users are Name, Caption, Active, and Display in Service Portal. The rest are internally modified by the application when attaching the XML Scores configuration file associated with it.
By default, the application comes with no Score Definitions defined. After running the Setup Script, the Score Definition for the Device Properties will be automatically created (see Execute setups). The platform of a Score Definition can be windows, mac_os, or both. This is detected automatically when loading the score.
Device Properties
Along with the Scores, a group of standard device fields can be configured to be displayed when checking incidents. The table x_nexsa_imc_score_header allows users to define which Nexthink device table fields will be imported into the Incident form.
For each device property to be specified, this table defines the corresponding field in the Nexthink device table (including custom fields), the caption to display on the Incident form, and the order in the list. Table columns are shown in the next impression.
By default, IMC comes with a set of 13 device properties (see above screenshot Device Properties table). This table is populated by using the application Setup Script, as will be explained in the following sections. Some properties are specific to Windows devices. For a full reference, check the Nexthink NXQL data model for the device table.
Device Tables
Within the table x_nexsa_imc_device_table, the CMDB tables that contain the devices that will be taken into consideration for the retrieval of the data are recorded.
The property x_nexsa_imc.allow_extending_device_tables controls which devices will launch the data retrieval process in the Incident form: either only those stored directly in the tables included in this module (property set to false) or both the aforementioned devices, as well as those stored in tables inheriting from/extending the tables included (property set to true).
For instance, if the Computer table (cmdb_ci_computer) is included in this module, and the property is set to false, only devices in the Computer table will trigger the process in the Incident form. However, if the property is set to true, devices belonging to the table Personal Computer (cmdb_ci_pc_hardware), which inherits from Computer, or devices belonging to other extending tables will also trigger the data retrieval process.
The columns of the table are shown in the following screenshot (Device Tables table). This table contains only two fields: a reference to the dictionary of tables table (sys_db_object) and a string field that stores the internal name of the table.
By default, the application comes with the Computer (cmdb_ci_computer) table defined and the property set to true.
Score Query
The table x_nexsa_imc_score_query is used as a cache for the necessary NXQL query to retrieve the Scores information to be displayed on the Incident form. It will contain just two records (one for a Windows & Mac properties query, another for only a Windows properties query).
This section is not modifiable by users (see Figure Score Query table below). Every time a Score Definition or Device Property is modified, this record will be automatically updated by the application.
By default, this table will contain an empty query since no device properties or Scores come pre-loaded.
Endpoints
The table x_nexsa_imc_endpoint contains all the configurations to connect to both Nexthink Engines and Portals. To facilitate the configuration, the Application provides 2 modules (views) for this table:
Portals
This view of the table x_nexsa_imc_endpoint allows users to configure which Portals will provide the Remediation API endpoints for the Incident form. The different fields to be filled in are shown in the following screenshot Fields for the Portal table.
A Portal is used to launch remote actions and to connect to Nexthink Finder. Please, note that the Authentication fields change depending on the Authentication type selected, which can be Basic or OAuth 2.0.
The Remediation Port field can be left empty when an out-of-the-box configuration is in place. By default, the Remote Actions API is listening on port 443, so this is the port the connector uses to send remediation requests to the portal. If the port has been customized on the Portal side and the Remote Action API is listening to a different port, it must be specified in the form.
Another consideration is that the MID Server field is not mandatory when defining a new portal with “Basic” authentication type. Only those portals located inside an intranet or those that are not accessible from the Internet would need it.
If necessary, please follow your proxy instructions or ServiceNow instructions on how to set up a MID Server.
Note: Users from the previous version of the Connector likely remember the Finder Connection table. To simplify the configuration, this table does not exist anymore. To configure the Finder Connection to a Nexthink Portal, please configure the port in the Finder tab.
Please, note that since version 2.2.0, it is possible to create more than one portal, unlike in previous versions where only a portal is allowed to be created and is set as the default portal.
This is no longer necessary. In case that more than one portal is created, the remote action requests are executed to the portal that is linked to the engine where the CI is mapped to.
Engines
This view lets users configure which Engines will provide the Scores information for the Incident form. The different fields to be filled in are shown in the screenshot Fields for Engine (Endpoint table) displayed below. It is possible to define as many Engines as necessary.
With the Portal field, it is possible to relate any Engine to a specific portal. This field is mandatory, therefore, please ensure a portal is available before creating a new engine.
Please note that the Authentication fields will change depending on the Authentication type selected: Basic or OAuth 2.0.
MID Server observations made in the previous section (Portals) apply to this case as well.
Additionally, for those using Nexthink in a Cloud environment, and WEB API V2.0 service listening on a different port other than 443, it is mandatory to declare the port in the field “port” of the new Engine form. If the default port is not customized, the field should remain empty. In this case, it is not necessary to install a MID Server because the Engine will be reachable over the internet. The figure Engine cloud configuration example shows an example of the configuration for this scenario.
New fields
For normal operation of the integration, the addition of 3 new fields to one of the ServiceNow tables is required, as shown in Table 1.
ServiceNow table | Field added |
---|---|
cmdb_ci | x_nexsa_imc_nxt_engine |
cmdb_ci | x_nexsa_imc_nxt_platform |
cmdb_ci | x_nexsa_imc_nxt_last_seen |
ServiceNow table modified and new field added
Please note that this is the default base table, predefined in the integration, where endpoint information is stored. Please remember that all tables used to store devices in ServiceNow must be contained or inherited from those configured in Devices Tables, as mentioned in previous sections.
Business rules
To reduce the possibility of making mistakes during the initial configuration or during normal operation, several business rules have been defined. These business rules monitor that conditions such as the following, among others, are met:
Only one Device Properties Score Definition is created.
The Score Query content is reloaded after modifying a Score Definition.
The number of Device Properties is not greater than the limit (20, by default).
A Device Property cannot be left blank if it is not a custom field.
The Score Query content is reloaded after modifying a Device Property.
Score Query cannot be deleted.
The number of Score Queries is not greater than two.
No more than one attachment for every Score Definition can be uploaded_._
The Score Definition field is updated after modifying a Score Definition.
Device Tables must inherit from cmdb_ci.
There is a minimum of one Device Table record.
Validate the enable remediation property.
Validate the REST timeout property.
No Portal deletion if an engine is linked
Setup scripts
The script under this module performs the default configuration, loading the default records in the tables Device Properties and Device Tables. The Score Definition to show the Device Properties is also created with this script.
Client script
The script under this module allows loading the necessary UI Scripts to display Nexthink Data in the incident form. This has a limitation and unfortunately, the application will only display the Nexthink scores in the default view of the incident form.
Roles and ACLs
Nexthink Incident Management Connector integration creates 6 new roles to manage the application:
Role | Description |
---|---|
x_nexsa_imc.manager | This role is intended for general application configuration. |
x_nexsa_imc.incident_viewer | This role allows users to access the Incident form and check endpoint Scores |
x_nexsa_imc.incident_remediator | In addition to the incident_view role capabilities, this role allows users to execute remote remediation actions through the remediation panel on the Scores view. In case of parametric remote action it will be executed with the default values |
x_nexsa_imc.advance_remediator | In addition to the incident_view role capabilities, this role allows users to execute remote remediation actions through the remediation panel on the Scores view. In case of parametric remote action a modal window will be displayed to customize the input parameters. |
x_nexsa_imc.disable_open_in_finder | This role will disable the Open in Finder button. |
x_nexsa_imc.service_portal_viewer | This role is necessary to be able to see the self-service portal widget. |
Please note that only users with the admin role can modify the definition or code of the business rules, scripts and any other ServiceNow artefacts.
Additionally, remember the itil** role** is necessary for any user dealing with CIs on the Incident form.
x_nexsa_imc.manager role does NOT include the x_nexsa_imc.incident_viewer, x_nexsa_imc.advance_remediator or x_nexsa_imc.incident_remediator role_._
ServiceNow administrators will NOT be able to test the application without explicitly being given the required x_nexsa_imc roles.
The roles permissions are summarized in Table 2: Roles description.
Section | admin | x_nexsa_imc.manager | x_nexsa_imc.viewer | x_nexsa_imc.remediator | x_nexsa_imc.advance_remediator | x_nexsa_imc.disable_open_in_finder | x_nexsa_imc.service_portal_viewer |
---|---|---|---|---|---|---|
Execute scheduled jobs | X | |||||
Manage business rules | X | |||||
Manage score definitions | X | X | ||||
Manage device properties | X | X | ||||
Manage device tables | X | X | ||||
Manage score query | ||||||
Manage portal endpoints | X | X | ||||
Manage engine endpoints | X | X | ||||
Manage properties | X | X | ||||
Execute setup scripts | X | |||||
Execute remote actions | X | |||||
Execute remote actions in agent workspace | X | |||||
View score tabs | X | |||||
View score tabs in agent workspace | X | |||||
Create scores snapshots | X | |||||
Create scores snapshots in agent workspace | X | |||||
Hide open in finder button | X | |||||
Hide open in finder button in agent workspace | X | |||||
See the self-service portal widget | X |
Roles description
Note: ACLs control the information displayed on ServiceNow. Please note that it may be necessary to modify some ACL rules based on your ServiceNow configuration to include the required IMC roles. If this is not done, some system tables and their associated records cannot be shown when performing the initial setup or the scores tab may not appear in the incident form.
Note: The user that will run the scheduled job (indicated in the field run as) must have the necessary permissions to read the following tables:
ecc_agent
sys_auth_profile
cmdb_ci
sys_db_object
oauth_entity_profile
For more information about this, see the section Configure Scheduled Job.
Note: The self-service portal widget user must have the necessary permissions to read the following tables:
sys_auth_profile
oauth_entity_profile
cmdb_ci
ecc_agent
sys_db_object
Apart from this, it is also required to provide access to write and create records in the sys_journal_field table.
For more information about this, see Install Service Portal Widget.
The Global ACLs required to be added for the Incident Management Connector are described in Table 3: List of ACLs to be enabled.
Type | Operation | Target name | Field | Role | Condition |
---|---|---|---|---|---|
Record | Read | ecc_agent | None | x_nexsa_imc.manager x_nexsa_imc. incident_remediator x_nexsa_imc.advance_remediator x_nexsa_imc. incident_viewer x_nexsa_imc.service_portal_viewer | |
Record | Read | ecc_agent | * | x_nexsa_imc.manager x_nexsa_imc. incident_remediator x_nexsa_imc.advance_remediator x_nexsa_imc. incident_viewer x_nexsa_imc.service_portal_viewer | |
Record | Read | sys_auth_profile | None | x_nexsa_imc.manager x_nexsa_imc.incident_remediator x_nexsa_imc.advance_remediator x_nexsa_imc. incident_viewer x_nexsa_imc. x_nexsa_imc.service_portal_viewer | |
Record | Read | cmdb_rel_person | None | x_nexsa_imc.manager x_nexsa_imc.incident_viewer | |
Record | Read | sys_scope | None | x_nexsa_imc.manager | |
Record | Read | sys_scope | * | x_nexsa_imc.manager | |
Record | Read | sys_app | None | x_nexsa_imc.manager | Name = Nexthink Incident Management Connector |
Record | Read | sys_store_app | None | x_nexsa_imc.manager | Name = Nexthink Incident Management Connector |
Record | Read | oauth_entity_pr ofile | None | x_nexsa_imc.manager x_nexsa_imc.incident_viewer x_nexsa_imc.service_portal_viewer | |
Record | Read | oauth_entity_pr ofile | * | x_nexsa_imc.manager x_nexsa_imc.incident_viewer x_nexsa_imc.service_portal_viewer | |
Record | Read | cmdb_ci | None | x_nexsa_imc. service_portal_viewer | |
Record | Read | sys_db_object | None | x_nexsa_imc. service_portal_viewer | |
Record | Read | sys_db_object | * | x_nexsa_imc. service_portal_viewer | |
Record | Create | sys_journal_field | None | x_nexsa_imc. service_portal_viewer | |
Record | Write | sys_journal_field | None | x_nexsa_imc. service_portal_viewer |
List of ACLs to be enabled
Apart from this, for further details, included in the application, the below ACLs are added to the sys_security_acl table:
Type | Operation | Target name | Field | Role |
---|---|---|---|---|
client_callable_script_include | Execute | AWPanelAJAXUtilites | N/A | x_nexsa_imc.incident_viewer |
Record | Write | cmdb_ci | x_nexsa_imc_nxt_engine | x_nexsa_imc.manager |
Record | Write | cmdb_ci | x_nexsa_imc_nxt_platform | x_nexsa_imc.manager |
ui_page | Read | finder_error | N/A | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator |
client_callable_script_include | Execute | IncidentScoresRefresher | N/A | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator |
client_callable_script_include | Execute | NexthinkIncidentWriterGA | N/A | x_nexsa_imc.incident_viewer |
client_callable_script_include | Execute | NexthinkUserInteractionsScoreGA | N/A | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator |
ui_page | Read | nexthink_contact_support | N/A | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager |
Processor | Execute | nexthink_create_incident | N/A | itil |
client_callable_script_include | Execute | RelatedDevicesPopulator | N/A | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator |
client_callable_script_include | Execute | RemediationExecutorGA | N/A | x_nexsa_imc.incident_remediator |
UI Page | Read | remediation_error | N/A | nexsa_imc.incident_remediator |
UI Page | Read | remediation_ok | N/A | nexsa_imc.incident_remediator |
Record | Read | x_nexsa_imc_device_table | N/A | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager |
Record | Create Write Delete | x_nexsa_imc_device_table | N/A | x_nexsa_imc.manager |
Record | Read | x_nexsa_imc_device_table | internal_name | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager itil |
Record | Read | x_nexsa_imc_endpoint | N/A | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager x_nexsa_imc.service_portal_viewer |
Record | Create Write Delete | x_nexsa_imc_endpoint | N/A | x_nexsa_imc.manager |
Record | Read | x_nexsa_imc_endpoint | * | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager x_nexsa_imc.service_portal_viewer |
Record | Create Write Delete | x_nexsa_imc_endpoint | * | x_nexsa_imc.manager |
Record | Write | x_nexsa_imc_endpoint | count_views_serviceportal_widget | x_nexsa_imc.service_portal_viewer |
Record | Write | x_nexsa_imc_endpoint | data_loads_agent_workspace_counter | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager |
Record | Write | x_nexsa_imc_endpoint | data_loads_incident_do_counter | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager |
Record | Write | x_nexsa_imc_endpoint | user_interactions_agent_workspace_counter | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager |
Record | Write | x_nexsa_imc_endpoint | user_interactions_incident_do_counter | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager |
UI Page | Read | x_nexsa_imc_finder_error | N/A | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator |
UI Page | Read | x_nexsa_imc_NexthinkAWPanel | N/A | x_nexsa_imc.incident_viewer |
UI Page | Read | x_nexsa_imc_nexthink_contact_support | N/A | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager |
UI Page | Read | x_nexsa_imc_NXTRemediationParams | N/A | x_nexsa_imc.incident_remediator |
UI Page | Read | x_nexsa_imc_remediation_error | N/A | x_nexsa_imc.incident_remediator |
UI Page | Read | x_nexsa_imc_remediation_ok | N/A | x_nexsa_imc.incident_remediator |
Record | Read | x_nexsa_imc_score_definition | N/A | x_nexsa_imc.incident_viewer x_nexsa_imc.incident_remediator x_nexsa_imc.manager Itil |
Record | Write Create Delete | x_nexsa_imc_score_definition | N/A | x_nexsa_imc.manager |
Record | list_edit | x_nexsa_imc_score_definition | is_device_properties | N/A |
Record | add_to_list | x_nexsa_imc_score_definition | template | admin |
Record | list_edit | x_nexsa_imc_score_definition | template | admin |
Record | Write Create Delete | x_nexsa_imc_score_header | N/A | x_nexsa_imc.manager |
Record | Read | x_nexsa_imc_score_header | N/A | x_nexsa_imc.manager x_nexsa_imc.incident_viewer |
Record | Read | x_nexsa_imc_score_query | N/A | x_nexsa_imc.manager |
Record | Write Create Delete | x_nexsa_imc_score_query | N/A | x_nexsa_imc.manager x_nexsa_imc.incident_viewer x_nexsa_imc.service_portal_viewer |
List of ACLs included in the application
Properties
The set of system properties created by the integration are shown in Table 4: System properties created by the integration.
Name | Type | Default value | Description |
---|---|---|---|
x_nexsa_imc.max_device_properties_fields | Integer | 20 | Sets the maximum number of device properties field to be configured |
x_nexsa_imc.glide.script.block.client.globals | true | false | false | Set the use of DOM to access elements in the Nexthink section of the Incident form. Please do not change the value of this property to true (it MUST be false). |
x_nexsa_imc.rest_timeout | Integer | 60 | Timeout in seconds for HTTP responses when using REST messages with Nexthink Web API 2.0 |
x_nexsa_imc.enable_remediation | true | false | false | Enables use of remediation actions (only for Windows devices) |
x_nexsa_imc.allow_extending_device_tables | true | false | true | Allows tables extending those included in the "Device Tables" module to trigger the scores retrieval process |
x_nexsa_imc.snow_mapping_field | string | name | Field in ServiceNow CI table where the corresponding Nexthink field is mapped |
x_nexsa_imc.nxt_mapping_field | string | name | Field in Nexthink device table to be mapped to the corresponding ServiceNow field |
x_nexsa_imc.nxt_mapping_field_type | string | string | Type of Nexthink device table field |
x_nexsa_imc.snapshot_on_creation | true | false | false | Adds status score info in the incident work note when it is created |
x_nexsa_imc.snapshot_on_demand | true | false | false | Adds a button to store status scores in the incident work note |
x_nexsa_imc.trigger_field | string | cmdb_ci | Triggers field on Incident form which fetches Scores |
x_nexsa_imc.enable_agent_workspace | true | false | true | Enables Agent Workspace integration |
x_nexsa_imc.discovery_large_cmdb | true | false | false | Enables discovery manager optimization for large CMDBs |
x_nexsa_imc.enable_support_telemetry | true | false | true | Enables Support Telemetry program |
x_nexsa_imc.workflow_time_slices | string | Default timer slices | Specifies the frequency to query the Nexthink database to find out if a remote action has been executed. |
x_nexsa_imc.plain_text | x_nexsa_imc.plain_text | N/A | (Not included by default, it has to be manually created) In case is set as true, the snapshots will be created as a plain text comment in the incident worknotes. |
System properties created by the integration
Scheduled Job
A Scheduled Job is included with Nexthink Incident Management Connector to run the device-Engine mapping discovery process. It is necessary to set the mapping so that connection information is available for every device when retrieving Scores in the Incident form.
Processor
The processor exposes a custom URL endpoint to open a new ServiceNow Incident. This processor is called from a Nexthink Custom Action, where the CI is passed as a parameter to the processor.
Service Portal Widget
In release 2.0.0, a service portal widget has been included. This widget, called NXT-Self Service Portal Score, allows the employee to observe, through certain metrics, the status of some components of their device. If a leaf score can be improved, help links will be displayed, or remote actions can be triggered that can help improve these metrics, and therefore, the overall digital experience. This widget has an educational function with the objective of generating good employee practices, in order to improve the digital experience of the company. To install the widget in the Service Portal, see Configure Service Portal Widget.
Nexthink Components
The integration also provides a way to open ServiceNow Incidents from a Nexthink Custom Action. Therefore, for this part of the integration to work properly, it is also necessary to install this Custom Action.
Custom Action to create tickets from the Finder
An XML file with the Custom Action is provided by the integration. Please refer to the Configure Custom Action to create Incidents from the Finder section to properly set the Custom Action.
Please note that, for a ticket to be properly opened in ServiceNow, the user currently logged-in to ServiceNow (or the one used for the login) must include the ITIL role.
For security reasons, the processor that creates the ticket through the custom action is protected against CSRF attacks by default. A detailed explanation of what must be done is on the next page.
If this feature is required, it is necessary to deactivate the CSRF protect checkbox under System Definition > Processors > nexthink_create_incident file.
Initial Configuration
Once the application has been installed, an initial configuration is necessary. Please follow the next steps in ServiceNow, in the given order, to achieve a successful configuration. To carry out this process the user must have the manager or admin roles assigned.
Assign appropriate roles to users
First, a general permission policy for all the users accessing the application must be established. For this, the appropriate application roles must be assigned to each user according to how the application will be utilized (see Roles and ACLs).
If the user assigned with roles is currently online, it is necessary to log off and log in again for the changes to take effect.
Configure Nexthink–ServiceNow Mapping
By default, the integration provides a “name–name” mapping, meaning that the Nexthink device name must match the ServiceNow CI name for the integration to work properly. However, this mapping can be modified according to specific needs. Once the field, both in Nexthink and Service now, has been chosen to provide the unique mapping, modifications can be made in the Properties module.
Please be sure the Nexthink field selected for the mapping is unique per device, otherwise, this could lead to inconsistencies.
For a complete list of available Nexthink fields and types, check the device table on the Nexthink NXQL data model.
Configure authentication profiles
Before going on to the next step, it is necessary to configure authentication profiles to be used by the application when interacting with Nexthink. Since the introduction of the Incident Management Connector v1.4.0, it is possible to configure the connection towards the Engines and Portal using Basic or OAuth V2 authentication types.
These credentials are intended for:
Engines Web API 2.0: To extract data from the engines. See Introducing The Web API V2 for more details.
Portal Remediation API: To execute remote actions. Details in Triggering Remote Actions Via Their API.
Depending on which authentication type we choose to connect, there are two different procedures to follow.
Basic
A new entry must be created in the sys_auth_profile_basic completing the fields as shown below:
ServiceNow field | Value |
---|---|
Name | Name to identify the Authentication type |
Username | Identifier of a Nexthink user with access to WEB API v2. |
Password | Password of the user. |
OAuthV2
A new application registry in table oauth_entity must be created, as well as two Entity profiles in oauth_entity_profile and two entity scopes in oauth_entity_scope. These must be related accordingly. In order to complete this configuration, the steps listed below must be completed.
Create the application registry
a. Search "oauth_entity.list" in the Filter navigator.
b. Click on "new."
c. Select "Connect to an OAuth Provider (simplified)."
d. Use the parameters below to fulfill the form:
ServiceNow field | Value |
---|---|
Name | Name to identify the application registry |
Client ID | Servicenow uses the client ID in combination with the client secret below to get an access token from the OAuth service provider. |
Client Secret | The client secret that will provide the user with access to the appliance when it is used in combination with the Client ID. |
Token URL: | The token provider that allows connections to your appliance via OAuth V2. For example: “https://token.provider.example.com/oauth2/token” |
Default Grant Type | Client Credentials |
Create the OAuth Entity Profiles
a. Go to the "OAuth Entity Profiles" tab and create two new rows fulfilling the following fields:
ServiceNow field | Value |
---|---|
Name | Name to identify the OAuth Entity Profile |
Grant type | Select Client Credentials |
*Please, note that each entity profile will be linked to an OAuth Entity scope to connect to the Nexthink appliance, therefore, using names referencing the Engine and the portal connections is recommended.
b. Go to the “OAuth Entity Scopes” tab and create the following scopes:
i. NXQL service scope:
ServiceNow field | Value |
---|---|
Name | Name to identify the OAuth Entity scope |
OAuth scope | service:nxql |
ii. Remote Action service scope:
ServiceNow field | Value |
---|---|
Name | Name to identify the OAuth Entity scope |
OAuth scope | service:remoteaction |
iii. Telemetry service scope:
ServiceNow field | Value |
---|---|
Name | Name to identify the OAuth Entity scope |
OAuth scope | service:telemetry |
c. Link the scopes to the profiles.
Go to the "OAuth Entity Profiles" tab and click on the name of the profile created to connect to the engine. Add a new row on the “OAuth Entity Profile Scopes” and select the Scope created for the NXQL connection.
Repeat this step with the Portal Entity profile, but link this one to the Remote Action service scope.
Register Portals
Add the Nexthink Portal used for remote remediation action execution. Since v2.2 it is possible to add as many portals as necessary. For this, it will be necessary to:
Click on the
Portals module.
Click on the
New button and fill in the form.
The Portal form works the same way as the Engine form. If the authentication profile is updated, the form will display different fields. The next table shows how to fill in this form when using Basic authentication type.
ServiceNow field | Tab | Value |
---|---|---|
Name | ||
URI | ||
Active | true/false (true by default) | |
Remediation Port | (leave blank for the default, which is 443) or set it to the custom port for customized instances. | |
Authentication type | Authentication | 2 options: Basic or OAuth 2.0 |
Auth Profile | Authentication | (authentication profile with proper credentials, see sections above) |
MID Server | Authentication | (only if necessary) |
Finder Port | Finder | (usually 443) |
Endpoint table fields to be populated for creating a portal with Basic Authentication profile.
On the other hand, if the authentication type “OAuth 2.0” is selected the following fields will be displayed.
ServiceNow field | Tab | Value |
---|---|---|
Name | ||
URI | ||
Active | true/false (true by default) | |
Remediation Port | (leave blank for the default, which is 443) or set it to the custom port for customized instances. | |
Authentication type | Authentication | 2 options: Basic or OAuth 2.0 |
OAuth Profile | Authentication | (OAuth entity Profile for the portal, see section above 6.3.2.a) |
OAuth Requestor profile | Authentication | (Must be fulfilled with a user with role oauth_admin) |
Finder Port | (usually 443) | |
Finder URI (without protocol) | DNS or IP of the Portal. It will be used to setup the “Open in Finder” button, only if the portal is referenced by the Finder Connection |
Endpoint table fields to be populated for creating a portal with OAuth 2.0 Authentication profile.
Click on the
Submit button to save that Portal.
Repeat this process if further portals are required for your integration.
Register Engines
Add the Nexthink Engines from where the data will be retrieved. For this, it will be necessary to:
Click on the Engines module.
Click on the button and fill in the form.
The next table shows how to fill in this form:
ServiceNow field | Tab | Value |
---|---|---|
Name | (same as in Engine configuration in Portal) | |
URI (without protocol) | ||
Active | true/false (true by default) | |
Portal | Link to the Nexthink portal related to this Engine. | |
Port | (usually 1671 for on-premise environments, 443 for cloud environments) | |
Authentication type | Authentication | 2 options: Basic or OAuth 2.0, as explained below |
Status | Engine Properties | Idle |
Connection | Engine Properties | Disconnected |
Endpoint table fields to be populated for creating an engine.
By default, the form will display the Authentication type “Basic.” Therefore, the two following fields will be displayed as well:
ServiceNow field | Value |
---|---|
Auth Profile | (authentication profile with proper credentials, see previous section) |
MID Server | (only if necessary) |
Endpoint table fields to be populated for creating an engine with Basic Authentication type.
However, if we modify the Authentication type and we set the value “OAuth 2.0”, the form will be updated. The fields in the table above will disappear and two new fields will be displayed.
ServiceNow field | Value |
---|---|
OAuth Profile | (OAuth entity Profile for the engine, see above section – step 2.a) |
OAuth Requestor profile | (Must be fulfilled with a user with role oauth_admin) |
Endpoint table fields to be populated for creating an engine with OAuth 2.0 Authentication type.
At this point, is also important to note that in the event that “OAuth 2.0” is set as the authentication type, the field URI (without protocol) must be completed with the URI of the API gateway that is used to send requests to the corresponding engine.
For example, in the following case, to configure engine 1, we must populate the URI field with the string “api.gateway.example.com/nxql/engine-1/”. Given the configuration, the API gateway will route the requests to the correct engine.
Click on the
Submit button to save the Engine.
Please repeat this process to add as many Engines as necessary. Note that the application is multi-engine, making it possible to retrieve and process data from several Nexthink Engines at the same time.
Configure Scheduled Job
Below are the steps to configure the user who will run the Scheduled Job in charge of the device-Engine mapping.
Click on the
Scheduled Jobs module to display the application scheduled job named Discover Engines – Devices.
Click on the
Discover Engines – Devices record on the list.
If the
Run as attribute is not shown on the form:
a. Open layout configuration. Right-click on the gray header and browse Form Layout.
b. If not in the Global application, select Edit this section in Global.
c. Select the Run as field to be shown on the form and click the add button.
d. Save the selection.
e. Back in the Scheduled Job form, pick the user who will be running it. Note that this user must perform the following operations:
Read the tables: sys_db_object, sys_auth_profile and ecc_agent apart from the tables of the connector.
Write the fields x_nexsa_imc_nxt_engine and x_nexsa_imc_nxt_platform of the table cmdb_ci apart from the tables of the connector.
Decrypt passwords to take the password from the sys_auth_profile table and communicate with the API.
The recommendation, if this user cannot be an admin user, is to utilize a user with the roles itil, web_service_admin and x_nexsa_imc_manager.
f. Save changes by clicking on Update.
Execute setup script
The next step would be to execute the Setup Script to load the default configuration to be run by the application.
Click on the
Setup Scripts module to display the Scheduled Script Execution named Default Configuration Setup.
Click on the
Default Configuration Setup record.
Click on the
Execute Now button to load the initial configuration.
The execution of this script will load the default Device Properties to be considered when endpoints scores are displayed (see Device Properties), set a default table for the devices to be stored (see Device Tables) and create the Score Definition for the Device Properties.
Enable/disable remediation
To enable/disable the remediation feature on the application, the user must appropriately toggle the value of the x_nexsa_imc.enable_remediation property (in the Properties module).
Define Scores configuration
In order to configure the Scores to be displayed on the Incident form, it is first necessary to properly load them into the application. Here is a detailed description of the steps involved:
Open Finder and export the Scores that must be loaded into the ServiceNow application to an XML file.
If necessary, configure all the Scores formats that require some special transformation. For this, a
Format attribute must be inserted in the required Input element of the XML Scores configuration, see the example below.
Format="percent">
<Field Name="disks_smart_index" />
</Input>
There are several formats that can be applied to transform retrieved values, such as:
second
millisecond
microsecond
byte
mhz
permill
percent
bps
To select the appropriate format, please check the NXQL Data Model of the field corresponding to the one shown in the attribute Name if the input is of type Field, or in the attribute Output if the score is of type Computation.
If necessary, configure all the Scores that have a remediation panel available.
For this, a Document element must be inserted inside every Score mentioned. Every Document element must be composed of Header and Sections elements to properly format the panel. The most important element to specify inside the panel is RemoteAction which contains the IDof, a remote action to be invoked through the Portal API. Please note that a new attribute ‘Name’ has been added to the RemoteAction element. See the example below:
<Document>
<Header>S.M.A.R.T is a monitoring system included in computer hard disk drives (HDDs) and solid-state drives (SSDs) that detects and reports on various indicators of drive reliability.</Header>
<Sections>
<Section>
<Title>Step 1: It can be an overheating problem</Title>
<Description>It is necessary to increase fan speed.</Description>
<RemoteAction UID="364bd31c-39a3-4ee3-b4a6-c9e83d731707" Name="Increase fan speed" />
</Section>
</Sections>
</Document>
Back in the ServiceNow instance where the application is installed, click on the
Score Definitions module.
Click on
New to insert a new score definition record.
Fill in the
Name, the Caption, and the Order fields. Make sure Active is checked and click on Submit.
Back in the
Score Definitions list, click on the score definition just created. Note that if you are not in the application scope then the score tab will be empty and it will not work.
Attach the XML file with the score definition. The following images provide a detailed view of the next steps to take.
The fields of the Score Definition are automatically populated (the content will vary depending on the score uploaded).
Enable creation of Scores snapshots
By default, the Incident Manager Connector dynamically loads the Nexthink Scores in tabs every time the incident ticket is opened.
It is also possible to store the Nexthink Scores in the Work Notes thanks to the “Take snapshot” button.
The snapshots are saved in the Work Notes tab with the format represented in Figure Scores snapshot saved in the Work Notes.
In order to save the snapshots, it is necessary to have previously loaded the Score tabs in the incident.
The snapshots can be enabled by setting one or both of the following properties to true, available in the Properties section in the Incident Management Connector.
“Set true to store a snapshot when incident is created”: When this property is enabled, a snapshot is automatically stored in the Work Notes when a new ticket is submitted manually. Since the snapshot is stored using the work_note field, if any comment is added to this field before creating the ticket, it will be overwritten with the snapshot content. Thus, it is required to create the ticket first and then add the comment in another work note once the incident is already created. Apart from that, this functionality is only available for the Incident view.
“Set true to allow snapshot button (snapshot on demand)”: This allows for the creation of a snapshot of the scores after the Incident is submitted to be stored in the Work Notes, at any time during the incident life. This is done by pressing the “Snapshot” button in the Incident view or pressing the “Take snapshot” in the Agent Workspace Nexthink Panel.
These properties are disabled by default when the Incident Management Connector is installed.
When the ”snapshot on demand” property is enabled, the snapshot button will be displayed for a submitted incident. In other words, the button will not be displayed until the Incident form is saved into a record.
After the “submit” button is clicked, the snapshot button will be displayed on the top right corner of the Incident form or on the top right corner of the Nexthink Panel in the Agent Workspace Incident form.
a) Incident form
b) Agent workspace
Snapshots formats
Snapshots will be inserted in the incident’s Work Notes as HTML or Text depending on the property “Allow support for embedding HTML code by using the** [code] _tag_” (At _System Properties -> UI Properties),**_ as it restricts the insertion of HTML in the Journal fields, the snapshot will look like below Figure Snapshot inserted as Text in the event of the UI Property being disabled.
In the event this property is changed to false, snapshots previously recorded as HTML will be rendered as HTML text, impacting their legibility. The snapshots taken after the change will be automatically saved in text format.
However, since IMC v2.2, it is possible to create a new IMC property to override the UI property configuration. In case it is necessary, it is possible to create the property x_nexsa_imc.plain_text within the Nexthink Incident Management Connector scope with the below settings:
Field | value | Comment |
---|---|---|
Suffix | plain_text | |
Name | x_nexsa_imc.plain_text | Fulfilled automatically |
Description | Property to override the "Allow support for embedding HTML code by using the [code] tag" | |
Type | true | false | |
Value | [true] | [false] | Set true to store snapshots as plain text comments or false to store using HTML format. |
For further clarification, the above property will always prevail over the default UI property. Therefore, in case any inconsistencies are found between the format of the snapshot and the UI property "Allow support for embedding HTML code by using the [code] tag", please, double-check if there is any property called x_nexsa_imc.plain_text in the sys_properties table.
Define device properties
As mentioned earlier, in addition to the scores loaded by users, a series of standard device properties can be retrieved from Nexthink to be displayed on the Incident form. Those properties can be edited by accessing the Device Properties module. Take special care when defining the platform for each device property (see the Nexthink Data Model1 if you have any doubt).
To configure the records of this table, it is necessary to specify the following fields:
ServiceNow field | Value |
---|---|
Field | Nexthink device table field (including custom fields) to retrieve for the Incident form |
Caption | Text to label the field when displayed on the Incident form |
Order | Order in which the field will be displayed on the Incident form |
Platform | Options: Windows – Windows & Mac |
Fields to be populated to create a new Device Property
Define device tables
Users can also configure the tables in which devices are expected to be stored or the tables from which a custom device table must inherit (see Device Tables). Only devices stored in these tables (or extending from them, depending on the value of the x_nexsa_imc.allow_extending_device_tables property) will launch the scores retrieval process in the Incident form.
To configure the records of this table, it is necessary to specify the next field only:
ServiceNow field | Value |
---|---|
Table | ServiceNow table directly containing devices or from which other extending tables will also be considered (according to property value). |
Fields to be populated to create a new Device Property.
It is possible that the tables inserted in this Device Tables module (or tables inheriting from those included here) will need some cross-scope access privileges to be granted. In order to achieve this:
Navigate to Application Cross-Scope Access, under the System Applications menu.
Create 4 new cross-scope privileges for each table (Read, Write, Create and Delete).
ServiceNow field | Value |
---|---|
Source Scope | Nexthink Incident Management Connector |
Target Scope | Global |
Target Name | |
Target Type | Table |
Application | Nexthink Incident Management Connector |
Operation | Read / Write / Create / Delete |
Status | Allowed |
Cross-scope privileges configuration.
Define Engine-Device discovery configuration
It is extremely important at this point in the configuration to be certain that every endpoint has an Engine associated with it so that when it is loaded from an incident form, Nexthink Scores can be queried and retrieved. This can be achieved by executing the utility Discover Engines - Devices included in the Scheduled Jobs module.
Basically, this artifact can be executed in two ways:
On-demand: Click on Execute Now. The utility will be executed once.
Scheduled: The user can set up a particular schedule for the utility to be executed (daily, weekly, etc.).
In this case, please remember to have the Active checkbox selected.
Please note that if an endpoint is moved from one Engine to another, the discovery process must be run again to update the Engine associated with it. The Scheduled mode comes in handy when users do not want to manually execute the process, but allows the system to automatically run the process once a day, a week, etc.
To check the Engine associated with every endpoint, users only have to access the devices table (for instance, cmdb_ci_computer) and check the NXT Engine field.
In addition, it is important to remark, that in version IMC 2.3 or lower, this scheduled job expects every configuration Item to be registered at most only in one of the tables configured in the “device tables” configuration. This job has a mechanism to manage duplicates within the same tables, but if the CI is duplicated in different tables the script will only perform the mapping for one of them.
On the other hand, starting from version IMC 2.4, there is a new system property added to the configuration UI page to allow enabling a new Discovery method.
I.E:
This property is configured as “false” by default, but in case it is enabled, a new version of the discovery manager optimized for large CMDBs will be executed when the scheduled job Discover Engines - Devices is executed.
Please, note that it is only recommended to enable it on instances where performance issues are experienced during the discovery scheduled job is running. In any other case we strongly recommend to keep the property set as false
Besides, this new process allows mapping all duplicated devices with their respective Nexthink engines even if they are stored in different tables.
Shortcut for CI assignment
Sometimes it is critical to know which device belongs to the caller that opened the incident. To simplify this task, the connector provides two ways to auto-populate the Configuration Item field based on the Caller field. To achieve this, two new buttons can be configured to be displayed beside the Caller field in the Incident form.
The first button shows all the configuration items assigned to the caller, according to the Assigned To field of the configuration item itself.
The second button shows all the configuration items related to the caller, according to the information stored in the cmdb_rel_person table.
In both panels, you can simply right-click on the desired CI, and click on the ‘Assign as CI’ action.
To activate these buttons, ensure the global scope is selected in the application picker in the header, right-click over the Caller field in the Incident form and navigate to ‘Configure Dictionary’.
In the Attributes section, concatenate the desired option to the ref_contributions attribute. Please note this must be done in the Global scope.
Attribute | Value |
---|---|
ref_contributions | x_nexsa_imc_user_show_assigned_devices |
ref_contributions | x_nexsa_imc_user_show_related_devices |
Note that the manager can decide to implement none, one, or both of them.
If the Attributes section contains any previous configuration with other attributes apart from ref_contributions, please, keep in mind that the values assigned within every attribute must be separated using semicolons (highlighted in blue below) and every attribute is split from each other using commas (highlighted in red below).
Configure triggering field in the Incident form
By default, the Incident Management Connector looks for the device properties and scores when the user enters a value in the cmdb_ci field in the Incident form. The picture Default triggering field shows the default field in the Incident form2.
You can change the triggering field on the properties page as shown in the below screenshot Default triggering field define in the Properties section.Just be sure that the new field is a reference to cmdb_ci or one of its descendants.
For example, we can create a new field named “x_nexsa_imc_computer” in the Incident form. The property must change accordingly, as shown in the below sample.
In the incident form, the field that would refresh the score would be the one you selected. For example:
2 SN Utils is a Chrome add-on that allows watching in the technical name of a field on the form. Although it is not necessary, we have used it in these examples to provide a better understanding.
Configure Custom Action to create Incidents from the Finder
Creation of Incidents is possible from the Finder, by adding a new Custom Action, which can be found in the Product download page of the Incident Management Connector.
To add the new Custom Action, go to the Custom actions menu in Finder, double click on the “Create ServiceNow Incident” one, and modify the URL to point to the desired ServiceNow instance. From now on, when you execute this Custom Action on a given device, a new browser window will be opened with a ServiceNow incident. This incident will have the device selected in Nexthink as CI.
Disable Open in Finder Button
Adding the role x_nexsa_imc.disable_open_in_finder will disable the Open in Finder Button which is shown in the Nexthink tabs.
Support Telemetry program
The Support Telemetry program aims to provide your organization with a better support experience by sharing information with your Nexthink appliance about the actual configuration and use of the application. Support Telemetry collects the following data points: application configuration, application performance, and feature usage (more details in the online documentation).
With the help of this data, the Nexthink Support team will be able to respond to your organization’s requests more efficiently, as the necessary information will already have been provided to them.
This feature is currently available for Oauth 2.0 and basic connections. However, in case the connection type setup in the portal or portals is Oauth 2.0, please, ensure the scope service:telemetry is configured in the OAuth entity profile.
I.E:
Install Service Portal Widget
The installation of the NXT-Self Service Portal Score widget consists of two main steps: creating the Service Portal Score definition and configuring the Service Portal page to add the widget.
Please remember that the device for which the score will be retrieved must be assigned to the user accessing the Service Portal on ServiceNow. If version 2.3 or lower is installed, please, note that the widget will not be displayed if more than one computer is assigned to the same user. From IMC v2.4 on, the widget will also be displayed for end-users with more than one device assigned.
Also, remember to give the users that will use the widget the role nexsa_imc.service_portal_viewer. This user will also need permissions to read the tables cmdb_ci, oauth_entity_profile, sys_db_object and sys_auth_profile. If the user does not have them, an error will be displayed and the widget will not be shown. Apart from this, due to the ServiceNow role management, it is important to note that the widget will also be displayed for users with admin role.
To configure the Score Definition, it is required to follow the below steps:
Make sure that the Service Portal Score definition has been added to the Finder. Please follow the section Define Scores configuration for further reference.
On your ServiceNow instance, to create the score definition, navigate to the Score Definitions module.
Click on New to create a new record.
Complete the Name and Caption fields with any value. (Service portal Widget would be a good example)
Check the Display in Service Portal checkbox.
Click on the Submit button.
Back in the Score Definitions list, click on the score definition just created to reopen the record.
Click on the Manage attachments button.
Browse for the XML file containing the Score Definition and select it. The remaining fields in the form will be completed automatically.
As can be seen on the above screenshot, the self-service score is just available for Windows devices only out-of-the-box. In case it is necessary to leverage the score for macOS devices as well, please, go to the Customizing the Service Portal Widget Score definition section for further reference.
The next step involves configuring the Service Portal page in which the widget will be displayed.
Navigate to Service Portal Configuration.
Click on Designer.
Search for the page on which the widget should be displayed. If it is the main page displayed when opening the Service Portal, click on Index.
In the left-side column, on the Widgets tab, look for the NXT-Self Service Portal Score widget.
Drag the widget into the position of your choice on the page. After a few seconds, the widget will be loaded onto the page:
To use the widget, navigate to Service Portal Home.
In versions 2.0.0 to 2.3, the widget will be displayed, featuring the name of the computer assigned to the user accessing the Service Portal (Please, note that the widget will not be displayed if the user has more than one device assigned in cmdb_ci).
However, starting from v2.4, the widget will display different information based on the given status:
If the user has no devices assigned the below message is displayed:
In case there are no active engines configured in the x_nexsa_imc_endpoint:
When just one device is assigned to the user, the name of the CI will be displayed. The widget will work following exactly the same logic as in previous versions:
If more than one device is assigned to the user the widget will display a combo box where the user’s devices are eligible to be selected:
Once the box is clicked, the device list is displayed as below:
Finally, right after clicking on any of the devices, the button to retrieve the data from Nexthink, which is at first disabled, will be enabled and display the message Click here to improve your digital experience.
To retrieve the information for the computer, click on the button mentioned above. After a few seconds, the information for the score will be displayed.
For scores that need some improvement, a button appears offering the user the option to launch a Remote Action by clicking it. Click on the Fix it button to execute it and after a few seconds, a modal window will be displayed informing the user that the remediation was requested correctly.
Please bear in mind that although the remediation may have been executed, the results may not be immediately reflected in the score, depending on its computation time and other factors.
Apart from this, it is important to know that starting from IMC 2.4, a journal message is created in table sys_journal_field every time that a Remote Action is executed from the widget. Thus, it is important to activate the “can read“, “can create“ and “can update“ application access for this table as displayed below:
Apart from this, it is also required to create the ACL rules to allow the users with Service Portal Viewer role to create and write records in the sys_jounal_field table as explained in the “Roles and ACLs“ section.
Customizing the Service Portal Widget Score definition
The default Service portal widget score can be installed in the Nexthink appliance towards the library using the following link: Employee Self Service. Although, the score has been designed for a standard case that might not be applicable to all scenarios.
In case it is required to edit the score XML content, it is important to understand the procedure to create or edit a score. In summary, ther
Alternatively, Edit the XML file using a text editor
It is always recommended to use the Scores creator tool. Editing the XML code manually using a text editor is only advisable for quick local changes and only for XML fluent people.
Custom score example
IMPORTANT:
Please, bear in mind that it is only allowed to include one leaf score under every composite score. If more than one leaf score is included within a composite score the widget will not be accurate.
In case of doubt, please, feel free to reach the Nexthink support team for further clarification.
The most interesting part for editing the content of the service portal widget will be located in the leaf score side (select it on the top-left corner of the editor), within the document section:
If the Figure Document Section in the Score creator display is taken as an example, the score will have the following behavior:
If the value of the leaf score is higher than 7 and lower than 10. (Green status)
The message set in the description section will be displayed along with the green check:
If the value of the leaf score is higher than 3 and lower than 7. (Yellow status)
Apart from the message set in the description section and the warning icon, the URL set in the HTTP content section will be displayed as a link.
If the value of the leaf score is lower than 3. (Red status)
The message set in the description section and the failure icon will be displayed. In addition, the remediation set in the RemoteAction content section will be executed if the Fix it button is pressed
To summarize, the score will always display:
The description message, the status icon, and the Fix it button if the score result is red.
The message, the icon, and the link for helping the user to fix the issue by himself if the score result is yellow.
The message and the status icon if the result is green.
A green check and no message if the leaf score value is blank.
In other words: It is not possible to display any link if the result is green or red, to request a remote action if the result is yellow or green, to offer more than one remote action if the result is red, or to display more than one link if the result is yellow.
At this point, it is important to clarify that the score does not always have 3 different thresholds. For example, in case there is a score measuring if the anti-malware software is running on a particular device, there can only be 2 possible scenarios:
Yes - Green status
No - Red status
Similarly, the thresholds of the score can be modified. It is possible to adjust the values taken as a reference to set the status color of a leaf score. To achieve this, it is necessary to modify the settings under the Normalization section of the leaf score.
With the above screenshot, we can conclude that:
Red status: Any value between 0 and 23000000000 incoming from the field system_drive_free_space will be assigned with a value between 0 and 3 based on this scale.
Yellow status: Any value between 23000000000 and 30000000000 incoming from the field system_drive_free_space will be assigned with a value between 3 and 7 based on this scale.
Green status: Any value larger than30000000000 incoming from the field system_drive_free_space will be assigned with a value between 7 and 10 based on this scale.
All these scales and score values are customizable to adjust to every situation. Please, ensure the scale makes sense in order to avoid any misbehavior of the widget.
How to activate the score for the macOS platform
By default, the score that can be installed through the Nexthink Library (Link) is only available for Windows devices.
In case is necessary to enable it for macOS devices as well, it is necessary to follow the below procedure.
Open the Scores creator tool
Load the XML file of the score
Click on the first composite score in the left panel
Check the macOS option
Click on Save score
Upload the XML file in both Finder following the last 6 steps of this procedure.
Update the attachment of the score definition of the Self-Service score with the new XML file generated following this procedure.
Navigating in Nexthink Incident Management Connector
Navigating in the Incident form
Please, note that, as informed in the Nexthink Requirements section the Nexthink scores will only be displayed in the default view of the incident table from.
Once the user has some scores or properties defined to be visualized when opening or creating an incident for an endpoint, the Create New module can be selected for this purpose.
NOTE: To be able to visualize the scores and remediation panels, a Configur