Skip to main content

ServiceNow CMDB Lookup App - Asset & Location Discovery

Overview​

The ServiceNow CMDB app queries your ServiceNow Configuration Management Database to retrieve device and location information based on call data. When integrated with Call Telemetry, this app enriches calls with asset details, network topology, and physical location data critical for E911 and IT operations.

Why Use the ServiceNow CMDB App​

  • E911 Location Services: Retrieve physical addresses from CMDB for emergency calls
  • Asset Verification: Match calling devices to CMDB records for inventory accuracy
  • Network Topology: Identify connected switches, ports, and network segments
  • Automatic Location Lookups: Follow CMDB references to get complete location details
  • Multi-Table Support: Query any ServiceNow table - phones, switches, computers, locations

Key Features​

  • Flexible Authentication: Basic Auth or OAuth 2.0 client credentials
  • Dynamic Queries: Template variables for real-time data insertion
  • Two-Stage Lookups: Automatic location enrichment from CMDB references
  • ServiceNow Query Syntax: Full support for encoded queries and filters
  • Comprehensive Results: Returns all ServiceNow fields for maximum flexibility

Prerequisites​

Before configuring the ServiceNow CMDB app:

  • Call Telemetry Appliance: Version 0.8.0 or later
  • Call Telemetry Premium License
  • Cisco CallManager: Configured with CURRI API Integration
  • ServiceNow Instance: With REST API access enabled
  • ServiceNow Permissions: Read access to CMDB tables
  • Network Connectivity: HTTPS access from Call Telemetry to ServiceNow

ServiceNow Setup​

Step 1: Create Integration User​

  1. Log into ServiceNow as administrator
  2. Navigate to User Administration → Users
  3. Create a new user for Call Telemetry integration
  4. Assign these minimum roles:
    • rest_api_explorer - REST API access
    • itil or itil_read - CMDB read permissions

Step 2: Configure Authentication​

  1. Navigate to System OAuth → Application Registry
  2. Click New → Create an OAuth API endpoint for external clients
  3. Name: "Call Telemetry Integration"
  4. Note the Client ID and Client Secret

For Basic Authentication​

Use the integration user's username and password directly.

Configuration Steps​

Step 1: Create the ServiceNow CMDB App​

Navigate to Policies → Apps → Post Call Apps → ServiceNow CMDB

Click Create App

Step 2: Configure Basic Settings​

Fill in the app details:

  • App Name - "ServiceNow CMDB Lookup" or descriptive name
  • Description - Brief description of the lookup purpose
  • App Order - Execution order (30-50 recommended after Phone Discovery)

Step 3: Configure ServiceNow Connection​

  • Instance URL - Your ServiceNow instance (e.g., https://company.service-now.com)
  • Table - ServiceNow table to query:
    • cmdb_ci_ip_phone - IP phones
    • cmdb_ci_netgear - Network devices (parent table)
    • cmdb_ci_ip_switch - Network switches
    • cmdb_ci_computer - Computers/workstations
    • alm_hardware - Hardware assets

Step 4: Set Up Authentication​

For Basic Authentication:

  • Auth Type - Select "Basic"
  • Username - ServiceNow integration user
  • Password - ServiceNow integration password

For OAuth 2.0:

  • Auth Type - Select "OAuth2"
  • OAuth Grant Type - "client_credentials"
  • OAuth Token URL - https://your-instance.service-now.com/oauth_token.do
  • OAuth Client ID - From ServiceNow OAuth application
  • OAuth Client Secret - From ServiceNow OAuth application
  • OAuth Scope (optional) - Leave empty or use "useraccount"

Step 5: Configure Query Parameters​

Add query parameters to filter CMDB results:

Query by IP Address​

[
  {
    "key": "ip_address",
    "value": "{{ app_data.phone-discovery.data.phone.ip }}"
  }
]

Query by Switch Name​

[
  {
    "key": "name",
    "value": "{{ app_data.phone-discovery.data.neighbor.neighbor_name }}"
  }
]

Complex Query with Filters​

[
  {
    "key": "sysparm_query",
    "value": "name={{ app_data.phone-discovery.data.neighbor.neighbor_name }}^operational_status=1"
  },
  {
    "key": "sysparm_limit",
    "value": "1"
  },
  {
    "key": "sysparm_fields",
    "value": "sys_id,name,ip_address,location,serial_number"
  }
]

Step 6: Configure Location Lookups​

  • Lookup Location - Toggle ON to automatically retrieve location details
    • When enabled, follows CMDB location references
    • Provides full address, city, state, ZIP data
    • Toggle OFF if location data not needed

Available Template Variables​

From Phone Discovery App​

  • {{ app_data.phone-discovery.data.phone.ip }} - Phone IP address
  • {{ app_data.phone-discovery.data.phone.extension }} - Extension number
  • {{ app_data.phone-discovery.data.phone.device_name }} - SEP MAC address
  • {{ app_data.phone-discovery.data.neighbor.neighbor_name }} - Connected switch
  • {{ app_data.phone-discovery.data.neighbor.neighbor_port }} - Switch port

From Call Event​

  • {{ event.calling_number }} - Calling party number
  • {{ event.calling_devicename }} - Device name (MAC-based)
  • {{ event.called_number }} - Called party number

Understanding ServiceNow Responses​

The app returns structured data with CMDB records and location details:

CMDB Record Response​

{
  "data": {
    "cmdb_ci_netgear": {
      "status": "success",
      "result_count": 1,
      "data": [
        {
          "name": "la-switch-01",
          "ip_address": "10.128.10.105",
          "serial_number": "ABC1234D567",
          "location": {
            "link": "https://test.service-now.com/api/now/table/cmn_location/cef3f45d",
            "value": "cef3f45d1b4174100d8cecea234bcb00"
          },
          "location_details": {
            "name": "USA - CA - Los Angeles",
            "city": "Los Angeles",
            "state": "CA",
            "zip": "90071",
            "street": "123 Main St"
          }
        }
      ]
    }
  }
}

Accessing Data in Templates​

# First CMDB record
Switch: {{ app_data.servicenow-cmdb.data.cmdb_ci_netgear.data[0].name }}
Location: {{ app_data.servicenow-cmdb.data.cmdb_ci_netgear.data[0].location_details.city }}

# Location details
Address: {{ app_data.servicenow-cmdb.data.cmdb_ci_netgear.data[0].location_details.street }}
City: {{ app_data.servicenow-cmdb.data.cmdb_ci_netgear.data[0].location_details.city }}
State: {{ app_data.servicenow-cmdb.data.cmdb_ci_netgear.data[0].location_details.state }}

ServiceNow Query Parameters​

Essential Parameters​

  • sysparm_query - Encoded query syntax for complex filters
  • sysparm_limit - Maximum records to return (recommend: 1)
  • sysparm_fields - Specific fields to retrieve
  • sysparm_display_value - Return display values vs sys_ids

Query Syntax Examples​

  • Equals: field=value
  • Contains: fieldLIKEvalue
  • AND: field1=value1^field2=value2
  • OR: field1=value1^ORfield2=value2
  • Is not empty: fieldISNOTEMPTY

Common Use Cases​

E911 Phone Location​

Query phone's physical location for emergency dispatch:

{
  "table": "cmdb_ci_ip_phone",
  "query_params": [
    {
      "key": "ip_address",
      "value": "{{ app_data.phone-discovery.data.phone.ip }}"
    }
  ]
}

Network Switch Discovery​

Find switch details and location:

{
  "table": "cmdb_ci_ip_switch",
  "query_params": [
    {
      "key": "name",
      "value": "{{ app_data.phone-discovery.data.neighbor.neighbor_name }}"
    },
    {
      "key": "operational_status",
      "value": "1"
    }
  ]
}

Asset Verification​

Validate device against CMDB records:

{
  "table": "alm_hardware",
  "query_params": [
    {
      "key": "serial_number",
      "value": "{{ event.device_serial }}"
    }
  ]
}

Multi-App Workflows​

E911 Location Discovery​

  1. Phone Discovery App (Order: 10) - Get phone network info
  2. ServiceNow CMDB App (Order: 30) - Query switch location
  3. Webex Teams App (Order: 50) - Alert with location data
  4. Email App (Order: 60) - Notify security team

Asset Management​

  1. Phone Discovery App (Order: 10) - Identify device
  2. ServiceNow CMDB App (Order: 30) - Verify in CMDB
  3. Webhook App (Order: 40) - Update external systems

Best Practices​

Query Optimization​

  1. Limit Results: Always use sysparm_limit=1 for single device lookups
  2. Specific Queries: Use unique identifiers when possible
  3. Field Selection: Request only needed fields with sysparm_fields
  4. Index Usage: Query on indexed fields (sys_id, name, ip_address)

Location Data​

  1. Maintain CMDB: Keep location data current in ServiceNow
  2. Standard Naming: Use consistent device naming conventions
  3. Location Hierarchy: Leverage ServiceNow location relationships
  4. Address Format: Ensure addresses are E911-dispatcher friendly

Performance Considerations​

warning

The app only processes the FIRST record returned by ServiceNow. Ensure queries return the exact device needed.

  • API Rate Limits: ServiceNow enforces hourly request limits
  • Query Efficiency: Complex queries impact ServiceNow performance
  • Location Lookups: Second API call adds latency (disable if not needed)
  • Timeout Settings: Default 30 seconds for post-call apps

Troubleshooting​

Authentication Failures​

  • Verify username/password or OAuth credentials
  • Check user has required ServiceNow roles
  • Confirm REST API access is enabled

No Results Returned​

  • Test query directly in ServiceNow
  • Verify table name is correct
  • Check field names match ServiceNow schema
  • Ensure device exists in CMDB

Missing Location Data​

  • Confirm location field populated in CMDB
  • Verify lookup_location is enabled
  • Check user has read access to cmn_location table

Template Variable Issues​

  • Ensure Phone Discovery app runs first
  • Verify variable syntax is correct
  • Check app naming matches references

Supported ServiceNow Tables​

Network Infrastructure​

  • cmdb_ci_netgear - Parent table for network gear
  • cmdb_ci_ip_switch - IP switches
  • cmdb_ci_router - Routers
  • cmdb_ci_ip_network - Network definitions

Communication Devices​

  • cmdb_ci_ip_phone - IP phones
  • cmdb_ci_comm - General communication devices

Computing Assets​

  • cmdb_ci_computer - Workstations
  • cmdb_ci_hardware - General hardware

Supporting Tables​

  • cmn_location - Location records
  • alm_hardware - Asset management

Security Considerations​

  • Credential Storage: Encrypted in Call Telemetry database
  • API Permissions: Read-only access recommended
  • Network Security: Use HTTPS for all communications
  • Audit Trail: ServiceNow logs all API access

See Also​

Last updated on by Call Telemetry