ServiceNow CMDB Data Synchronization
Overview
The Rapid7 InsightVM Integration for CMDB is a ServiceNow Platform application that provides end-to-end configuration management integration with capabilities to automate:
- InsightVM Asset Tagging
- Tag InsightVM assets based on ServiceNow CMDB CI data
- ServiceNow Asset Import
- Creation and updating of ServiceNow CMDB CI data based on InsightVM asset data including asset vulnerability and risk related metrics
- InsightVM Site Configuration
- Manage InsightVM site scopes based on ServiceNow CMDB CI data
Get Started
Installation
The application can be installed by a ServiceNow instance administrator from the ServiceNow Store:
Initial Setup
Install the Configuration Management for Scoped Apps CMDB (com.snc.cmdb.scoped) plugin
The ServiceNow Asset Import functionality of the application utilizes the Configuration Management for Scoped Apps CMDB (com.snc.cmdb.scoped) plugin. Follow the below steps to install it within a ServiceNow instance:
- As a ServiceNow instance administrator, go to the System Definition -> Plugins module:

- From this module, search for the
Configuration Management For Scoped Apps CMDB (com.snc.cmdb.scoped)
plugin, click Install.

- Click Activate.

Create an ‘InsightVM’ Discovery Source
The application requires a custom discovery source to be created for easy identification of assets that are imported/updated by the integration.
- As a ServiceNow instance administrator, go to the System Definition -> Scripts - Background module.

- Ensure that the Scope in the module is set to
Global
. - Run the following script snippet to create the ‘InsightVM’ discovery source:
text
1var discoverySource = 'InsightVM';2var gr = new GlideRecord('sys_choice');3gr.addQuery('element', 'discovery_source');4gr.addQuery('name', 'cmdb_ci');5gr.addQuery('value', discoverySource);6gr.query();7if (!gr.hasNext()) {8var grNew = new GlideRecord('sys_choice');9grNew.initialize();10grNew.setValue('element', 'discovery_source');11grNew.setValue('name', 'cmdb_ci');12grNew.setValue('value', discoverySource);13grNew.setValue('label', discoverySource);14if (!grNew.insert()) {15gs.info('Adding discovery source failed for: ' + discoverySource);16}17}
Source
https://community.servicenow.com/community?id=community_blog&sys_id=7e3fb6d5db5afb00fece0b55ca9619e3
Create an InsightVM Connection
To establish connectivity to your InsightVM Security Console(s), the application uses an InsightVM Connection configuration. To configure one, follow the below steps:
- Begin by creating an InsightVM user account for the application
- The user needs access to All Sites and All Asset Groups, along with the following permissions: Manage Sites, Manage Tags, View Group Asset Data, Create Reports.
TIP
For additional information on creating users, review the following documentation section:
- With the user created, navigate to the Rapid7 InsightVM Integration for CMDB -> InsightVM Connections module.

- Click New to create a new InsightVM Connection configuration.
- Enter a user friendly name for the connection.
- Complete the remainder of the form and click Submit.
ServiceNow MID Server configuration required
If you do not have a ServiceNow MID Server configured, search for the MID Server Installation module for instructions on installation and configuration of a ServiceNow MID Server. The MID server should be installed with network accessibility to the web interface of the InsightVM Security Console host.
To ensure reliable operation of the integration, the MID server should be located in the same network region as the InsightVM Security Console. For example if the InsightVM Security Console is in the US, the MID server should also be located in the US.

An example InsightVM Connection configuration is shown below:

Required Roles
In order to use the application, you will need to be a ServiceNow admin, or have one of the roles provided by the application assigned to your user:
x_r7_rapid7_cmdb_i.integration_admin
- Access to all application modules
x_r7_rapid7_cmdb_i.asset_tagging_user
- Access to all InsightVM Asset Tagging integration modules
x_r7_rapid7_cmdb_i.asset_import_user
- Access to all ServiceNow Asset Import integration modules
x_r7_rapid7_cmdb_i.site_configuration_user
- Access to all InsightVM Site Configuration integration modules
Configuration
Each integration available in the application has three modules provided:
- Jobs
- Individual integration configurations with scheduling options to specify how frequently the configuration is run.
- Maps
- Individual configuration for the job. Each integration job can contain a list of maps. Details for each map type are provided in the configuration documentation for the corresponding integration.
- Run Statistics
- High level statistics provided from each job execution for an integration.
InsightVM Asset Tagging
The InsightVM Asset Tagging integration provides capabilities to tag InsightVM discovered assets with data from ServiceNow CMDB CI (Configuration Item) records. This can be used to provide context on InsightVM assets for data such as location, business owner, and any other fields that are available in the ServiceNow CMDB.
Tags created by the integration are managed end-to-end by the integration, meaning that they are created, updated, and optionally deleted each time an integration job runs.
Jobs
Each InsightVM Asset Tagging integration job contains the following configuration options:
Field | Description |
---|---|
Name | Friendly name for the integration job configuration |
InsightVM Connection | InsightVM Connection to use for InsightVM requests (asset/tag data report generation and tagging operations) |
Tag Prefix | Prefix for tags managed by the integration. Only tags with this prefix will be updated by the integration. |
Tag Name Maps | Tags to be created from CMDB CI data. Each tag includes a CMDB CI table selection, a field whose value will be the suffix of a tag name, and a type for the tag. |
Delete Empty Tags | Whether tags with the defined tag prefix should be deleted if no assets are associated with the tag. |
InsightVM Scope | Comma-delimited regular expression patterns for names of InsightVM sites, tags, and asset groups to include in the scope for tagging. |
Schedule | Frequency for tagging to run. Should not be scheduled so frequently that the integration is running multiple times simultaneously. |
An example job configuration is shown below:

Tag Name Maps
Tag Name Maps are used to define which tags are created/updated by the Asset Tagging feature. For each InsightVM asset in scope for a particular integration job, a CMDB CI lookup is performed against the table specified in the tag configuration. If CMDB CIs are found, the field values from each CI are used to create/update tags with the following format: [TAG PREFIX][FIELD VALUE]
.
The display name for the Tag Name Map is dynamically generated based on the configuration with the following format: [Table].[Field]:[Type]
. Default Tag Name Map configurations included with the application are as follows:
- cmdb_ci_computer.assignment_group.name:owner
- cmdb_ci_computer.location.name:location
- cmdb_ci_computer.owned_by.name:owner
- cmdb_ci_computer.sys_class_name:custom
Field | Description |
---|---|
Table | Table containing CMDB CIs for the tag. |
Filter | Filter to limit the scope of the CMDB CI search for the tag. |
Field | Field whose value will be used for creating/updating InsightVM Tags and associated with assets matching the CI. |
Type | Type for the tag |
Lookup Fields | Fields used when searching for matching CIs based on InsightVM data. InsightVM data retrieval includes the asset's host name, IP address, and MAC address. |
IP Address Field | Field used to search for CIs based on an asset's IP address. |
MAC Address Field | Field used to search for CIs based on an asset's host name. |
Host Name Field | Field used to search for CIs based on an asset's host name. |
An example of a Tag Name Map configuration is shown below:

Run Statistics
Run statistics are logged with each run of the InsightVM Asset Tagging integration. Statistics include the following details:
- Start
- Date and time when an integration job begins
- End
- Date and time when an integration job ends. In the event that an integration job run fails, field will be empty until it is updated by the next integration job run.
- Tags created
- Number of tags created based on Tag Name Map configurations and ServiceNow CMDB CI field data
- Tags updated
- Number of tags with updated associations from the run
- Note: Tags are updated each run, even when no changes are required. Tags are bulk updated, meaning that only one request is made for each tag asset association updated during an integration job run.
- Tags deleted
- Number of tags with the defined integration prefix deleted during the integration job run due to there no longer being assets associated with the tag
- Note: Tag deletion only occurs if the ‘Delete Empty Tags’ option is enabled in the InsightVM Asset Tagging job configuration.
- Tagged assets
- Number of unique InsightVM assets tagged during the integration job run.
- Unmatched assets
- Number of assets for which no matching CIs were identified during the integration job run.
InsightVM Site Configuration
The InsightVM Site Configuration integration provides the capability to create and update InsightVM sites with site names based on ServiceNow CMDB CI data and scopes including the IP address and/or host name from CIs with those field values.
For example, with a Site Name Map of [company.name]-[location.name]
and a CI record with a Company Name of ‘Rapid7’ and Location Name of ‘Boston’, the resulting InsightVM site would be sn_Rapid7-Boston
(when using the default Site Name Prefix). Each additional asset returned by the configured table and filter for the Site Name Map would have its IP address and/or hostname added to the scope for that site.
Jobs
Each InsightVM Site Configuration integration job contains the following configuration options:
Field | Description |
---|---|
Name | Friendly name for the Site Configuration job record |
InsightVM Connection | InsightVM Connection to use for InsightVM requests (site operations) |
Site Name Prefix | Prefix for sites managed by the integration. Only sites with the defined prefix will be updated by the integration. |
Site Name Maps | List of Site Name Maps (table and field list values) from which InsightVM sites will be created. Up to five field values may be used. |
Delete Empty Sites | Whether sites without assets in their scope should be deleted. New sites with no scope during after processing of all CI records will not be created. |
Schedule | Frequency for site configuration to run. Should not be scheduled so frequently that the integration is running multiple times simultaneously. Recommendation: Daily during an hour of the day with minimal InsightVM scanning in progress. |
Below is an example InsightVM Site Configuration integration configuration:

Site Name Maps
Site Name Maps define which fields are used to construct the site name. Each Site Name Map can contain up to five fields on the selected table, from which the name of the site will be constructed. For example, given the following fields defined for a Site Configuration record:
- Company.name
- Location.city
- sys_class_name
With a delimiter of ‘-’, two example site names would be:
- Rapid7-Boston-cmdb_ci_linux_server
- Rapid7-Chicago-cmdb_ci_computer
One default Site Name Map is included with the application:
- company.name-location.name (cmdb_ci_computer)
Configuration details for Site Name Maps are as follows:
Field | Description |
---|---|
Table | Table containing CMDB CIs from which field values will be used for constructing site names. |
Filter | Filter to limit the scope of the CMDB CI search for the site configuration. |
Name Field (1-5) | Up to five field values used to sequentially construct the name of the InsightVM site. |
Delimiter | Delimiter to add between each field value when constructing site names. |
Empty Field Value | Value to use in the site name for the field when there is no value for the field on a CI. |
Site Scope Values | Values to include in the site scope for the sites. |
IP Address Field | Field whose value will be added to the scope of the InsightVM site. IP addresses are validated by the integration prior to including them in the scope for a site. Only IPv4 addresses are supported. |
Hostname Field | Field whose value will be added to the scope of the InsightVM site. |
Below is an example Site Name Map configuration:

Run Statistics
Run statistics are logged with each run of the InsightVM Site Configuration integration. Statistics include the following details:
- Start
- Date and time when an integration job begins
- End
- Date and time when an integration job ends.
- In the event that an integration job run fails, field will be empty until it is updated by the next integration job run.
- Sites Created
- Number of sites created during an integration job run.
- Sites Updated
- Number of sites updated during an integration job run.
- Sites Deleted
- Number of sites deleted during an integration job run.
ServiceNow CMDB Asset Import
The ServiceNow CMDB Asset Import integration provides the capability to ingest InsightVM asset data into the ServiceNow CMDB. Data imported for each asset includes:
- IP Address
- MAC Address
- Host Name
- Operating System
- InsightVM Connection Name
- Asset ID
- Risk Score
- Last Assessed for Vulnerabilities (Date and Time)
- Criticality Tag
- Vulnerability Count
- Critical Vulnerability Count
- Severe Vulnerability Count
- Moderate Vulnerability Count
IMPORTANT
Only assets which have a host name that has been discovered by InsightVM can be imported.
Columns created on the cmdb_ci_hardware table for use by this integration include:
- Rapid7 Asset ID (x_r7_rapid7_cmdb_i_rapid7_asset_id)
- Rapid7 InsightVM Connection Name (x_r7_rapid7_cmdb_i_rapid7_insightvm_connection_name)
- Rapid7 Risk Score (x_r7_rapid7_cmdb_i_rapid7_risk_score)
- Rapid7 Last Assessed for Vulnerabilities (x_r7_rapid7_cmdb_i_rapid7_last_assessed_for_vulnerabilities)
- Rapid7 Criticality Tag (x_r7_rapid7_cmdb_i_rapid7_criticality_tag)
- Rapid7 Vulnerabilities (x_r7_rapid7_cmdb_i_rapid7_vulnerabilities)
- Rapid7 Critical Vulnerabilities (x_r7_rapid7_cmdb_i_rapid7_critical_vulnerabilities)
- Rapid7 Severe Vulnerabilities (x_r7_rapid7_cmdb_i_rapid7_severe_vulnerabilities)
- Rapid7 Moderate Vulnerabilities (x_r7_rapid7_cmdb_i_rapid7_moderate_vulnerabilities)
Based on an asset's operating system value retrieved from InsightVM, specific CMDB classes can be associated with the imported asset by configuring CMDB Class Maps.
Note: If no matching CMDB Class Map is found for the asset, it will not be imported into the CMDB. To ensure that all in scope assets are imported, a wildcard CMDB Class Map can be used to assign a generic CMDB class to these records. The included Default Computer map provides this functionality.
Jobs
Each ServiceNow Asset Import integration job contains the following configuration options:
Field | Description |
---|---|
Name | Friendly name for the ServiceNow Asset Import job record |
InsightVM Connection | InsightVM Connection to use for InsightVM requests (asset data report generation) |
CMDB Class Maps | List of CMDB CI class name and operating system name regular expression patterns to use when mapping InsightVM assets to CMDI CI classes. Note that patterns are processed sequentially, with the first match being used. To ensure that non-specified operating systems are still imported, a default catch all |
InsightVM Scope | Comma-delimited regular expression patterns for names of InsightVM sites, tags, and asset groups to include to further scope the assets to import into the CMDB. |
Schedule | Frequency for asset import to run. Should not be scheduled so frequently that the integration is running multiple times simultaneously. |
An example job configuration is shown below:
CMDB Class Maps
CMDB Class Maps define case insensitive regular expression patterns used when processing InsightVM assets for import into the CMDB. When a matching regular expression pattern is found, the asset's CMDB Class is set to the one configured for the class map. In a ServiceNow Asset Import job record, CMDB Class Maps are processed sequentially, with the first match being used.
CMDB Class Map records included with the integration are as follows:
- Linux Server
- Windows Server
- Windows Workstation
- MacOS Device
- VMware
- Default Computer
Usually, CMDB Class Maps should be listed in descending order of specificity, e.g a Windows Server class map that specifies a pattern of windows server
should appear in the list before one that specifies a pattern of windows
.
If no matches are found, the asset will not be imported. As such it is recommended to have a wildcard pattern at the bottom of the CMDB Class Map list in a job record.
Details for CMDB Class Map records are as follows:
Field | Description |
---|---|
Name | Friendly name for the CMDB Class Map |
CMDB Class | CMDB Class name to assign to the imported asset when a match for the regular expression pattern is found |
Regular expression | Case insensitive regular expression pattern to test against an asset's operating system name from InsightVM |
Run Statistics
Run statistics are logged with each run of the ServiceNow Asset Import integration. Statistics include the following details:
- Start
- Date and time when an integration job begins
- End
- Date and time when an integration job ends.
- In the event that an integration job run fails, field will be empty until it is updated by the next integration job run.
- CIs Inserted
- Number of InsightVM assets identified as new (not found in the CMDB) based on lookup using the ServiceNow Identification Engine.
- CIs Updated
- Number of InsightVM assets found and updated based on lookup using the ServiceNow Identification Engine.
- CIs Deleted
- Number of CIs removed from the CMDB during the run.
- Note: This is a possible response from the Identification Engine, but the integration does not itself make requests for CI deletion.
- CIs Unchanged
- Number of InsightVM assets with an existing CI that is identical to the data provided from InsightVM.
- Identification Errors
- Number of InsightVM assets for which no matching CMDB Class Map was found.
- This could also be related to other errors during the import process for an individual InsightVM asset.
- The application logs provide details on each identification error.
- Note: If the job configuration is intentionally configured to not match all operating systems (by excluding a wildcard class map), the integration will still provide identification error statistics.
Running Integrations
Once integration job records are configured, there are two ways to run each integration:
- Defining a schedule on the job configuration for the integration
- Clicking the ‘Execute Now’ button when viewing an existing integration configuration
Note: If multiple jobs for a particular integration are configured (i.e InsightVM Asset Tagging), they should not be scheduled in a frequency that would result in overlap between the two jobs. When an integration job starts, temporary data from any running job for that integration is removed; and as such, the running job that started first will not successfully complete. Jobs for separate integrations can run concurrently without conflict.
Each integration will log its start and end to the Diagnostics -> Logs module in the application. In addition, details pertaining to the run of the integration job are also logged to the application logs. Note that some log messages may be out of order in the Logs view (even when sorting by the timestamp) when the logs were written during the same second.
InsightVM Asset Tagging Run Details
Workflow
Below is a diagram which illustrates the workflow for the InsightVM Asset Tagging integration:

Run Logs
During an InsightVM Asset Tagging integration run, the following informational logs are provided to identify specific operations performed by the integration.
Integration Start
When the integration starts, the following message is written to the application log:
1Started asset_tagging integration run
InsightVM Data Collection
The integration collects the following data from the InsightVM Security Console based on the configuration defined in the job record:
- In scope asset information
- Existing tags with the configuration integration prefix
To collect this data, two background jobs are created by the integration:
- Asset Tagging Asset Data Import Job
- Asset Tagging Tag Data Import Job
A third background job, ‘Asset Tagging Update Tags after Data Import’, checks the status of these two jobs. Once the asset and tag data has been collected by these jobs, this job begins the tag create/update/delete process.
Messages similar to the following will be logged when a background job has been successfully scheduled:
1Successfully scheduled job with name Asset Tagging Update Tags after Data Import, sys_id: 0d8451151b65441015b63335cc4bcb95
Once the job is complete, it is deleted by the integration. Jobs for InsightVM data collection will create, generate, import, and delete a report in InsightVM (once the data has been imported). Additional messages related to this process are also logged.
Tag Create/Update/Delete Process
The tagging process begins after data from the InsightVM Security Console is imported. This includes identifying which tags need to be created, which assets need to be associated with each tag, and which tags need to be deleted if the ‘Delete Empty Tags’ configuration option is enabled.
When the tagging process begins, the following message will be logged:
1Updating tag associations...
Logs related to the tagging process are as follows:
Tag Creation
For tag creation, messages similar to the following will be logged:
1Created tag with name: sn_Linux Server, type: CUSTOM
Tag Update
For tag updates, messages similar to the following will be logged:
1Adding 2 assets to tag sn_Computer2Updated tag with ID: 447
Tag Deletion
If there are tags that need to be deleted and this option is enabled, a message similar to the following will be logged to indicate the start of this process:
1Deleting 5 tags that no longer have assets
For each tag that is deleted, a message similar to the following will be logged:
1Deleting tag sn_NoMoreAssets:CUSTOM
Completion
At completion of the integration run, multiple messages related to job cleanup will be logged. In addition, the following message indicating run success will be logged:
1Finished asset_tagging integration run
InsightVM Site Configuration Run Details
Workflow
Below is a diagram which illustrates the workflow for the InsightVM Site Configuration integration:

Run Logs
During an InsightVM Site Configuration integration run, the following informational logs are provided to identify specific operations performed by the integration.
Integration Start
When the integration starts, the following message is written to the application log:
1Started site_configuration integration run
Site Creation
When a site is created in InsightVM, a message similar to the following will be logged:
1Successfully created InsightVM site with name sn_Rapid7-Boston
Site Update
When the scope of an InsightVM site is updated, a message similar to the following will be logged:
1Updated site sn_Rapid7-Boston scope with 57 addresses
Site Deletion
If there are sites with empty scopes and the ‘Delete Empty Sites’ configuration option is enabled, a message similar to the following will be logged for each site that is deleted:
1Deleted site with empty scope sn_Rapid7-Boston
Completion
At completion of the integration run, the following message indicating run success will be logged:
1Finished site_configuration integration run
ServiceNow CMDB Asset Import Run Details
Workflow
Below is a diagram which illustrates the workflow for the ServiceNow Asset Import integration:

Run Logs
During an- ServiceNow CMDB Asset Import integration run, the following informational logs are provided to identify specific operations performed by the integration.
Integration Start
When the integration starts, the following message is written to the application log:
1Started asset_import integration run
InsightVM Data Collection
The integration collects the following data from the InsightVM Security Console based on the configuration defined in the job record:
- In scope asset information
To collect this data, one background job is created by the integration:
- Asset Import Asset Data Import Job
Messages similar to the following will be logged when a background job has been successfully scheduled:
1Successfully scheduled job with name Asset Import Asset Data Import Job, sys_id: 0d8451151b65441015b63335cc4bcb95
CMDB Asset Import
As part of the Asset Import Asset Data Import Job, the report data from InsightVM is imported to a temporary integration table; and during the import process, imported into the ServiceNow CMDB.
Each InsightVM asset in the report is processed based on the CMDB Class Maps defined for the configuration which are used to identify the CMDB class to associate with the InsightVM asset. The ServiceNow Identification Engine API is then used to look up the asset based on its hostname. Where a matching CI is found using the name
field, the CI is updated. Only assets with hostnames discovered by InsightVM will be imported into the CMDB by the integration. In the scenario an additional field is required for Identification Engine lookups for the ServiceNow environment, the lookup will fail and the asset will not be imported into ServiceNow as a CMDB CI record.
Import Start
When the asset import process begins, the following message is logged:
1Beginning ServiceNow CMDB Asset Import process...
Note: To reduce the volume of log messages related to the import process, only error messages are logged during the import process. Successful CI create/update operations are not logged.
Identification Errors
Identification errors are logged by the integration. In the event that no matching CMDB Class Map is found for a particular InsightVM asset’s operating system, the asset is not imported.
To indicate that no matching CMDB Class Map was found for an asset, a message similar to the following is logged with the details:
1Failed to find an OS -> Class mapping for source data, {"ip_address":"192.168.1.1","mac_address":"00:00:00:00:00:00","name":"WindowsServer1","os":"Microsoft Windows Server 2012 R2 Standard Edition"}, cannot continue! Configuration Sys ID: d3c5ffb01b21041015b63335cc4bcb64
Note: In the event that the ServiceNow CMDB Asset Import job configuration intentionally leaves out a wildcard pattern to ensure that all assets are imported, these errors will still be logged; however, they can be ignored.
Import Errors
Any errors outside of identification errors during the asset import process are also logged.
Import Completion
When the asset import process is complete, a message similar to the following will be logged:
1Processed 34 total records during CMDB CI integration
Completion
At completion of the integration run, multiple messages related to job cleanup will be logged. In addition, the following message indicating run success will be logged:
1Finished asset_import integration run
FAQ
How long do integrations take to run?
The duration of an integration run is dependent on a number of factors:
- InsightVM host resources
- InsightVM asset count
- ServiceNow data import performance
Logs are provided to generally show which operations are being performed by each integration. In addition, the Run Statistics module can provide insight into how long each integration tags to run as it provides ‘start’ and ‘end’ metrics for each.
How frequently can I run the integrations?
Integrations can be run as often as makes sense given factors like scan or CMDB update frequency. The only requirement imposed by the application is that integrations with multiple jobs do not overlap. E.g two InsightVM Asset Tagging integration jobs may not run at the same time, but one InsightVM Asset Tagging job and one ServiceNow Asset Import job may run concurrently.
Can multiple jobs for the same integration be configured?
As many jobs as needed to facilitate the desired data synchronization workflow may be configured, so long that only one job for a particular integration is running at a given time. Different jobs can be run on independent frequencies and even connect to separate InsightVM Security Consoles.
Troubleshooting
Diagnostics
The Diagnostics module in the application menu provides access to the logs for the application, along with access to some of the internal components for troubleshooting purposes. Modules within this module include:
- Logs
- Logs from all integrations provided with the application
- Note: In the event that an exception is not caught by the application, it will not appear under this module. If troubleshooting a run failure or other issue, it is also recommended to review the System Logs -> System Log -> All module for additional details
- Integration Internal Jobs
- Transient background jobs table used by the InsightVM Asset Tagging and ServiceNow Asset Import integrations
- Data Sources
- List of application data sources used by the InsightVM Asset Tagging and ServiceNow Asset Import integrations for import of data from InsightVM.
Debug Level Logging
If additional logging is required, you can enable debug level logging by following these steps:
- In the ServiceNow Filter navigation (which is the primary search), enter
sys_properties.list
into the filter menu and hit Enter. - Select New and create a new property with the following information:
- Name:
x_r7_rapid7_cmdb_i.logging.verbosity
- Choices:
debug,info,warn,error
- Value:
debug
- Name:
- Once saved, log out and then log back into ServiceNow to enable debug logging.
Avoid property collision
If the property created in step 2 already exists, an error will occur upon saving. If this happens, update the existing record with the above information instead of creating a new property.
Common Issues
Integration fails to run
When attempting to run an integration after a prior failure, you may see the following error in the application log:
1Integration is already running, only one instance of an integration can run at time
This error can occur due to one of the following cases:
- A valid job for the integration is already running.
- Stale records in the
Internal Integration Jobs
table from a prior job that were not cleaned up are preventing the integration from running again.
If there is a valid job running, wait for that job to complete. Otherwise, follow these steps to clean up the Internal Integration Jobs
table:
- Confirm that stale records exist by going to the
Rapid7 InsightVM Integration for CMDB -> Diagnostics -> Internal Integration Jobs
module and verify that records are listed. - Go to the
System Definition -> Scripts - Background
module and enter the following script:
1var gr = new GlideRecord('x_r7_rapid7_cmdb_i_integration_job');2gr.query()3gr.deleteMultiple()
- Verify that the
scope
is set toglobal
. - Click
Run script
to execute the script.
If the script runs successfully, you will see a message indicating the number of records that were deleted from the x_r7_rapid7_cmdb_i_integration_job
table.
If execution of the script failed, try repeating the steps with the scope
set to Rapid7 InsightVM Integration for CMDB
.
Accessing another application's resources
When the integration is configured to access tables (or other resources) outside of those it owns, it needs what's known in ServiceNow as cross-scope access. Without cross-scope access, the integration will fail to execute. By default, the integration is configured with cross-scope access to the following CMDB tables:
- cmdb_ci
- cmdb_ci_computer
Some examples of when cross-scope access is needed:
- If a Tag Name Map's Table property is set to
cmdb_ci_vmware_instance
- If a Site Name Map's Table property is set to
cmdb_ci_win_server
.
This also applies to any custom application's resources accessed by the integration.
To create cross-scope access, perform the following steps in the ServiceNow UI:
- Navigate to System Applications > Application Cross-Scope Access.
- Select New record.
- Source Scope: Rapid7 InsightVM Integration for CMDB
- Target Scope: {{Target Scope}}
- Target Name: {{Target Name}}
- Target Type: {{Target Type}}
- Operation: {{Operation}}
- Status: Allowed
Filling in the placeholder values with the appropriate values should be performed before submitting the changes.
As an example, if the integration needs to read values from cmdb_ci_vmware_instance
because of a custom Tag Name Map, the cross-scope access record would look similar to:
- Source Scope: Rapid7 InsightVM Integration for CMDB
- Target Scope: Global
- Target Name:
cmdb_ci_vmware_instance
- Target Type: Table
- Operation: Read
- Status: Allowed
No assets are imported by the ServiceNow Asset Import integration
InsightVM discovery source not created
An error message in the application log stating the following indicates that the 'InsightVM' discovery source for the application was not created:
text
1IdentificationEngine Error Request: {"items":[{"className":"cmdb_ci_linux_server","lookup":[{"className":"cmdb_ci_network_adapter","values":{"ip_address":"192.168.1.1","mac_address":"00:00:00:00:00:00"}}],"values":{"ip_address":192.168.1.1","mac_address":"00:00:00:00:00:00","name":"linux1","os":"Ubuntu Linux 16.04","sys_class_name":"cmdb_ci_linux_server"}}]}, Response: {"items":[{"sysId":"Unknown","identifierEntrySysId":"Unknown","errors":[{"error":"INVALID_INPUT_DATA","message":"In payload invalid data source [InsightVM] exist. You need to provide a valid choice value from field [discovery_source] in table [cmdb_ci]"}],"identificationAttempts":[]}],"relations":[],"logContextId":"b9b87bb41b21041015b63335cc4bcbbe"}
The ‘message’ section in the above log displays the following message, “In payload invalid data source [InsightVM] exist. You need to provide a valid choice value from field [discovery_source] in table [cmdb_ci]”, indicating that the discovery source is not created. Follow the steps in Initial Setup section of this guide to configure discovery source, then try running the job again.
Configuration Management For Scoped Apps CMDB plugin not installed
An error message stating the following indicates the Configuration Management For Scoped Apps CMDB (com.snc.cmdbb.scoped) plugin is not installed. Follow the instructions in the Initial Setup section of this guide to install the plugin, then try running the job again.
1Configuration Management For Scoped Apps CMDB (com.snc.cmdb.scoped) plugin is not installed.
Processed 0 total records during CMDB CI integration
InsightVM Scope configuration
Review the InsightVM Scope configuration for the job and validate that assets should be included based on the defined regular expression patterns.
CMDB Class Map configuration
Review the CMDB Class Maps defined for the job configuration and validate that assets in scope for the job have operating systems matching those patterns.
If no CMDB Class Map matches are found for an asset, a message similar to the following will be logged:
1Failed to find an OS -> Class mapping for source data, {"ip_address":"192.168.1.1","mac_address":"00:00:00:00:00:00","name":"WindowsServer1","os":"Microsoft Windows Server 2012 R2 Standard Edition"}, cannot continue! Configuration Sys ID: d3c5ffb01b21041015b63335cc4bcb64
InsightVM connectivity issues
Authentication Failure
A log message similar to the following indicates authentication failure to the InsightVM security console:
1site_configuration integration failed to run: {"message":"An error occurred executing the paged REST request for Rapid7 VM endpoint: /api/3/sites, method: undefined, error:Error: There was an error retrieving results from the paged endpoint. Error: The supplied credentials are invalid."}
Validate the credentials and host information for the InsightVM connection assigned to the integration job configuration and try running the job again.
Security Console Down
A log message similar to the following may indicate that the InsightVM Security Console host may be down or unresponsive:
1site_configuration integration failed to run: {"message":"An error occurred executing the paged REST request for Rapid7 VM endpoint: /api/3/sites, method: undefined, error:Error: There was an error retrieving results from the paged endpoint. Error: The supplied credentials are invalid."}
Manually review the status of the InsightVM Security Console application and the status of the host. If assistance is needed to restore service of the Security Console application, contact Rapid7 support.
ServiceNow connectivity issues
MID server connectivity issues
A message similar to the following indicates that there may be an issue with the ServiceNow MID server configured for the InsightVM Connection on an integration job configuration:
1asset_import integration failed to run: {"message":"An error occurred executing the paged REST request for Rapid7 VM endpoint: /api/3/sites/, method: undefined, error:com.glide.ecc.ECCResponseTimeoutException: No response for ECC message request with sysid=1a5d1e091ba9041015b63335cc4bcb75 after waiting for 30 seconds in ECC Queue"}
To review the status of a MID server, go to the MID Servers -> Servers module in ServiceNow. For resolution of connectivity issue on a MID server, refer to ServiceNow’s documentation.
No tags created by the InsightVM Asset Tagging integration
InsightVM Scope configuration
Review the InsightVM Scope configuration for the job and validate that assets should be included based on the defined regular expression patterns.
Tag Name Maps configuration
Review the Tag Name Maps configuration for the job configuration and validate that data is available in the fields selected. Also ensure that the selected IP Address, Hostname, and MAC address fields are correct for the records on the selected Table.
No assets are assigned to InsightVM tags
ServiceNow MID server max payload size
Depending on the size of your environment, the reports generated by the integration jobs may result in very large responses between the ServiceNow MID server and the ServiceNow platform. The MID Server max payload size default of 20 MB meets most customer needs. However, if you get this error when running a job, it means the MID server was not able to fulfill the request due to the response size:{""message"":""Received non-OK status code (0), response: null""}
.
To avoid this issue, increase the max payload size. You can refer to this ServiceNow knowledge base article for more information: https://hi.service-now.com/kb_view.do?sysparm_article=KB0748591.
You can define the max payload size globally or per MID Server by following these steps:
- In ServiceNow, go to MID Server > Properties.
- Create a new property.
- Name: mid.eccq.max_payload_size
- Value: 40000000
- Either set globally or for a specific MID Server.
- Save and restart the MID server from within ServiceNow UI.
No sites created by the InsightVM Site Configuration integration
Site Name Maps configuration
Review the Site Name Maps configuration for the job configuration, validate that CIs exist on the selected Table, and ensure that CIs on that table have values in the selected Name Fields [1-5].
Imported assets do not have the correct CMDB class assigned
Review the regular expression patterns defined in the CMDB Class Maps for the integration job configuration and try running the job again.
Not all tables are listed for the Table dropdown in a Tag Name Map or Site Name Map configuration
The application only supports cmdb_ci prefixed tables for Tag Name Map and Site Name Map configurations.
Not all fields are listed in the Field** dropdowns in a Tag Name Map or Site Name Map configuration
The application only supports values of type string as selections on Field selectors.
Receive "Execute operation on script include 'SysRelatedList' from scope 'Rapid7 InsightVM Integration for CMDB' was denied" error when saving Connection
This issue occurs when the "Rapid7 InsightVM Integration for CMDB" application is not able to execute a script include for SysRelatedList resulting in a failure message when saving the Connection.
This can be resolved by navigating in ServiceNow to:
- System Applications > Application Cross-Scope Access
- New record
- Source Scope: Rapid7 InsightVM Integration for CMDB
- Target Scope: Global
- Target Name: SysRelatedList
- Target Type: Script Include
- Operation: Execute API
- Status: Allowed
Once the Application Cross-Scope Access record has been created, you will now be able to create the Connection without receiving the save denied error.