ServiceNow Service Graph

Platform

The Service Graph connector for runZero allows you to bring runZero assets into your ServiceNow CMDB as CIs, and optionally periodically update the CIs with fresh information from runZero scans.

The Service Graph Connector fetches and transforms data using ServiceNow IntegrationHub ETL, and passes it through the Identification and Reconciliation Engine (IRE). This allows specific fields and CI class mappings to be fine-tuned from the ServiceNow console. You can also specify a runZero search query to determine which assets get brought in by the connector.

Important notes

• There is no charge from runZero for use of the connector. However, CI resources created in CMDB by the connector will increase ServiceNow Subscription Unit consumption. CIs created by Service Graph Connectors should be charged at a lower rate than CIs created via other means; you will need to consult ServiceNow to confirm this and obtain current pricing.

• If you are a self-hosted runZero customer, you will need to set up a MID Server to enable ServiceNow to connect to your runZero console. If your console uses a self-signed TLS certificate, or a TLS certificate signed by your own internal CA, you will need to configure the MID server to accept the CA or certificate as trusted. For more information, see ServiceNow Knowledge Base article KB0863673.

• While the Service Graph Connector is packaged and available from the ServiceNow Application Store, setting up connectors to integrate with your existing ServiceNow configuration is unlikely to be a one-click operation. You are strongly advised to have a ServiceNow Consulting and Implementation partner available to assist with the process.

Prerequisites

To use the Service Graph connector for runZero, you need the following:

• A Platform license for runZero.
• A ServiceNow ITOM license including ITOM Discovery and ITOM Visibility.
• Integration Commons for CMDB installed.

The ServiceNow dependencies are checked as part of the connector installation process.

Installation

The first step of the installation is to locate the Service Graph connector for runZero in the ServiceNow Application Store, and follow the usual process to install it into your ServiceNow instance.

The Service Graph connector adds a new menu entry Service Graph connector for runZero to the ServiceNow main menu. The module contains entries for Setup, Data Sources, Scheduled Imports, Support, and System Import Sets. You must have the admin role in ServiceNow to configure the connector.

Setup

The Setup menu offers a Guided Setup process to help you get up and running with the connector. There are three main stages to the setup process:

1. Configure the connection
2. Configure the mappings (optional)
3. Confgure the scheduled import (optional)

Step 1: Configure the connection

Configuring the connection consists of two steps: entering a runZero API key as credentials, and configuring connection options.

Entering the API key

The connector can use a runZero Organization API or Export API key. In either case, you can obtain the key by going to the Organizations page in runZero and clicking on the organization containing the assets you want to bring into ServiceNow CMDB. Organization tokens begin with OT, export tokens begin with ET.

In the API Key Credentials form, paste the runZero token into the field labeled API Key, and click Update.

Configuring connection options

For runZero cloud users, the default HTTP connection options should be correct.

You can optionally add a Search string to the Attributes for the connection at the bottom of the form. If you do, this search will be passed to runZero to determine the set of assets to bring in to CMDB via the connector. Any search string should be in runZero search query format. You are strongly encouraged to test your search string in your runZero asset inventory.

The Connection alias and Base path fields should be left as-is. (The connection alias groups together the connection settings and the API key credentials for the connector to use.)

If you are self-hosting runZero, the connection options form is where you configure the MID server to use and specify the URL of your runZero console. Your console’s fully-qualified hostname should be placed in the Host field. The hostname should match the hostname in the console’s TLS certificate in order for the MID server to trust it, even if the TLS certificate is trusted by the MID server. Check the Use MID server box and select the MID server to use.

Step 2: Configure the mappings (optional)

The second step of setting up the connector allows you to customize the mapping of runZero data to CI classes, using the IntegrationHub ETL Transform Map Assistant.

This stage can be skipped if you do not have special requirements for data mapping.

Step 3: Configure the Scheduled Import (optional)

The third step of setting up the connector is to set up a schedule for data import. Initially, you will want to test the connector setup with a one-off import. Once everything is configured correctly, you can create recurring imports.

Scheduled imports are configured as regular ServiceNow tasks. This step can be skipped if you don’t want to set up a scheduled import at this time.

Notes on data mapping

The object data models for ServiceNow CMDB and runZero are not an exact match. Some runZero data does not fit in any standard attributes available in CMDB, and in other cases runZero does not have data that CMDB expects. Review this list to understand how the connector will map runZero attributes to ServiceNow CMDB attributes:

• IP addresses: ServiceNow CIs have an attribute which takes a single IP address. The connector places the first IP address in the CI attribute IP Address. The remaining addresses are created as IP Address CIs owned by the device CI. Each IP Address CI is given a Description indicating whether it has been scanned by runZero or not. Note: By default, ServiceNow does not show IP addresses owned by a device CI. It only shows IP addresses owned by a network adapter CI which is owned by the device CI. This is a known limitation of ServiceNow’s default CMDB forms. runZero doesn’t associate IP addresses with network adapters because the necessary information isn’t generally known. In that situation, the CMDB connector development guide states that the IP addresses should be associated with the device CI.
• Names: ServiceNow CIs have a single Name attribute, while runZero assets can have any number of names with runZero attempting to guess which are the best names and put them at the front of the list. The connector places the first name in the CI Name attribute. The first name which looks like a fully-qualified domain name is placed in the Fully qualified domain name attribute, and is used to compute a DNS Domain for CIs descended from Network Gear. The full list of names is placed in the Description attribute for reference.
• Serial numbers: ServiceNow CIs have an attribute which takes a single serial number. The connector picks the first serial number for the Serial Number attribute, and then also performs a Serial Number Lookup operation to add the complete list of serial numbers with their associated type.
• Tags: runZero assets can have any number of tags, which are either single tags such as tag_name, or tags with values in the format tag=value. These are placed in the Key Value class, and this class is then associated with the Hardware class.
• MAC addresses/Network Adapters: As with IP addresses, ServiceNow has both a single-value MAC Address attribute, and an option to look up named MAC addresses to create Network Adapter objects. A runZero asset can have any number of MAC addresses, but since runZero does not run agent software on the scanned systems, it has no way to know the interface name associated with a given MAC address. The first MAC address is imported as the MAC Address attribute, and the entire set is imported via lookup as Network Adapter objects, with each being given a name made up by the MAC address and IP address (e.g. 00:00:00:00:00:00-127.0.0.1) or the MAC address and hostname if the IP address is not available (e.g. 00:00:00:00:00:00-hostname). If neither the IP address or hostname are available, the MAC address alone is used as the network adapter name. In some cases, runZero may not know the MAC address(es) of an asset. In this case, a zero MAC address (00:00:00:00:00:00) is added to satisfy ServiceNow requirements for some CI classes.
• Sites: runZero sites represent distinct networks, which may or may not correspond to physical sites. They are imported as CMDB Network Site objects.
• Organizations: The runZero organization has no obvious corresponding attribute in network hardware CIs. The organization name is incorporated into the Description of CIs.
• SNMP data: The snmp.sysDesc attribute from runZero, if it exists, is also placed in the Description.