ServiceNow App - Incident & Change Management Integration

Overview

The ServiceNow app enables seamless integration between Call Telemetry and ServiceNow's IT Service Management platform. Automatically create incidents, change requests, and service requests based on call events, network issues, or emergency situations.

Why Use the ServiceNow App

• Automated Incident Creation: Generate tickets for emergency calls, network issues, or service problems
• Change Management: Create change requests for phone moves, adds, and changes
• Service Requests: Automate fulfillment workflows for new phone provisioning
• Real-time Updates: Keep ServiceNow current with live call data and network events
• Audit Trail: Maintain complete records of call-related incidents and changes

Key Features

• Multiple Record Types: Create incidents, change requests, service requests, and custom tables
• ServiceNow Authentication: OAuth 2.0 and Basic Authentication support
• Custom Fields: Map call data to any ServiceNow fields
• Attachment Support: Include call recordings or network diagrams
• Template Variables: Use any call or app data in your requests
• Priority Mapping: Automatically set priority based on call patterns or caller identity
• Assignment Rules: Route tickets to appropriate teams based on location or device type

Prerequisites

Before configuring the ServiceNow app:

• Call Telemetry Appliance: Version 0.8.0 or later
• Call Telemetry Premium License
• Cisco CallManager: Configured with CURRI API Integration
• ServiceNow Instance: With appropriate user permissions
• ServiceNow API Access: REST API enabled with proper authentication
• Network Connectivity: Call Telemetry server must reach your ServiceNow instance

ServiceNow Configuration

Step 1: Create ServiceNow Integration User

1. Log into your ServiceNow instance as an administrator
2. Navigate to User Administration → Users
3. Click New to create a new user
4. Fill in user details:
   • User ID: call-telemetry-integration
   • First Name: Call
   • Last Name: Telemetry Integration
   • Email: Your integration email address
5. Assign appropriate roles:
   • incident_manager - For incident creation
   • change_manager - For change request creation
   • itil - General ITIL processes
   • rest_service - REST API access

Step 2: Generate API Credentials

For OAuth 2.0 (Recommended)

1. Navigate to System OAuth → Application Registry
2. Click New → Create an OAuth API endpoint for external clients
3. Configure the OAuth application:
   • Name: "Call Telemetry Integration"
   • Client ID: Auto-generated (copy this)
   • Client Secret: Auto-generated (copy this)
   • Redirect URL: Not required for client credentials flow
4. Save and note the credentials

For Basic Authentication

Simply use the username and password of your integration user.

Step 3: Test API Access

Test your credentials using a REST client:

# OAuth 2.0 Token Request
POST https://your-instance.service-now.com/oauth_token.do
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

# Test Incident Creation
POST https://your-instance.service-now.com/api/now/table/incident
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "short_description": "Test incident from Call Telemetry",
  "description": "Testing API connectivity"
}

Call Telemetry Configuration

Step 1: Create the ServiceNow App

Navigate to Policies → Apps → Select app type:

• Real-time - For immediate incident creation during emergencies
• Post Call - For logging and change management after calls

Select ServiceNow → Click Create App

Step 2: Configure Basic Settings

Fill in the app details:

• App Name - "Emergency Incident Creation" or "Network Change Requests"
• Description - Brief description of the ServiceNow integration purpose
• App Order - Execution order (30-70 recommended after data gathering apps)

Step 3: Configure ServiceNow Connection

Instance Details

• ServiceNow Instance URL - Your ServiceNow instance (e.g., https://dev12345.service-now.com)
• Table Name - ServiceNow table to create records in:
  • incident - For incidents
  • change_request - For change requests
  • sc_request - For service requests
  • Custom table names supported

Authentication Method

OAuth 2.0 (Recommended):

• Auth Type: OAuth 2.0
• Client ID: From ServiceNow OAuth application
• Client Secret: From ServiceNow OAuth application
• Token URL: https://your-instance.service-now.com/oauth_token.do

Basic Authentication:

• Auth Type: Basic
• Username: ServiceNow integration user
• Password: ServiceNow integration user password

Step 4: Configure Record Fields

Map call data to ServiceNow fields using the field mapping interface:

Common Incident Fields

• short_description - Brief incident summary

  Emergency Call from {{ event.calling_number }} to {{ event.called_number }}

• description - Detailed incident description

  Emergency call detected at {{ event.timestamp }}.
  
  Caller: {{ event.calling_number }} ({{ event.calling_name }})
  Called: {{ event.called_number }}
  Device: {{ event.calling_devicename }}
  Location: {{ app_data.phone-discovery.data.subnet }}

• priority - Incident priority (1-5)

  {% if event.called_number == '911' %}1{% else %}3{% endif %}

• urgency - Incident urgency (1-3)

  {% if event.called_number == '911' %}1{% else %}2{% endif %}

• category - Incident category

  Telecommunications

• subcategory - Incident subcategory

  {% if event.called_number == '911' %}Emergency Services{% else %}Voice Services{% endif %}

• assignment_group - Team to assign ticket to

  IT Operations

• caller_id - Person who reported the incident

  {{ event.calling_number }}

• location - Physical location of the incident

  {{ app_data.phone-discovery.data.neighbor.neighbor_name }}

Common Change Request Fields

• short_description - Change summary

  Phone Move: {{ event.calling_devicename }} to new location

• description - Detailed change description

  Phone {{ event.calling_devicename }} ({{ event.calling_number }}) needs to be moved.
  
  Current Location: {{ app_data.phone-discovery.data.subnet }}
  Current Switch: {{ app_data.phone-discovery.data.neighbor.neighbor_name }}
  Current Port: {{ app_data.phone-discovery.data.neighbor.neighbor_port }}

• type - Change type

  Standard

• risk - Change risk level

  Low

• priority - Change priority

  4

• change_reason - Reason for change

  User Request

Step 5: Configure Advanced Options

Custom Fields

Add any custom ServiceNow fields your organization uses:

• Click Add Custom Field
• Enter field name (e.g., u_phone_model, u_network_segment)
• Enter value using template variables

Attachments (Optional)

Attach files to ServiceNow records:

• Attachment URL - URL to file or document
• Attachment Name - Name for the attachment
• Content Type - MIME type of attachment

Available Template Variables

Call Event Data

• {{ event.calling_number }} - Calling party number
• {{ event.called_number }} - Called party number
• {{ event.calling_name }} - Calling party name
• {{ event.calling_devicename }} - Device name (e.g., SEP123456789ABC)
• {{ event.timestamp }} - Call timestamp
• {{ event.trigger_point_type }} - Where call was intercepted

Phone Discovery Data (if Phone Discovery app runs first)

• {{ app_data.phone-discovery.data.phone.ip }} - Phone IP address
• {{ app_data.phone-discovery.data.phone.extension }} - Extension
• {{ app_data.phone-discovery.data.phone.model }} - Phone model
• {{ app_data.phone-discovery.data.phone.description }} - Phone description
• {{ app_data.phone-discovery.data.neighbor.neighbor_name }} - Connected switch
• {{ app_data.phone-discovery.data.neighbor.neighbor_port }} - Switch port
• {{ app_data.phone-discovery.data.subnet }} - Phone subnet

Meraki Lookup Data (if Meraki Lookup app runs first)

• {{ app_data.meraki-lookup.data.location.address }} - Physical address
• {{ app_data.meraki-lookup.data.location.city }} - City
• {{ app_data.meraki-lookup.data.location.state }} - State
• {{ app_data.meraki-lookup.data.device.name }} - Switch name
• {{ app_data.meraki-lookup.data.device.notes }} - Device notes

Understanding ServiceNow Responses

The ServiceNow app stores the created record details under the data key:

Example Response

{
  "result": {
    "sys_id": "1c741bd70b2322007518478d83673af3",
    "number": "INC0000123",
    "state": "1",
    "priority": "1",
    "short_description": "Emergency Call from 5551234567 to 911",
    "assignment_group": "IT Operations",
    "caller_id": "5551234567"
  }
}

This data is available as:

• {{ app_data.servicenow.data.result.number }} → "INC0000123"
• {{ app_data.servicenow.data.result.sys_id }} → "1c741bd70b2322007518478d83673af3"
• {{ app_data.servicenow.data.result.state }} → "1"

Common Use Cases

Emergency Call Incident Creation

Automatically create high-priority incidents when emergency calls are detected:

1. Phone Discovery App (Order: 10) - Get caller location
2. Meraki Lookup App (Order: 20) - Find physical address
3. ServiceNow App (Order: 30) - Create emergency incident
4. Webex Teams App (Order: 40) - Alert security team

Network Issue Reporting

Create incidents for network or phone issues:

1. Phone Discovery App (Order: 10) - Identify problematic device
2. ServiceNow App (Order: 30) - Create network incident
3. Email App (Order: 50) - Notify network team

Change Management Workflow

Create change requests for phone moves:

1. Phone Discovery App (Order: 10) - Document current configuration
2. ServiceNow App (Order: 30) - Create change request
3. Webhook App (Order: 40) - Update CMDB

Service Request Automation

Automate service fulfillment:

1. SOAP Query App (Order: 10) - Check user entitlements
2. ServiceNow App (Order: 30) - Create service request
3. Email App (Order: 50) - Notify fulfillment team

Best Practices

For Emergency Response

1. High Priority Mapping: Set priority to 1 for emergency calls
2. Immediate Assignment: Route to 24/7 operations team
3. Rich Context: Include location and caller details
4. Follow-up Actions: Chain with notification apps
5. SLA Compliance: Ensure emergency incidents meet response SLAs

For Change Management

1. Documentation: Include current and target configurations
2. Risk Assessment: Set appropriate risk levels
3. Approval Workflows: Route high-risk changes for approval
4. Impact Analysis: Document affected systems and users
5. Rollback Plans: Include rollback procedures in descriptions

For Service Requests

1. Catalog Items: Link to existing ServiceNow catalog items
2. Auto-Approval: Configure auto-approval for standard requests
3. Fulfillment Groups: Route to appropriate fulfillment teams
4. Progress Updates: Update requesters on fulfillment status
5. Asset Tracking: Update CMDB with new assets

Performance Considerations

API Rate Limits

ServiceNow enforces rate limits:

• Standard: 2000 requests per hour per user
• Enterprise: Higher limits available
• Burst: Short-term higher rates allowed

The app includes automatic rate limiting and retry logic.

Timeout Settings

• Real-time Apps: Use 5-10 second timeouts
• Post-call Apps: Use 30-60 second timeouts
• Bulk Operations: Consider longer timeouts

Troubleshooting

Authentication Issues

OAuth 2.0 Token Errors:

• Verify client ID and secret are correct
• Check OAuth application configuration in ServiceNow
• Ensure user has proper roles assigned

Basic Auth Failures:

• Verify username and password
• Check user account is active
• Confirm user has required roles

Record Creation Failures

Field Validation Errors:

• Check required fields are populated
• Verify field names match ServiceNow schema
• Ensure choice field values are valid

Permission Errors:

• Verify user has write access to target table
• Check ACL rules for the table
• Confirm user roles include necessary permissions

Template Variable Issues

Variables Not Replaced:

• Check variable syntax is correct
• Ensure data source app runs before ServiceNow app
• Verify app naming matches template references

Missing Data:

• Confirm dependent apps are configured
• Check app execution order
• Use Call Test to verify data flow

Multi-App Workflows

Complete Emergency Response

1. Phone Discovery App (Order: 10) - Get caller info
2. Meraki Lookup App (Order: 20) - Find location
3. ServiceNow App (Order: 30) - Create incident
4. Webex Teams App (Order: 40) - Alert team
5. Twilio SMS App (Order: 50) - Text security

IT Service Desk Integration

1. Phone Discovery App (Order: 10) - Identify caller
2. SOAP Query App (Order: 20) - Check CMDB
3. ServiceNow App (Order: 30) - Create ticket
4. Email App (Order: 40) - Notify support team

Change Management Process

1. Phone Discovery App (Order: 10) - Document current state
2. ServiceNow App (Order: 30) - Create change request
3. Webhook App (Order: 40) - Update external systems
4. Email App (Order: 50) - Notify change board

Security Considerations

• Credential Storage: All credentials encrypted in Call Telemetry database
• Network Security: Use HTTPS for all ServiceNow communications
• Access Control: Limit integration user permissions to minimum required
• Audit Logging: ServiceNow logs all API access for compliance
• Data Privacy: Ensure call data handling meets privacy requirements

See Also

• Phone Discovery App - Gather caller location data
• Meraki Lookup App - Find network device information
• Webhook App - General REST API integration
• Understanding Call Apps - Complete guide to Call Apps