ServiceNow CMDB

1. About this document

This document provides step-by-step instructions to configure SAFE Asset connector in ServiceNow portal.

2. Introduction

The integration of SAFE with ServiceNow CMDB allows SAFE users to enhance the metatdata of onboarded asset data. SAFE integration with ServiceNow CMDB allows synchronization of assets' metadata that are already onboarded in the SAFE platform. This asset metadata helps in smart group creation in SAFE to model Business Units or Applications.

The integration maps key asset attributes between SAFE and ServiceNow CMDB, ensuring consistency in onboarded assets' metadata for standard or custom attributes. Based on a predefined schedule/triggers in ServiceNow CMDB, the assets' metadata is periodically updated in SAFE One.

3. Prerequisites

3.1 Get SAFE Asset Connector application from ServiceNow store

• Log in to ServiceNow:

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

• Navigate to the ServiceNow Store:

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

• Search for SAFE Asset Connector:

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

• Select the SAFE Asset Connector Application:

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

• Click "Get" or "Request":

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

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

• Review Installation Requirements:

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

• Install the Application:

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

• Verify Installation:

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

• Configure the Application:

  • Proceed with the configuration steps detailed in the next section.

3.2 Pre-requisites for configuring the application

To configure SAFE Asset Connector application, you need the following details:

• The CI tables along with its configuration, that should be synced to SAFE ONE (A sample JSON is present as a default value) → The configuration includes parameters like:

  • ciTableName  →  Table Name against which the SAFE assets have to be mapped.

  • encodedQuery → To avoid asset matching against the whole data and use only a particular set, we can apply filter in the form of encodedQuery.

  • matchingCriteria → This field is used to define the matching criteria for the assets.

  • attackSurfaceLevelMatchingCriteria → If you want to override the matching criteria for a particular Attack Surface.

  • applicableAttackSurface → This contains the list of applicable attack surface for which the data to be synced.

[
  {
    "ciTableName": "cmdb_ci",
    "encodedQuery": "sys_updated_onONToday@javascript:gs.beginningOfToday()@javascript:gs.endOfToday()",
    "matchingCriteria": [
      {
        "serviceNowField": "name",
        "safeField": "name"
      }
    ],
    "attackSurfaceLevelMatchingCriteria": {
      "Endpoint": [
        {
          "serviceNowField": "name",
          "safeField": "name"
        }
      ]
    },
    "applicableAttackSurface": [
      "Endpoint",
      "Server",
      "SaaS",
      "Application",
      "Storage",
      "Cloud",
      "Network",
      "People",
      "Perimeter Services",
      "Others",
      "IoT",
      "OT"
    ]
  }
]

• Applicable SAFE ONE attack surface types for sync → SAFE One classifies assets into different attack surfaces namely Server, Cloud, Endpoint, SaaS, Network, Storage, Application, Others, IoT, OT, People and Perimeter Services.

• CI tables along with CI field mappings (A sample JSON is present as a default value) → The configuration includes parameters like:

  • ciTableName → The name of the cmdb ci table.

  • nonDefaultFieldMappings → The fields which are present as custom fields in SAFE.

  • safeField → The name which is provided here should have a corresponding custom field with the same name in SAFE.

  • defaultFieldMappings  → The entities which are directly linked to the asset in SAFE like department, location, ipAddress etc.

[
  {
    "ciTableName": "cmdb_ci",
    "nonDefaultFieldMappings": [
      {
        "serviceNowField": "fault_count",
        "safeField": "Fault Count"
      },
      {
        "serviceNowField": "short_description",
        "safeField": "CMDB Description"
      },
      {
        "serviceNowField": "serial_number",
        "safeField": "Serial Number"
      }
    ],
    "defaultFieldMappings": [
      {
        "serviceNowField": "location",
        "safeField": "locationId",
        "serviceNowFieldRelationship": {
          "tableName": "cmn_location",
          "columnName": "name"
        }
      },
      {
        "serviceNowField": "department",
        "safeField": "departmentId",
        "serviceNowFieldRelationship": {
          "tableName": "cmn_department",
          "columnName": "name"
        }
      },
      {
        "serviceNowField": "ip_address",
        "safeField": "ipAddress",
        "serviceNowFieldRelationship": {
          "tableName": "cmdb_ci",
          "columnName": "ip_address"
        }
      },
      {
        "serviceNowField": "fqdn",
        "safeField": "fqdn",
        "serviceNowFieldRelationship": {
          "tableName": "cmdb_ci",
          "columnName": "fqdn"
        }
      }
    ]
  },
  {
    "ciTableName": "cmdb_ci_2",
    "nonDefaultFieldMappings": [
      {
        "serviceNowField": "sys_class_name",
        "safeField": "CMDB Class"
      },
      {
        "serviceNowField": "short_description",
        "safeField": "CMDB Description"
      }
    ],
    "defaultFieldMappings": [
      {
        "serviceNowField": "location",
        "safeField": "location"
      },
      {
        "serviceNowField": "department",
        "safeField": "department"
      }
    ]
  }
]

For nonDefaultFieldMappings to be seen in SAFE a corresponding Multi-Valued Custom Field of type 'Any' needs to be created in SAFE. Refer to create custom field in SAFE One.

To handle cases where the mentioned cmdb table in the json only contains a reference, but the actual value is present in another table, please provide the service relationship as follows:-

{  "serviceNowField": "location",  "safeField": "locationId",  "serviceNowFieldRelationship":  {  "tableName": "cmn_location",  "columnName": "name"  }  }

• Get CI Relationships as Custom Field → This checkbox configuration enables the SAFE Asset Connector to import the parent or child CI name from ServiceNow CIs as custom fields in SAFE One

• Encoded Query for CI Relationships → This text field allows users to specify an encoded query to filter relationships in the cmdb_rel_ci table. Only relationships matching this query will be queried, and the parent or child CI name will be populated in the respective custom field of an asset

Encoded Query for CI Relationships

By default, this field applies the following filter:

• Type is "Runs on::Runs" or

• Type is "Used by::Uses" or

• Type is "Hosted on::Hosts" or

• SAFE ONE API Base URL → SAFE One instance URL (e.g. https://us.safeone.ai/ )

• SAFE ONE API Username and SAFE ONE API Password  →  Refer to generating SAFE API Credentials

4. Configure the SAFE Asset Connector Application

To configure SAFE Asset Connector application in ServiceNow:

1. Search for SAFE Asset Connector in the ServiceNow portal.

2. In the application menu, select Configure.

3. Enter the mandatory values (refer the pre-requisites required for configuring the application for more details)

4. Click Save.

5. Confirm that a message appears stating Properties updated.

5. Sync SAFE Asset Connector

To Sync ServiceNow CMDB into SAFE via SAFE Asset connector:

1. Search for SAFE Asset Connector in the ServiceNow portal.

2. In the SAFE Asset Connector application menu, select Sync CMDB CIs.

3. Click the Sync CIs to SAFE One button.

4. A progress bar will be displayed, indicating the progress of sync.

5. Once the progress bar reaches 100%, a pop-up window will display with Sync completed.

6. View Sync History

1. Search for SAFE Asset Connector Plugin in the ServiceNow portal.

2. In the SAFE Asset Connector application menu, click on Sync History Table.

3. You will see Sync History table that provides a comprehensive overview of sync history.

   Open image-20240821-131848.p

7. View Results

Once the SAFE Asset Connector application is configured and sync, the updated asset’s meta data can be seen in SAFE One.

Currently, we have a hard to limit to sync max 100K assets from ServiceNow CMDB into SAFE One

8. FAQs

1. What is encodedQuery and how is it used?

The encodedQuery field is used to apply filters on the assets, ensuring only a specific set of data is synced between ServiceNow CMDB and SAFE, instead of matching all data.

2. How to find encodedQuery for filtering CIs in ServiceNow?

To find the encodedQuery for filtering Configuration Items (CIs) in ServiceNow, follow these steps:

1. Open the desired CI table in ServiceNow (e.g., the cmdb_ci table).

2. Apply the required filters using the filter conditions available in the UI (e.g., filtering by name, location, status, etc.). Ref

3. Once the filters are applied and the results are displayed, inspect the URL of the current page.

4. Look for the query parameter sysparm_query in the URL. The value assigned to this parameter is the encodedQuery.

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

3. How many assets can be synced from ServiceNow CMDB into SAFE One?

There is a hard limit to sync max 100k assets from ServiceNow CMDB into SAFE One.

4. What permissions are required to configure and run the SAFE Asset Connector?

Admin-level privileges in both ServiceNow and SAFE to configure the integration, install the SAFE Asset Connector, generate API credentials in SAFE One and run the sync. Ensure that the ServiceNow user account used for sync has read access to the CI tables.

5. How do I troubleshoot sync errors in the SAFE Asset Connector?

Check the ServiceNow logs for any error messages related to the SAFE Asset Connector. Verify that all required fields are properly mapped, the API credentials are correct, and that the integration is configured according to SAFE's prerequisites.

6. How often is the asset metadata updated between ServiceNow and SAFE One?

The asset metadata is updated based on a predefined scheduled triggers within ServiceNow CMDB, ensuring periodic synchronization. The default values are:

• Full sync → Weekly on Sunday (00:00:01 hrs)

• Partial sync → Daily (00:00:02 hrs)

1. Navigate to the Scheduled Script Executions List at <ServiceNow Portal Base URL>/sysauto_script_list.do.

2. Search for and select SAFE Asset Connector Full Sync - Cron or SAFE Asset Partial Sync - Cron

3. Modify the scheduled time and frequency as needed to fit your requirements.

7. Does SAFE Asset Connector push data back to ServiceNow?

No, the SAFE Asset Connector only reads data from the ServiceNow cmdb_ci tables for which access is granted. There is no data pushed from SAFE back into ServiceNow, ensuring that the synchronization process is read-only from the ServiceNow side

8. What does the "Get CI Relationships as Custom Field" option do?

When enabled, this option allows the connector to pull parent-child CI relationships from ServiceNow using a specified encoded query. These relationships are then stored in SAFE One as custom fields, with parent relationships in ci-parent and child relationships in ci-child.

9. How do I use the "Encoded Query for CI Relationships" field?

The Encoded Query for CI Relationships field allows you to specify a filter for which relationships are imported. Only relationships matching this encoded query from the cmdb_rel_ci table will be imported. To get an encoded query, apply filters in the ServiceNow UI and copy the sysparm_query value from the URL.

10. What if I don't configure the custom fields ci-parent and ci-child in SAFE?

If these custom fields are not configured in SAFE, the connector will be unable to populate relationship data for CIs, and the parent-child relationships defined by the encoded query will not appear in SAFE.

11. Can I import relationships without enabling "Get CI Relationships as Custom Field"?

No, this option must be enabled to pull and store CI relationships as custom fields in SAFE. Without it, the encoded query for CI relationships will not apply, and no relationships will be imported.