Skip to main content
Skip table of contents

ServiceNow import via SFTP installation guide

This guide provides comprehensive information on how to install and configure the ServiceNow import via the SSH File Transfer Protocol (SFTP) integration with ServiceNow, as well as basic maintenance guides.

This document provides a detailed description of the processes needed for a successful installation. The information contained herein is subject to change without notice and is not warranted to be error-free.

If you find any errors, please report them to us via Nexthink support portal. This document is intended for readers with a detailed understanding of Nexthink technology and ServiceNow technology and some understanding of concepts such as business rules, scripting, and some basic security terms.

These configuration instructions must be executed by a ServiceNow certified professional

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

ServiceNow import via SFTP Installation and Configuration Guide

Overview

The ServiceNow import via SFTP offers Nexthink customers the ability to integrate end-user IT data from Nexthink Infinity into the ServiceNow platform. Configuring the ServiceNow import via SFTP is possible by selecting the set of information about different Configuration Items such as devices, users, software packages and other items, that the system will populate into ServiceNow. Additionally, the system can import the relationships between these Configuration Items (CI) into ServiceNow.

The integration provides a default set of transform maps with the corresponding information from Nexthink, thus offering a set of predefined mappings. Additionally, the integration allows you to leverage the import of specific fields associated with a given CI type.

In addition to the default mappings, the flexible design of the integration allows you to configure different CMDB ServiceNow table and fields populated by unprotected transform maps.

For installation guidelines, go to the Initial Configuration section.

Main ServiceNow components included

Custom table inventory

The application creates 8 custom tables that the system uses as staging tables to manage the import sets. You should not allocate these tables to any subscription.

Find more information about custom table allocations below:

Label

Name

Import Set Software

x_nexsa_sftp_import_set_software

Import Set User

x_nexsa_sftp_import_set_user

Import Set Workstation

x_nexsa_sftp_import_set_workstation

Import Set Workstation - Software

x_nexsa_sftp_import_set_workstation_software

Import Set User - Workstation

x_nexsa_sftp_import_set_user_workstation


NQL query to use in the Data Export feature

The Nexthink Infinity Data Export feature generated the CSV file used to create all the import set tables listed in the previous section. This was done using the following queries:

CI Type

Query

Workstation

CODE
devices
| where hardware.machine_serial_number != "" and (hardware.type == laptop or hardware.type == desktop)
| include cpus
| compute num_of_cores = number_of_cores.count() , number_of_cpus = count(), freq = 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 , freq ,disk_capacity, operating_system.name , operating_system.build 

Windows Server

CODE
Not supported yet

User

CODE
users
| where name !in ["*Local*"]

Software

CODE
package.installed_packages 
| list package.name, package.version , package.publisher 

User-Workstation Relationship

CODE
session.connects during past 7d
| where hardware.type == laptop or hardware.type == desktop
| summarize c1 = count() by device.name , user.name , user.ad.full_name
| list device.name , user.name , user.ad.full_name

Workstation-Software Relationship

CODE
package.installed_packages 
| where (device.hardware.type == desktop or device.hardware.type == laptop) 
| list package.name, package.version , package.publisher , device.name, device.hardware.type 

User-WindowsServer Relationship

CODE
session.connects during past 7d
| where hardware.type != laptop and hardware.type != desktop
| summarize c1 = count() by device.name , user.name , user.ad.full_name
| list device.name , user.name , user.ad.full_name

WindowsServer-Software Relationship

CODE
Not supported yet

Import sets, data sources, transform maps and scheduled imports

The Nexthink CMDB Populator integration provides one import set table, data source, transform map and scheduled import for each of the CI types and relationships that you can import:

Data Sources

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

Import set

The import sets are a special type of ServiceNow tables used during the import process. They act as a staging area, to receive the raw data from the data source and push that data into the ServiceNow target table.

Transform map

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. During this part of the process, it is also possible to modify, slice or convert any data imported in the import set and store the resulting data in the final table per the requirements.

Scheduled Import

Scheduled imports specify that the system will execute a given import operation at a regular interval, which can be defined as daily, weekly, periodically or a different timeframe. By default, the scheduled imports that the integration provides are inactive, as a different script will programmatically execute them.  Find more information in the following section.

Roles

ServiceNow import via SFTP creates a new role to manage the application, the x_nexsa_sftp.manager role.

Role

Task

x_nexsa_sftp.manager

  • Insert data in the import set tables.

 

Depending on the existing Access Control Lists (ACLs) that you have applied to your instance, you may need to modify some to include the x_nexsa_sftp.manager role. If you do not modify them, you may be unable to view some system tables and their associated records when performing the initial setup.

Other ServiceNow components you may need to consider

References and choice fields

The system has configured every column in the CMDB to contain a particular type of data. There are two types that behave in a specific manner.

In string fields, for example, the system may insert and store any incoming data with no more consequences. However, for reference and choice type fields, the system relates them to another record in a different table.

For instance, the field Manufacturer in the cmdb_ci_computer table is a reference to a given record in the standard core_company table, thus, to insert any information in the manufacturer field, the system must have an existing record to reference in the core_company table.

On the other hand, the choice fields work in the same way, but in this case, you must create the choices in the sys_choice table.

By default, the transform maps included in this application create records in the sys_choice and in every referenced table when Nexthink receives any new data. In other words, if the manufacturer received in the CSV file does not exist in the core_company table, the system will create one to allow the transformation to insert it into the reference table.

Business rules

Even if you have not defined any business rules in the application, the system configures all transform maps to respect any rule previously defined in the ServiceNow instance.

Transform map “Run business rules” setting detail

Every instance has its own business rules. Nexthink does not recommend bypassing these rules when inserting data into the target tables, as unexpected and potentially undesirable behavior could surface during the import process.

Transform scripts

Among the transform maps, the system populates some fields after transforming the data received from Nexthink. Refer to the table below:

Transform Map

source field

Target Field

Transformation

Workstation

u_device_operating_system_name

os

Gets operating system information

Workstation

u_device_opera_g_system_build

os_version

Gets operating system version

Workstation

u_device_hardware_memory

ram

Converts bytes to megabytes

Workstation

u_disk_capacity

disk_space

Converts bytes to gigabytes

User-Workstation

N/A

type

Inserts relationship type in cmdb_rel_person table

Workstation-Software

N/A

name

Sets relationship name based on the software and CI name

Workstation-Software

N/A

software

Sets the product name value based on the software name and version

Initial configuration

Application installation process

The application package is only available in the update set format. To install, follow these steps:

  1. Go to the System Update Sets > Retrieved Update Sets module.

  2. Click the Import Update Set from XML related link.

  3. Upload the application update set XML file.

  4. On the update set table, click on the ServiceNow import via SFTP update set.

  5. Click the Preview update set button and wait for the preview process to finish.

  6. Click the Commit update set button and wait for the process to finish.

  7. The Update set status should switch to committed.

x_nexsa_sftp_i1.0.0.xml.xml

Role assignment

Only a user with admin rights or a user who has the x_nexsa_sftp.manager role can write the import set tables included in the update. It is important to provide the users that will run the scheduled imports with one of the aforementioned roles.

Additionally, the ability to write in the target tables (Computer, Software, People Relationship) may be affected by other rules. Ensure the user in charge of importing data has access to write in all the target tables listed below.

  • Computer [cmdb_ci_computer]

  • Software [cmdb_ci_spkg]

  • User [sys_user]

  • People Relationship [cmdb_rel_person]

  • Software Instance [cmdb_software_instance]

Cross-scope permissions

The system has configured all the target tables detailed in the previous section with the cross-scope permissions enabled out-of-the-box to allow the ServiceNow import via SFTP to write and create records in all of them.

However, a situation may arise where the system triggers the following error during the import process:

[Read|Write|Create] operation on table '{table_name}' from scope 'ServiceNow import via SFTP' was denied. The application 'ServiceNow import via SFTP' must declare a cross scope access privilege. Please contact the application admin to update their access requests.

In such a case, resolve the issue by editing the affected table settings to grant the required operation in the application access configuration.

For example:

Application Access permissions

Data Source Configuration

The application contains a data source pre-configured per each CI Type and relationship available.
By default, these data sources populate the tables disclosed in the Custom Table Inventory section.
Additionally, the system configures each one of them to retrieve a CSV file retrieved from an SFTP server.

The rest of the fields are empty by default because you must populate them with the SFTP related information.

Data Source form

To configure the data source, go to the ServiceNow import via SFTP > Data Sources module and click over the required Data Source. Configure all the fields listed below:

Field

Detail

Server

DNS of the SFTP Server

Port

Port to access the server (port 22 by default)

File Path

Absolute path to reach the CSV file to be imported

Username

Username of the SFTP Server

Password

Password of the aforementioned user

CSV delimiter

Symbol used as delimiter (default value: “,“)

Optional configuration

Transform maps Configuration

Linked to every data source, there is a transform map created with some predefined settings. These are basically configured to map the columns imported in the import set table with the fields in the target table, also allowing some transformations when necessary.

Field Maps detail

In the screenshot above, you see all data stored in the u_device_entity field of the staging table will be transferred to the location field of the target table.

On the other hand, the system will record some data resulting from a transformation script in other columns like os or os_version.

Source Script example

If you need to create a new field mapping or edit any of the existing field maps, follow the ServiceNow standard procedure:

Scheduled Import Configuration

As explained in the Scheduled Import section, you can schedule the system to execute the import procedure at particular intervals.

To do so, go to the module ServiceNow import via SFTP > Scheduled Import.
In this module, there are 8 different predefined scheduled jobs (one per CI type). To access the configuration form, click on the scheduled import you want to modify.

Scheduled Import configuration

The following table details each configuration field in the form:

Field

Detail

Active

Controls if the system executes the scheduled import or not. Check the box to enable it.

Run

Frequency at which the system executes the import. The fields underneath will differ depending on the selection you make in this field

Run as

Name of a user whose credentials the import job uses. If you do not specify a value, the import job runs as the guest user.

The most important setting in the table above is the active setting. After you activate this field, new fields appear below the run field to configure the date or the interval details of the scheduled import. Find further details about these options on the ServiceNow documentation.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.