Exporter to ServiceNow CMDB

This documentation references external sources. Nexthink does not have control over the accuracy of third-party documentation, nor any external updates or changes that might create inconsistencies with the information presented on this page. Please report any errors or inconsistencies to Nexthink Support.

This page explains how to integrate an HTTP API Exporter with ServiceNow Configuration Management Data Base (CMDB). Therefore, the configuration samples in this document adhere to the following context:

• Exporting Nexthink data into ServiceNow CMDB using the endpoint: api/now/import/<staging_table>/insertMultiple

• Adding each asset and relationship on the Nexthink web interface within a single data exporter.

• Setting the payload structure as a JSON object with an array.

• Conducting a test with an empty CMDB on the Nexthink instance which can only be accessed by the development team.

Prerequisites

You need the following components to run the ServiceNow integration:

• A Nexthink platform instance.

• A ServiceNow instance.

• Connector credentials in the Nexthink web interface for the ServiceNow endpoint insertMultiple.

• An HTTP Data exporter in the Nexthink web interface.

• CMDB Strategy. Refer to the MDB Strategy and Planning documentation.

• Compliance of the necessary roles with target table ACL rules for users involved with the data import process.

Nexthink recommended settings for ServiceNow CMDB

The following table displays the recommended combination of data export scheduling and data volume.

Nexthink cannot guarantee data ingestion completion before executing the next data exporter for volumes over the recommended limits below.

This means you should not export more than 3.5 million records from Nexthink directly to ServiceNow in one week.

Data Export Recurrence	Recommended max number of records sent
Hourly	up to 25K records
Daily	up to 600K records
Weekly	up to 3.5M records

The maximum number of records returned by NQL API is 1 million per call.

ServiceNow recommended settings to import Nexthink Data

Nexthink recommends using the out-of-the-box transform map procedure in ServiceNow to import data from Nexthink.

In addition, you can use an update set package to set up a generic API call in the ServiceNow integration. Refer to the Generic API call in ServiceNow installation guide.

ServiceNow basic configuration

The steps listed below offer a quick summary of basic ServiceNow configuration:

1. Modify the timeout settings in the ServiceNow instance

2. Change application access to the table CI/User Relationship Type

3. Create an import set table in ServiceNow

4. Verify that the system has created the import set table

5. Create a transform map

6. Configure the Data Exporter in Nexthink

7. Run an end-to-end

Click on any of the steps above to jump to the specific instructions.

Modifying the timeout settings in the ServiceNow instance

1. Go to the System definition > Transaction Quota Rules module.

2. Search REST Import Set API request timeout and REST and JSON Catch-All. Change the value for Maximum Duration (seconds) to at least 300 (5 minutes).

Changing application access to the table CI/User Relationship Type

1. Go to the System definition > Tables module.

2. Search by name with the value cmdb_rel_user_type.\

   
3. Go to the Application Access tab and enable Can read, Can create and Can update for all the scopes.\

   

Creating an import set table in ServiceNow

The import set tables act as a staging location for record imports. The system automatically generates fields on these tables based on the imported data, therefore, you should not make any manual modifications.

Service now offers standard import set tables you may use if required. Refer to ServiceNow documentation for more information.

Creating an import set is mandatory because the system uses it to configure the Resource in the Data Exporter.

There are two ways of creating an import set table:

• Using a CSV file

• Using a Custom Script

Create an import set tables using a CSV File:

1. Select the NQL query that contains the assets or relationship to be sent into CMDB. For example, all Microsoft Windows laptops and desktops:

```
devices
| where hardware.machine_serial_number != "" and (hardware.type == laptop or hardware.type == desktop) and operating_system.platform == Windows 
| include cpus
| compute num_of_cores = number_of_cores.count() , number_of_cpus = count(), sum_frequency = frequency.sum()
| include disks
| compute disk_capacity = capacity.sum()
| list group_name, entity, hardware.manufacturer, hardware.model , 
operating_system.architecture , hardware.machine_serial_number , 
name, hardware.memory, num_of_cores , number_of_cpus , sum_frequency ,
disk_capacity, first_seen, last_seen
| limit 1
```

1. Run the NQL query in the Investigations module in the Nexthink web interface - add limit 1.

2. Export the CSV file using the Export Results button.

3. In ServiceNow, navigate to All > System Import Sets > Administration > Data Sources in the filter navigator.

4. Click New.

5. Complete the form**.** Fill out the fields according to the table below:

Field	Description
Name	A unique name to identify this data source.
Import set table label	A label for the import set staging table to use. For instance, nexthink_workstations.
Import set table name	This is automatically generated using the table label previously set (u_nexthink_workstations). It prevents namespace collision with an already existing table.
Type	File
Format	CSV
CSV delimiter	,

1. Attach the exported CSV file.

2. Click Load All Records.

Refer to ServiceNow documentation for detailed instructions.

Create a new import set table using a Custom Script

1. Navigate to All > System Import Sets > Administration > Data Sources in the filter navigator.

2. Click New.

3. Complete the form. Fill out the fields according to the table below:

Field	Description
Name	A unique name to identify this data source.
Import set table label	A label for the import set staging table to use. For instance, nexthink_workstations.
Import set table name	This is automatically generated using the table label previously set (u_nexthink_workstations). It prevents namespace collision with an already existing table.
Type	Custom (Load by Script).
Data Loader	This is generally used to provide a script to load data into the staging table. All fields Nexthink sends out must be added as part of the map variable. The field should look like this: (function loadData(import_set_table, data_source, import_log, last_success_import_time) {

var map = {
    name: "",
    entity: "",
    model: "",
    type:"",
    os_name:""
};
import_set_table.insert(map);

})(import_set_table, data_source, import_log, last_success_import_time); |

1. Click Load All Records.

2. Click Submit.

Refer to the ServiceNow documentation for detailed instructions.

Verifying that the system has created the import set table

1. Navigate to All > System Import Sets > Import Set Tables.

2. Verify that the import set table created in step 3 is listed.

Creating a transform map

ServiceNow documentation defines transform maps as:

A transform map is a set of field maps that determines the relationships between fields in an import set and fields in an existing ServiceNow table, such as Incident incident or User sys_user.

1. Create a transform map from the Data Source or from the Transform Maps module.

2. From the Data Source, go to the bottom of the page and click on the New button.

1. You can also navigate to System Import Sets > Create Transform Map.

   • Both options redirect you to a page with a form where you must fill out all mandatory fields.

1. Complete the form according to the table below:

Field	Description
Name	A unique name for the transform map
Source table	The staging table created when the data was imported in the previous step with the Data Source
Target table	The final table where all the data will be stored

1. Click Submit and you are ready to create a transformation for fields.

2. At the bottom of the page, in the Field Maps section, click New.

In the new Field Map section, you can configure a transformation in two ways, with the box for Use source script unchecked or checked.

Transformation with Use source script option unchecked

1. Copy the value from the source field to the target field without any changes.

2. Complete the fields according to the table below:

Field	Description
Source field	Field from the selected staging table to get the value from.
Target field	Field from the selected target table (final table) to store the value.
Coalesce	This determines the uniqueness of the record. If you tick this box, the field will be used as the primary key to detect if the record needs to be inserted or modified.

Transformation with the Use source script option checked

In this option, the source script defines the value of the target field.

Complete the fields according to the table below:

Field	Description
Target field	The field from the selected target table (final table) to store the value.
Coalesce	This determines the uniqueness of the record. If you tick this box, the field will be used as the primary key to detect if the record needs to be inserted or modified.
Source script	This JavaScript method should return a value to be stored in the desired target field. Use the variable source to get information from source table. Check the Custom Transformations section on this page for further information.

Choice action fields

Some fields in the target table may be external references to other tables, such as Company, Users and other references. Selecting any of these fields activates a new option called Choice action.

1. Set the value for the Choice action to create.

Value	Description
Create	The system creates a new record in the reference table (manufacturer, user or others.) with the value from the source field. The target table will reference this new record.
Ignore	The system ignores the value and the column remains empty in the final table.
Reject	The system omits the whole record from the source table.

1. Click Submit and the system redirects you to the transform map details page. You can add as many fields as you wish or directly save the transform map.

Refer to the ServiceNow documentation for details.

In addition, you may also review the update set package that is available in the Generic API call in ServiceNow installation guide.

Configuring the HTTP API data exporter for ServiceNow CMDB in Nexthink

• Create a new data exporter following the steps described in the HTTP API Exporter documentation.

• Configure the following parameters in the General tab:

  • Credentials: ServiceNow credentials of the targeted instance.

  • Method: POST.

  • Resource: api/now/import/<import_set_table>/insertMultiple. The import_set_table is the name of the import set table created and configured in Step 3.

• In the Data tab, configure the following parameters:

  • NQL query: insert the query to export the assets or relationships.

  • Payload structure: JSON object with an array.

  • Payload: create the payload specifying only one element to be exported and the placeholders to be taken from the NQL query. See the JSON example below.

• Save the Data Exporter.

{
 "records":[
    {
 "name": "{{device.name}}",
 "entity": "{{device.entity}}",
 "model": "{{device.hardware.model}}",
 "type": "{{device.hardware.type}}",
 "os_name": "{{device.operating_system.name}}"
    }
  ] 
}

The name of the fields within the payload must match those defined for the import set table.

Running an end-to-end

Run an end-to-end to test the entire configuration for workstations.

Configure Nexthink and ServiceNow for end-to-end

1. Configure these components in the Nexthink web interface:

   • ServiceNow credentials

   • Data Exporter for Workstations

2. Configure these components on ServiceNow:

   • Import set table for workstations

   • Transform map for creating/updating workstations

Test the HTTP data exporter

Click on the Test load up to 20 records button to execute the query configured in the Data tab.

Refer to the HTTP API Exporter documentation for more details on a Test load of up to 20 records.

Check the import table content and transformation results in ServiceNow

1. Copy the name of the import set table. For example, x_nexsa_g_api_call_import_set_workstation.

2. Type Import Set in the explorer field on the left side of the ServiceNow interface.

3. Click Import Set in the Advanced options.

4. Insert the import set table in the filter to display all the import sets referencing that table:

Each import set has a number that contains all the records being inserted.

1. Click on the import set number link for more details.

2. On the details page, find information about the import set:

   • Review when the import set table was created.

   • Review the Load completed time.

   • Review Load run time.

• At the bottom of the details page, find three tabs with the following information:

Import Set Run: Statistics about the process, such as the number of records inserted/updated, the number of errors and the transform map applied.

Import Set Rows: The content in the final table. Click on any of these rows to see the final stored record.

Import log: Logs traced during the test.

Check ServiceNow final table to verify end-to-end test results

Review the final table in ServiceNow to verify that the data was inserted properly.

Custom Transformations

ServiceNow documentation defines transform maps as:

A transform map is a set of field maps that determine the relationships between fields in an import set and fields in an existing ServiceNow table, such as Incident incident or User sys_user.

As described in Transformation with the Use source script option checked section, you can enable a source script in the transform map to modify any incoming data from Nexthink.

For example, Nexthink stores RAM memory data in bytes, but ServiceNow stores the same data in megabytes. To correctly store the data you must convert it from bytes to megabytes.

Find below examples of basic scripts that you can use to convert the incoming data:

Convert bytes to megabytes

JS

return source.[FIELD_NAME] / Math.pow(1024, 2);

Convert bytes to gigabytes

JS

return source.[FIELD_NAME] / Math.pow(1024, 3);

Concatenate two fields

JS

return source.[FIELD_NAME_1] + " " + source.[FIELD_NAME_2];

Insert the first half of a string

CODE

var value = source.[FIELD_NAME];
return value.split([SEPARATOR])[0];

The custom transformations described above are included in the update set package within the Generic API call in ServiceNow installation guide.

Troubleshooting guide for empty fields in the target table

You may expect a field to have a value by the end of the integration process, but the field is empty.

This issue is most likely due to naming problems during the various parts of the integration. Follow the steps below to ensure everything is named correctly and the expected information is where it should be.

The following example uses the field device.group_name for demonstration purposes.

Troubleshooting in Nexthink

1. Verify that the field in question is part of the Payload (JSON) and is populated by the correct field from the data model. This information is available on the Nexthink Data Exporter page > Data Tab.

1. In Nexthink Investigations, ensure the field in question contains some information.

Troubleshooting in ServiceNow

1. Ensure the field in question exists in the staging table and its name matches the name in the payload.

2. Go to System definition > Tables. Search for the desired import set table and click on its name link.

3. At the bottom of the ServiceNow details page, search for the field in the list.

4. Click on the field's name. The column label must be equal to the property in the payload configured in Nexthink Data Exporter.

1. Ensure that there is a transform set for that field.

2. Find the desired transform map associated with the staging table under System Import Sets > Administration > Transform maps and click on the name link.

3. On the next page, search for the desired field in the list and click on its name. There should be one item whose source field and target fields match with the ones configured in the staging table and final table respectively.

4. Add log traces to the code to ensure the source script is returning a value. See the JavaScript below:

JS

answer = (function transformEntry(source) {
    gs.info("Checking group name: " + source.u_device_group_name);
 return source.u_device_group_name;
})(source);

1. Ensure the field in the import set table contains data. Follow the steps explained in the end-to-end section.\

F.A.Q.

How do I import a CI Type?

To import a CI Type, you must configure a data exporter as explained in the Configuring Data Exporter in Nexthink section of this document. Make sure that the payload generated matches the fields configured in the transform map.

Once the Nexthink web interface triggers the POST request, the system creates an import set in the ServiceNow instance and the transform map automatically populates the target table according to the configured field map.

What happens if there is an error in the payload field between Nexthink and ServiceNow?

If the Nexthink payload configured in the Nexthink web interface contains a value such as device.name while on the ServiceNow side the data source is created using device_name, the value will remain empty when the request is sent.

This can cause an error if there is a business rule that verifies certain values when a new record is created in the final table.

It is important to execute a Test Load 20 records before scheduling the automatic execution of the exporter to avoid this kind of error.

What happens if I add a new field after configuring and running the entire end-to-end?

The process is very similar to the one explained in the Creating an import set table in ServiceNow section.

1. Open the data source used to configure the import set table.

2. Modify the import set table:

   1. If you attached a file to create the import set table, attach the new file from the Nexthink web interface containing the new column and execute a Test Load 20 records again.

   2. If you created the import set table using a custom script, add the column within the map variable and execute a Test Load 20 records again.

3. Modify the transform map with the new column added as part of the import set table into the final table.

4. Modify the payload in the Nexthink data exporter to include the new field.

5. Execute a Test Load 20 records in the Nexthink web interface.

6. Verify that the import set table in ServiceNow contains a new column and it has been populated accordingly.

7. Verify that the final table in ServiceNow has populated the column accordingly.

What happens with the sys_choice fields when importing the data?

Similarly to the reference fields, the sys_choice tables behave differently if the inserted value already has an entry in the sys_choice table.

There are two different cases:

1. If the inserted value does not have any entry in the sys_choice table for the target class, ServiceNow inserts the value in the table and the font color is blue. This means the inserted value is in the record, but it is not possible to manually select it from the choice combo box for that field.\

   

   Blue case choice

2. If the inserted value already has an entry in the sys_choice table for the target class, ServiceNow inserts the value in the table and the font color is black. This means the value is eligible from the choice combo box menu. At this point, if the value does not exist in the sys_choice table, it is possible to create it before its insertion as described in the Choice field section.\

   

What happens if I have other import mechanisms running at the same time?

Make sure that the coalesce fields are accurately configured when importing data from different connectors into CMBD tables.

As described in the Creating a transform map section, the behavior of a transform map depends on the Coalesce checkbox. If ServiceNow finds any record in the target table and a uniquely marked field already exists in the target table, the CI updates with the information of the last import set.

Can I execute the import process automatically?

You must schedule a data export from Nexthink to start the import process at ServiceNow.

What if the user-workstation relationship runs before inserting assets?

• If any user-workstation relationship runs before the assets for the user or workstation are available, the import process does not fail. Instead, ServiceNow inserts the record in the relationship table, but the reference to the assets remains empty.

  

What happens if the Data Exporter cannot reach the third-party tool because of a network/server issue?

If the Data Exporter cannot reach the third-party tools, the information exported from the NQL query scheduler is lost.