E911 Phone Discovery App for Emergency Location Services

Feature Overview

The Phone Discovery App is a post-call application that gathers comprehensive Cisco IP Phone information during emergency calls. When triggered, this app queries multiple Cisco systems (CUCM, RIS, CDP, Traceroute) to collect real-time phone location and network data for emergency response teams.

This app creates a context of the calling device details that can be used by downstream apps and alert systems.

Why Use This App

• Automatically locate 911 callers across multi-building campuses and remote sites
• Distinguish between on-site and remote workers for appropriate emergency response
• Provide exact location data including building, floor, switch, and port details
• Meet E911 compliance requirements for accurate emergency caller location

Feature Requirements

• Call Telemetry Server Appliance
• Call Telemetry Premium or Demo License
• Cisco Callmanager 8.5 with CURRI API Integration to Call Telemetry
• Configured External Call Control Profile Inspection - Your Emergency 911 route or translation pattern must be enabled for Call Telemetry Policy inspection.
• Enable Web access on Callmanager Cisco IP Phones to obtain CDP and LLDP, and Subnet Data
• Associate the Phone Discovery App to a Rule

App Configuration

The Phone Discovery App supports several hostname transformation options to customize how network device names are processed:

Configuration Parameters

• transform_hostname_upcase (boolean): Convert hostnames to uppercase
  • Default: false
• transform_hostname_strip_vlan (boolean): Remove VLAN information from hostnames (splits on underscore)
  • Default: false
• transform_hostname_within_parens (boolean): Extract hostname content within parentheses
  • Default: false
• transform_hostname_strip_domain (boolean): Remove domain suffix from hostnames
  • Default: false

Hostname Transformation Examples

Original hostname: switch-01_vlan100.company.com(rack-a-01)

With different transformation settings:

• upcase: SWITCH-01_VLAN100.COMPANY.COM(RACK-A-01)
• strip_vlan: switch-01.company.com(rack-a-01) (removes _vlan100)
• within_parens: rack-a-01 (extracts content from parentheses)
• strip_domain: switch-01_vlan100(rack-a-01) (removes .company.com)
• All enabled: RACK-A-01

Discovery Process

The app follows a comprehensive pipeline to gather phone information:

1. RIS Query: Connects to Cisco Real-time Information Service for live phone data
2. CDP Discovery: Queries Cisco Discovery Protocol for network neighbor information
3. Subnet Analysis: Determines phone's network subnet (IPv4 and IPv6)
4. Network Tracing: Performs next-hop analysis to identify network path
5. Hostname Processing: Applies configured transformations to device names
6. Location Lookup: Queries E911 location databases for:
   • Subnet-level locations (e.g., "12th Floor")
   • Switch-level locations (e.g., "12th Floor, North IDF")
   • Port-level locations (e.g., "Room 101, Floor 12")
   • Phone-specific locations (e.g., "Main Lobby Door, Room 101")
7. AXL Integration: Queries CUCM AXL for additional device pool information

Integration with Call Telemetry E911 Location Objects

The Phone Discovery App queries Call Telemetry's hierarchical E911 location database, which allows you to maintain emergency location information at multiple levels:

Location Hierarchy

Call Telemetry matches locations in order of specificity:

1. Phone Location (Most Specific)

   • Exact device location (e.g., "Reception Desk", "Security Station")
   • Linked directly to phone MAC address
   • Provides room-level or desk-level accuracy

2. Port Location

   • Room-level accuracy based on switch port
   • Maps physical wall jacks to specific rooms
   • Ideal for fixed desk phones

3. Switch Location

   • IDF/Closet level location
   • Provides floor or building section accuracy
   • Useful when port-level data isn't available

4. Subnet Location (Least Specific)

   • Building or floor-level location
   • Covers entire network segments
   • Fallback for VPN/remote users

Location Match Field

The match field in the response indicates which level provided the location:

• "match": "phone" - Exact phone location found
• "match": "port" - Port-level match used
• "match": "switch" - Switch location used
• "match": "subnet" - Subnet location used

Building E911 Location Data

You can populate Call Telemetry's E911 location objects through:

• Manual entry via the web interface
• CSV imports for bulk location data
• API updates from CMDB systems
• QR code scanning for physical verification

The Phone Discovery App automatically queries all these location sources during a 911 call to provide the most accurate emergency location possible.

Stacking with other Apps for more location data

The Phone Discovery App can be used in conjunction with other Apps to build a rich context of data for your emergency response teams.

Other related Apps include:

• Subnet CSV - Compares the Subnet discovered from the Phone to a CSV list, with optional data fields adding more context. List can be downloaded per schedule.
• HP Serice Manager CMDB - Queries HP Service Manager API for more context data, like the phone MAC address, and can gain more context location for alerts.
• Webhook App - Can query a JSON API and attach the body to the call for use in alerts.

You can compose detailed Call Alerts with this data, or use it in other Apps to trigger actions based on the phone's location or network data.

App Response Structure

Based on the actual implementation, the Phone Discovery App returns a comprehensive data structure:

{
  "result": "success",
  "message": "Phone Discovery App completed.",
  "provider_message": "Phone Discovery App completed.",
  "data": {
    "phone": {
      "ip": "192.168.123.218",
      "extension": "1006",
      "model": "Cisco 6921",
      "device_name": "SEPC4143C8B8BF9",
      "device_pool": "Default",
      "description": "Auto 1006",
      "firmware": "9.4.1.3SR3",
      "status": "Registered",
      "status_reason": "",
      "subnet": "192.168.123.0/24",
      "subnet_ipv4": "192.168.123.0/24",
      "subnet_ipv6": null,
      "neighbor": {
        "neighbor_ip": "192.168.123.214",
        "neighbor_name": "Switch",
        "neighbor_port": "GigabitEthernet1/0/5",
        "output": "Phone Neighbor Query successful."
      },
      "next_hop": {
        "ip": "192.168.123.214",
        "fqdn": "Switch",
        "hostname": "SWITCH",
        "icmp_output": "ICMP Traceroute skipped as CDP is present."
      },
      "ris_data": {
        "Name": "SEPC4143C8B8BF9",
        "DirNumber": "1006",
        "Model": "Cisco 6921",
        "Status": "Registered",
        "StatusReason": "0",
        "Description": "Auto 1006",
        "ActiveLoadID": "SCCP69xx.9-4-1-3SR3",
        "IPv4": "192.168.123.218"
      }
    },
    "neighbor": {
      "neighbor_ip": "192.168.123.214",
      "neighbor_name": "Switch",
      "neighbor_port": "GigabitEthernet1/0/5",
      "output": "Phone Neighbor Query successful."
    },
    "next_hop": {
      "ip": "192.168.123.214",
      "fqdn": "Switch",
      "hostname": "SWITCH",
      "icmp_output": "ICMP Traceroute skipped as CDP is present."
    },
    "subnet": "192.168.123.0/24",
    "subnet_ipv4": "192.168.123.0/24",
    "subnet_ipv6": null,
    "location": {
      "address": "Building HQ Floor 2",
      "address_text": "HQ-2",
      "near": "Conference Room 201",
      "port": "GigabitEthernet1/0/5",
      "switch": "SWITCH",
      "match": "best",
      "output": "Address processed successfully"
    }
  }
}

Location Data Response Examples

When the app successfully queries Call Telemetry's E911 location objects, the location field provides hierarchical emergency location data:

Phone-Level Location Match

{
  "location": {
    "address": "123 Main St, Boston, MA 02101",
    "address_text": "Boston-HQ",
    "near": "Reception Desk by Main Entrance",
    "port": "GigabitEthernet1/0/5",
    "switch": "BOSHQ-IDF2-SW01",
    "match": "phone",
    "output": "Exact phone location found"
  }
}

Port-Level Location Match

{
  "location": {
    "address": "456 Oak Ave, Cambridge, MA 02139",
    "address_text": "Cambridge-Branch",
    "near": "Conference Room 301",
    "port": "GigabitEthernet2/0/24",
    "switch": "CAMB-IDF3-SW02",
    "match": "port",
    "output": "Port-level location identified"
  }
}

Switch-Level Location Match

{
  "location": {
    "address": "789 Tech Blvd, Waltham, MA 02451",
    "address_text": "Waltham-DC",
    "near": "3rd Floor North IDF Closet",
    "port": "GigabitEthernet1/0/15",
    "switch": "WALT-IDF3N-SW01",
    "match": "switch",
    "output": "Switch closet location available"
  }
}

Subnet-Level Location Match

{
  "location": {
    "address": "999 Remote Way, Anytown, USA 12345",
    "address_text": "Building-A",
    "near": "Building A - General Area",
    "port": null,
    "switch": null,
    "match": "subnet",
    "output": "Subnet-based location estimate"
  }
}

Data Fields Explained

Phone Object

• ip: Phone's IPv4 address
• extension: Directory number from CUCM
• model: Human-readable phone model (decoded from RIS)
• device_name: Unique device identifier in CUCM
• device_pool: Associated device pool from CUCM
• description: Phone description from CUCM
• firmware: Parsed firmware version from ActiveLoadID
• status: Registration status (Registered/UnRegistered)
• status_reason: Human-readable status reason (decoded from numeric code)
• subnet: Primary subnet in CIDR notation
• subnet_ipv4: IPv4 subnet information
• subnet_ipv6: IPv6 subnet information (if available)

Network Information

• neighbor: CDP neighbor data (switch name, IP, port)
• next_hop: Network path information with hostname transformations applied
• location: Physical location context (if available)

Location Object Fields

When E911 location data is found, the location object contains:

• address: Full street address for emergency dispatch
• address_text: Short location identifier (e.g., "Boston-HQ")
• near: Specific location description (e.g., "Conference Room 201", "Reception Desk")
• port: Switch port where phone is connected
• switch: Network switch name
• match: Indicates which location level matched (phone/port/switch/subnet)
• output: Status message about location discovery

Raw RIS Data

The ris_data object contains all raw fields from Cisco's Real-time Information Service for advanced processing.

Error Handling and Response Types

The Phone Discovery App can return different result types based on the discovery outcome:

Success Response

• result: "success" - Phone discovery completed successfully
• message: "Phone Discovery App completed."
• All data fields populated based on available information

Partial Success Response

• result: "success" - Discovery completed but some data unavailable
• message: "Phone Discovery complete, but no location returned."
• Core phone data available but location context missing

Failure Response

• result: "failed" - Discovery pipeline failed
• Common failure scenarios:
  • Phone not found in CUCM
  • Phone not registered/offline
  • RIS query failure
  • Network connectivity issues

Data Availability Notes

• CDP data: Requires CDP to be enabled on phones and network infrastructure
• Location data: Depends on location services configuration and data availability
• AXL data: Requires proper CUCM user permissions for device pool information
• Subnet data: Automatically determined from phone IP address

Integration Requirements

Based on the actual implementation, the app requires:

• CUCM AXL API: For device pool and configuration data
• RIS API Access: For real-time phone registration status
• CDP Support: Phones must have CDP enabled for network topology discovery
• Network Connectivity: Call Telemetry server must reach CUCM and phone networks
• Proper Permissions: CUCM user account needs read access to phone data