ServiceNow CMDB (Asset Connector)

About this document

This guide outlines the end-to-end process of configuring the ServiceNow Asset Connector within SAFE. The connector helps you pull asset metadata from ServiceNow's CMDB and sync it with SAFE to enrich your asset context.

Introduction

SAFE integrates with ServiceNow by ingesting metadata for matching scoped assets from the cmdb_ci table and related CMDB tables.

Notes

The number of signals created may differ from the assets synced, as this connector only updates metadata and does not onboard them — hence, some signals may not appear as asset in SAFE.

Prerequisites

• SAFE Admin Access

• Servicenow Admin Access

• Required User Inputs:

  • Encoded Query

  • Fields to Sync

  • SAFE API URL, API Username and Password (Refer to Accessing SAFE APIs)

• Required Scope:

  • Organization - Read

  • Member - Read

Get SAFE Asset Connector application Store

1. Open your ServiceNow instance and log in with an account that has admin privileges.

2. In the application navigator, type "Store" and click on ServiceNow Store to open the store page.

3. In the search bar of the ServiceNow Store, type "SAFE Asset Connector" and press Enter.

4. Find the SAFE Asset Connector in the search results and click on it to view the application details.
   

5. Click "Get" or "Request":

6. If you have access to install the app directly, click the "Get" button.

7. If you need approval from your ServiceNow admin, click "Request" to submit a request.

8. Check for any prerequisites listed on the application page, including required roles or dependencies.

9. Follow the prompts to install the application into your instance.

10. After installation, go to the Application section in the ServiceNow instance and search for SAFE Asset Connector to ensure it's installed.

Open image-20240921-121352.png

Choose Asset Matching Criteria

You can define custom criteria to match assets between ServiceNow and SAFE. This configuration ensures that metadata is associated with the correct assets in SAFE.

On the SAFE Asset Connector configuration page, the Asset Matching Criteria field allows you to define this logic.

You must provide an array of ServiceNow field names (strings). The connector will attempt to match assets using the fields in the order provided — from highest to lowest priority (left to right).

In this example, SAFE will first attempt to match using fqdn. If no match is found, it will try name. Ensure the fields you provide exist in both SAFE and ServiceNow to ensure proper matching.

Create Encoded Query

To avoid syncing every record from the CMDB, SAFE allows you to filter which assets should be synced by using ServiceNow’s encodedQuery format. This helps narrow down data to only those assets that are relevant to your security posture in SAFE.

You will generate this query by applying filters in the ServiceNow UI, which will automatically build the encoded query string behind the scenes.

For configuring the encoded query follow the given steps:

1. Click on All, and search for cmdb_ci.list and then press enter.
   

2. The system displays the cmdb_ci table view in ServiceNow.
   

3. Click the Filter icon at the top of the table to open the filter editor.  

4. Apply your desired filters (e.g., Class = Server, Manufacturer = Dell, etc.).  Click Run to apply the filter.
   

   Result: The table will now only show records matching your filter criteria.

5. Once the filters are applied and the results are displayed, inspect the URL of the current page. Look for the query parameter sysparm_query in the URL. The value assigned to this parameter is the encodedQuery.

6. Copy this value, as it represents the filter logic you applied in the UI in an encoded form.

7. Now return to the SAFE Asset Connector Configuration page. Locate the field labeled Encoded Query (typically the second field on the form).
   

8. Copy and Save the value you copied from the ServiceNow URL to use while configuring the Asset Connector. This encoded query will control which CMDB records get synced into SAFE.

Generate Configuration for Fields to Sync

If you're migrating from an earlier version of the connector and have a backup of your configuration, you can paste it directly into the Fields to Sync field.  

Go to any json beautifier to avoid any confusions while creating configuration. (Example: Json Beautifier - Json Formatter)

SAFE Field Mapping Overview

The configuration JSON includes two keys:

• defaultFieldMappings – for predefined fields in SAFE.

• nonDefaultFieldMappings – for custom fields you've added to SAFE.

List of predefined fields in SAFE

• ipAddress

• region

• internetFacing

• sourceName

• criticalityId

• departmentName

• designationName

• locationName

• fqdn

• cmdbId

• platform

By default the connector ships with the following configuration:

[
  {
    "nonDefaultFieldMappings": [],
    "defaultFieldMappings": [
      {
        "serviceNowField": "ip_address",
        "safeField": "ipAddress"
      },
      {
        "serviceNowField": "fqdn",
        "safeField": "fqdn"
      },
      {
        "serviceNowField": "location",
        "safeField": "locationName"
      },
      {
        "serviceNowField": "internet_facing",
        "safeField": "internetFacing"
      }
    ]
  }
]

Default Fields Mapping

Let’s take an example with the departmentName field which is a predefined field in SAFE to have more clarity.

To map the ServiceNow department field to SAFE’s departmentName:

1. Go to cmdb_ci (or any table where this column resides) and click on any record. You might see a window like this.
   

2. Right Click on the highlighted button and click on show XML. You will find a new window opened. Search for the field that you want to sync into SAFE. (Example: departmentName)
   

   The tag is basically your servicenow field.

3. Now in your configuration JSON, we can write the mapping as given below:
   

   Now the asset connector will pick department column from cmdb_ci table and link it with the default field departmentName in SAFE

Non-Default (Custom) Field Mappings

Use nonDefaultFieldMappings when you want to bring in additional data that isn't part of SAFE's predefined fields. These custom fields must first be created in SAFE, then mapped to corresponding fields in ServiceNow. Refer to Custom Fileds.

• In the Servicenow CMDB, Identify the corresponding column in ServiceNow that should be mapped to this custom field.

• In this case we need to pick the asset_tag column which is already present in CMDB (you can create the column and extract the actual column name too).

• Go to the ci_record for which you want to extract the asset_tag and click on Show XML.
  

• Get the column name from the XML. asset_tag in this case.
  

• Map both the things in the configuration under nonDefaultFieldMappings section. The final configuration will look like this.
  

Configuring Parent Child Relationship in CMDB

In ServiceNow’s CMDB, parent-child relationships represent how assets (Configuration Items or CIs) depend on or relate to each other — such as a server hosting an application.

These relationships provide valuable context around asset dependencies and are useful for risk assessment in SAFE.

How it works in SAFE?

When you enable the “Get CI Relationships as Custom Fields” option in the SAFE Asset Connector:

1. The connector will sync only one direct parent and one direct child for each CI, based on your CMDB relationship query.

2. These relationships are stored as custom fields in SAFE, enriching asset metadata with upstream/downstream context.

Only assets included in the primary CMDB encoded query will be considered. If either the parent or child is excluded, the relationship will not be captured.

Steps to configure parent-child relationship

1. Click on All and type cmdb_rel_ci.list to navigate CMDB Relationship table. This opens the CMDB Relationship [cmdb_rel_ci] table, which defines relationships between Configuration Items (CIs).

2. Click the Filter icon at the top of the table.

3. Apply filters to narrow down to relationships you want to sync (e.g., "Parent Class = Server" and "Child Class = Application").  The goal here is to capture the relationships that are relevant to your asset sync logic.  
   

4. Click Run to execute the filter.  
   

5. After the filtered results are shown, inspect the browser URL.  Find the sysparm_query parameter.  

6. Copy the value of sysparm_query — this is the encoded query representing your filter logic.

7. Go to the SAFE Asset Connector configuration page.  

8. Enable the option that says "Get CI relationships as custom fields ".  

9. Paste the copied encoded query into the CI-Parent Encoded Query field.  This allows the connector to sync CI relationships using the logic you defined in ServiceNow.

Make sure your relationship filter only includes assets that are also included in your earlier cmdb_ci encoded query — otherwise, SAFE may not resolve the relationship if one side of the pair wasn't synced.

Update the configuration with your SAFE Credentials

To push data from ServiceNow to SAFE, the connector needs valid API credentials with appropriate access. You’ll create these credentials in SAFE and input them in the connector configuration.

Generate API Credentials from SAFE

Refer to Accessing SAFE APIs

1. Go to your SAFE and click Settings > API Credentials.

2. Click the Add API Credential and enter your API Key name and the expiry period and then click Add.

3. You will find your credentials generated. Make sure to securely copy and store your credentials. They may not be retrievable later.

4. Now go to SAFE Asset Connector’s configure page in ServiceNow and add your credential.
   

5. Click the Save button.

Test the Connector

After completing all configuration steps, it's important to test the connector to ensure it can successfully connect to both ServiceNow and SAFE.

1. Go to application menu and search for SAFE Asset Connector and then click on Sync CMDB CIs.

2. Click on the Test Connector button.
   

3. Success Message: Indicates that the connector is properly configured and ready to sync.
   

4. Once the test is successful, you’re ready to perform a full sync.

Sync

Once the connector test is successful, you’re ready to initiate a sync to pull asset metadata from ServiceNow into SAFE.

1. Click the Sync button.
   

2. The connector will start processing:

   1. Filtering assets based on your encoded query

   2. Mapping ServiceNow fields to SAFE fields

   3. Pulling one direct parent and one direct child relationship per CI (if enabled)

   4. Pushing the resulting metadata into your SAFE environment

What Happens After Sync

1. The mapped metadata appears in SAFE under the corresponding assets.

2. Relationships (if configured) are added as custom fields.

3. Any assets not matched to existing SAFE assets will not generate signals (metadata only).

This sync does not onboard new assets—it only enriches metadata for assets already present in SAFE.

History

SAFE Asset Connector keeps a detailed record of all sync actions—whether triggered manually or via scheduled jobs.

1. In order to view history table, under SAFE Asset Connector, click on Sync History Table.

2. You will see all the actions triggered by you or by the cron jobs here.