> For the complete documentation index, see [llms.txt](https://docs.nexthink.com/platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/data-exporters/exporter-for-secure-file-transfer-protocol-sftp-server/cmdb-import-from-sftp-into-servicenow/servicenow-import-via-sftp-installation-guide.md).

# 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.

## Prerequisites <a href="#servicenowimportviasftpinstallationguide-prerequisites" id="servicenowimportviasftpinstallationguide-prerequisites"></a>

* A ServiceNow-certified professional must execute the configuration instructions on this page.

This page is intended for readers with a detailed understanding of Nexthink technology, ServiceNow technology and basic concepts such as business rules, scripting, and elemental security terms.

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](https://support.nexthink.com/).

{% hint style="warning" %}
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.
{% endhint %}

## ServiceNow import via SFTP overview <a href="#servicenowimportviasftpinstallationguide-servicenowimportviasftpoverview" id="servicenowimportviasftpinstallationguide-servicenowimportviasftpoverview"></a>

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 populates 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. 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.

{% hint style="info" %}
For installation guidelines, go to the [Initial Configuration](#servicenowimportviasftpinstallationguide-initialconfiguration) section on this page.
{% endhint %}

## Main ServiceNow components included <a href="#servicenowimportviasftpinstallationguide-mainservicenowcomponentsincluded" id="servicenowimportviasftpinstallationguide-mainservicenowcomponentsincluded"></a>

### Custom table inventory <a href="#servicenowimportviasftpinstallationguide-customtableinventorycustom_table_inventory" id="servicenowimportviasftpinstallationguide-customtableinventorycustom_table_inventory"></a>

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:

<table><thead><tr><th width="261">CI Type</th><th>Query</th></tr></thead><tbody><tr><td>Workstation</td><td><pre data-overflow="wrap" data-line-numbers><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
</code></pre></td></tr><tr><td>Windows Server</td><td><pre><code>Not supported yet
</code></pre></td></tr><tr><td>User</td><td><pre><code>users
| where name !in ["*Local*"]
</code></pre></td></tr><tr><td>Software</td><td><pre data-overflow="wrap" data-line-numbers><code>package.installed_packages
| list package.name, package.version, package.publisher
</code></pre></td></tr><tr><td>User-Workstation Relationship</td><td><pre data-overflow="wrap" data-line-numbers><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
</code></pre></td></tr><tr><td>Workstation-Software Relationship</td><td><pre data-overflow="wrap" data-line-numbers><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
</code></pre></td></tr><tr><td>User-WindowsServer Relationship</td><td><pre data-overflow="wrap" data-line-numbers><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
</code></pre></td></tr><tr><td>WindowsServer-Software Relationship</td><td><pre><code>Not supported yet
</code></pre></td></tr></tbody></table>

### Import sets, data sources, transform maps and scheduled imports <a href="#servicenowimportviasftpinstallationguide-importsets-datasources-transformmapsandscheduledimports" id="servicenowimportviasftpinstallationguide-importsets-datasources-transformmapsandscheduledimports"></a>

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 <a href="#servicenowimportviasftpinstallationguide-roles" id="servicenowimportviasftpinstallationguide-roles"></a>

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

| **Role**               | **Task**                                                |
| ---------------------- | ------------------------------------------------------- |
| x\_nexsa\_sftp.manager | <ul><li>Insert data in the import set tables.</li></ul> |

Depending on the existing Access Control Lists (ACLs) you have apply 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 <a href="#servicenowimportviasftpinstallationguide-otherservicenowcomponents" id="servicenowimportviasftpinstallationguide-otherservicenowcomponents"></a>

### References and choice fields <a href="#servicenowimportviasftpinstallationguide-referencesandchoicefields" id="servicenowimportviasftpinstallationguide-referencesandchoicefields"></a>

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 <a href="#servicenowimportviasftpinstallationguide-businessrules" id="servicenowimportviasftpinstallationguide-businessrules"></a>

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.

<figure><img src="/files/oodDFBVlQSlD6LMulPIY" alt="" width="544"><figcaption></figcaption></figure>

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 <a href="#servicenowimportviasftpinstallationguide-transformscripts" id="servicenowimportviasftpinstallationguide-transformscripts"></a>

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 |

## ServiceNow import via SFTP installation - Initial configuration <a href="#servicenowimportviasftpinstallationguide-servicenowimportviasftpinstallationinitialconfiguration" id="servicenowimportviasftpinstallationguide-servicenowimportviasftpinstallationinitialconfiguration"></a>

### Application installation process <a href="#servicenowimportviasftpinstallationguide-applicationinstallationprocess" id="servicenowimportviasftpinstallationguide-applicationinstallationprocess"></a>

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**.

### Role assignment <a href="#servicenowimportviasftpinstallationguide-roleassignment" id="servicenowimportviasftpinstallationguide-roleassignment"></a>

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 (Compute&#x72;*,* Softwar&#x65;*,* 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]

{% file src="/files/SwOj3MhkUx8IZL2RnZBB" %}

### Cross-scope permissions <a href="#servicenowimportviasftpinstallationguide-cross-scopepermissions" id="servicenowimportviasftpinstallationguide-cross-scopepermissions"></a>

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:

{% hint style="danger" %}
*\[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.*
{% endhint %}

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:

<figure><img src="/files/0HvBEM8C6SoGhQZxNqYq" alt=""><figcaption><p>Application Access permissions</p></figcaption></figure>

### Data Source Configuration <a href="#servicenowimportviasftpinstallationguide-datasourceconfigurationdata_source_configuration" id="servicenowimportviasftpinstallationguide-datasourceconfigurationdata_source_configuration"></a>

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](#servicenowimportviasftpinstallationguide-customtableinventorycustom_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.

<figure><img src="/files/ZxQLo6Sq0YU641uSQgDB" alt=""><figcaption><p>Data Source form</p></figcaption></figure>

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: “,“)      |

## ServiceNow import via SFTP installation - Optional configuration <a href="#servicenowimportviasftpinstallationguide-optionalconfiguration" id="servicenowimportviasftpinstallationguide-optionalconfiguration"></a>

### Transform maps Configuration <a href="#servicenowimportviasftpinstallationguide-transformmapsconfiguration" id="servicenowimportviasftpinstallationguide-transformmapsconfiguration"></a>

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.

<figure><img src="/files/mL6OCErMJyeWxdMGQw9V" alt=""><figcaption><p>Field Maps detail</p></figcaption></figure>

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*.

<figure><img src="/files/Wgcy8fTZpO3Ox2cm9hAD" alt=""><figcaption><p>Source Script example</p></figcaption></figure>

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

* [Creating a Field Map | ServiceNow](https://docs.servicenow.com/bundle/tokyo-platform-administration/page/script/server-scripting/task/t_CreatingAFieldMap.md)
* [Mapping Options | ServiceNow](https://docs.servicenow.com/bundle/tokyo-platform-administration/page/script/server-scripting/concept/c_MappingOptions.md)

### Scheduled Import Configuration <a href="#servicenowimportviasftpinstallationguide-scheduledimportconfiguration" id="servicenowimportviasftpinstallationguide-scheduledimportconfiguration"></a>

As explained in the [Scheduled Import](#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.

<figure><img src="/files/dBcRjPF3up86uF0tG70Y" alt=""><figcaption><p>Scheduled Import configuration</p></figcaption></figure>

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](https://docs.servicenow.com/bundle/tokyo-platform-administration/page/administer/import-sets/task/t_ScheduleADataImport.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/data-exporters/exporter-for-secure-file-transfer-protocol-sftp-server/cmdb-import-from-sftp-into-servicenow/servicenow-import-via-sftp-installation-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.