Skip to content
vScope Support Page

ServiceNow

vScope’s Discovery not only gathers and structures data but also correlates resources from multiple technologies into a virtual map showing your complete datacenter setup. Integrate vScope with ServiceNow using vScope’s REST API to automate the import of Configuration Items (CIs) like virtual machines, virtualization hosts, and their relationships.

Visualization of asset inventory from vScope in ServiceNow

Overview

This setup fully integrates vScope and ServiceNow for automated discovery, transforming, and relationship mapping, offering a unified view of your IT infrastructure within ServiceNow’s CMDB.

Steps in vScope

  1. Create an API token for ServiceNow.
  2. Create a table listing the virtual machines to import.
  3. Create a table listing the virtualization hosts to import.

Steps in ServiceNow

  1. Create Data Sources for virtual machines and virtualization hosts.
  2. Set up Transformation Maps to create CIs in ServiceNow.
  3. Create Data Sources and Transformation Maps for host/VM relationships.

Create an API Token in vScope

In vScope:

  1. Navigate to Settings > API Tokens.
  2. Create a token, assigning it to a user with READ access to the tables.
  3. Note the expiry date and ensure that the token has access to all tables used in ServiceNow.

Create Tables in vScope

Table for Virtual Machines

  1. In Tables, create a new table for Virtual Machines.
  2. Add essential columns, including UUID (required).
  3. Include additional columns like RAM and CPU Total as needed.
  4. Save the table with a recognizable name, ensuring the assigned user has READ access.
  • After saving, click Collaborators to get the table ID from the permalink, which will be used in ServiceNow.

Table for Virtualization Hosts

Follow the same steps as above to create a table for Virtualization Hosts and add UUID. Use Collaborators to note the table ID.

Set Up Data Sources in ServiceNow

Data Source for Virtual Machines

  1. In ServiceNow, navigate to Data Sources and create a new entry.

  2. Configure:

    • Name: vScope-CS
    • Label: vScope
    • Import set table name: u_vscope_cs
    • Type: File
    • Format: JSON
    • Path for each row: /rows/rows
    • File retrieval method: HTTP/HTTPS
    • Server: {your vScope server address}
    • File path: /rest/v1/tables/{tableId}/data/json?token={API_TOKEN}

  3. Replace {tableId} and {API_TOKEN} with the actual table ID and API token created earlier.

  4. Test the data import by clicking Load All Records.

Data Source for Virtualization Hosts

Follow similar steps to create a Data Source for Virtualization Hosts, using the appropriate table ID from the vScope Hosts table.

Create a Transform Map in ServiceNow for Virtual Machines

  1. After importing the Virtual Machines data into the import table (u_vscope_cs), navigate to Transform Maps and click New.
  2. Configure the Transform Map as follows:
    • Name: vScope-CS
    • Source table: vScope-CS (u_vscope_cs)
    • Target table: Computer (cmdb_ci_computer)
  3. Click Submit to save the new Transform Map.
  4. Under Related Links, click Mapping Assist to set up field mappings.

Suggested Field Mappings for Virtual Machines

In Mapping Assist:

  • Name -> Name
  • UUID -> Correlation ID (this is essential for maintaining consistency on each import)
  • CPU Cores -> CPU core count
  • CPU Sockets -> CPU count

  1. Ensure Coalesce is enabled for UUID -> Correlation ID. This treats UUID as a unique key, enabling ServiceNow to update existing records rather than creating duplicates.

  2. Click Transform under Related Links to start the transformation, selecting the import set and corresponding transform map.

Create a Transform Map in ServiceNow for Virtualization Hosts

  1. After importing the Virtualization Hosts data into the import table (u_vscope_host), go to Transform Maps and create a new entry.
  2. Configure the Transform Map:
    • Name: vScope-Host
    • Source table: vScope-Host (u_vscope_host)
    • Target table: ESX Server (cmdb_ci_esx_server) or Hyper-V Host (cmdb_ci_hyper_v_server for Hyper-V)
  3. Click Submit to save the new Transform Map, then use Mapping Assist for field mapping.

Suggested Field Mappings for Virtualization Hosts

  • Name -> Name
  • UUID -> Correlation ID
  • CPU Cores -> CPU core count
  • CPU Sockets -> CPU count
  1. Enable Coalesce for UUID -> Correlation ID to ensure unique mapping. Then, click Transform under Related Links.

Create a Data Source in ServiceNow for Host/VM Relationships

  1. In ServiceNow, create a Data Source for the Host/VM Relationship:

    • Name: vScope-Host-VM-Rel
    • Import set table label: vScope
    • Import set table name: u_vscope_host_vm_rel
    • Type: File
    • Format: JSON
    • Path for each row: /rows/rows
    • File retrieval method: HTTP/HTTPS
    • Server: {your vScope server address}
    • File path: /rest/v1/tables/{tableId}/hops/hostToVM?hopName=Hosted on::Hosts&token={API_TOKEN}

  2. Replace {tableId} with the table ID of the Virtualization Hosts table and {API_TOKEN} with your API token.

  3. Test the Data Source by selecting Load All Records. Confirm successful import in the u_vscope_host_vm_rel import table.

Create a Transform Map in ServiceNow for Host/VM Relationships

  1. In ServiceNow, create a new Transform Map for the Host/VM relationship:

    • Name: vScope-Host-VM-Rel
    • Source table: vScope-Host-VM-Rel (u_vscope_host_vm_rel)
    • Target table: CI Relationship (cmdb_rel_ci)

  2. Configure field mappings in Mapping Assist:

    • u_sourceuuid -> parent
    • u_targetuuid -> child
    • u_hopname -> type

  3. Add a Transform Script under the Transform Scripts tab, using onBefore to run the script:

(function runTransformScript(source, map, log, target) {
 ignore = true; // Ignore as we'll add the relationship manually


 var ci_tables = ["cmdb_ci_computer", "cmdb_ci_esx_server"];
 var childSysId = null, parentSysId = null;


 function findSysId(table, correlationId) {
   var gr = new GlideRecord(table);
   gr.addQuery('correlation_id', correlationId);
   gr.query();
   return gr.next() ? gr.getValue('sys_id') : null;
 }


 childSysId = ci_tables.map(t => findSysId(t, source.u_sourceuuid)).find(id => id);
 parentSysId = ci_tables.map(t => findSysId(t, source.u_targetuuid)).find(id => id);


 if (childSysId && parentSysId) {
   var relGr = new GlideRecord("cmdb_rel_ci");
   relGr.initialize();
   relGr.parent = parentSysId;
   relGr.child = childSysId;
   relGr.type = source.u_hopname;
   relGr.insert();
 }
})(source, map, log, target);

Verify Successful Transformation of Relationships

  1. Check Transformation History: After running the transformation, go to Transform History to review the results. Here, you’ll see the number of relationships created, updated, or any errors encountered.

  2. Common Errors:

    • If you encounter entries like "Skipped: Failed to map endpoints", it usually indicates that the u_sourceuuid or u_targetuuid fields could not be matched to existing CI records.
    • Make sure the UUID fields in both vScope and ServiceNow match and that your API token has the correct permissions.
    • If necessary, re-run the import to ensure data integrity.

  3. Verify Relationships in ServiceNow:

    • Navigate to CI Relationships by entering cmdb_rel_ci in the ServiceNow filter navigator.
    • You should see entries that represent relationships between virtual machines and virtualization hosts, with parent and child fields populated by the sys_id values from cmdb_ci_computer and cmdb_ci_esx_server tables.

Viewing Relationships in ServiceNow

  1. Visualize CI Relationships:

    • To view relationships in a graphical format, go to an imported ESX server or virtual machine in the Configuration Item table.
    • Under Related Items, click the graph icon to bring up a visualization of relationships.

  2. Check Relationship Details:

    • Relationships will show connections between hosts and their hosted virtual machines.
    • Verify the Relationship Type (e.g., “Hosted on::Hosts”) is correctly displayed for each entry.

Schedule Regular Imports in ServiceNow

Automating the import process is essential to maintain up-to-date data in ServiceNow. Follow these steps to set up scheduled imports:

  1. Navigate to Scheduled Imports:

    • In ServiceNow, go to System Import Sets > Scheduled Import.
    • Click New to create a scheduled import for each data source (Virtual Machines, Virtualization Hosts, and Host/VM Relationships).

  2. Configure Each Import Schedule:

    • Virtual Machines:

      • Name: vScope-CS Import
      • Data Source: vScope-CS
      • Run as User: Choose a user with API access permissions.
      • Schedule: Set the preferred interval (e.g., Daily at 3:00 AM).
      • Click Submit and Execute Now to test the import.

    • Virtualization Hosts:

      • Name: vScope-Host Import
      • Data Source: vScope-Host
      • Set the schedule to run after the Virtual Machines import is complete.

    • Host/VM Relationships:

      • Name: vScope-Host-VM-Rel Import
      • Data Source: vScope-Host-VM-Rel
      • Schedule this import to run after the Virtual Machines and Hosts imports (e.g., at 3:30 AM) to ensure all CI records are in place.

  3. Validate Scheduled Imports:

    • After setting up, run each scheduled import manually via Execute Now to confirm functionality.
    • Review the Transform History for each import to ensure successful transformations and troubleshoot any issues as needed.

Important Notes and Tips

  • Always Coalesce on UUID: For accurate synchronization, always map UUID from vScope to Correlation ID in ServiceNow and enable Coalesce on this field to maintain consistent identifiers across imports.
  • Relationship Transformations: Ensure that Host/VM Relationships transformations only run after Virtual Machines and Virtualization Hosts transformations. This sequencing ensures that CI references are established before relationships are created.
  • Check API Token Permissions: Verify that your API token has sufficient permissions to access all relevant tables and CI records in vScope.
  • Monitor Storage Limits: If import tables (u_vscope_cs, u_vscope_host, etc.) reach maximum field character limits (often 40 characters), you may need to delete and recreate them as noted earlier.

Troubleshooting Common Issues

  1. Data Not Importing:

    • Check that the vScope API endpoint and API token are correct.
    • Verify network connectivity between ServiceNow and vScope.

  2. Field Truncation:

    • If UUIDs are truncated in import tables, clear and recreate the table structure by deleting import tables under System Import Sets > Cleanup and re-running the import.

  3. Duplicate Records:

    • Ensure Coalesce is enabled on the UUID to Correlation ID field mapping to prevent duplicate CI entries.
    • Confirm that scheduled imports do not overlap or run concurrently.