Support
Documentation
Start typing to search…

ServiceNow Integration Guide

Complete guide to integrating ServiceNow with DevGrid for DORA metrics (MTTR and Change Failure Rate).

Overview

ServiceNow integration enables DevGrid to:

  • Calculate Mean Time to Restore (MTTR) from incident data
  • Calculate Change Failure Rate (CFR) by linking incidents to deployments
  • Filter metrics by incident priority (P1, P2, P3, P4)
  • Track incident trends over time

Prerequisites

Before starting, ensure you have:

  1. ServiceNow Instance

    • Admin or integration user account
    • API access enabled
    • Custom field creation permissions (for deployment linkage)

  2. DevGrid Account

    • Admin access to configure integrations
    • Applications/entities already created in DevGrid

  3. Technical Requirements

    • ServiceNow REST API enabled
    • Network connectivity between DevGrid and your ServiceNow instance
    • API credentials (username/password or OAuth)

Integration Setup

Step 1: Create ServiceNow Integration User (Recommended)

Create a dedicated integration user rather than using a personal account.

  1. In ServiceNow:

    • Go to User Administration → Users
    • Click New
    • Fill in details:
      • User ID: devgrid_integration
      • First name: DevGrid
      • Last name: Integration
      • Email: [email protected]

  2. Assign Required Roles:

    • rest_service - REST API access
    • itil - Access to incident tables
    • Custom role with read access to:
      • incident table
      • change_request table
      • Custom deployment linkage field

  3. Set Password:

    • Generate a strong password
    • Store securely in password manager

Step 2: Configure Custom Field for Deployment Linkage

This is critical for Change Failure Rate calculation.

DevGrid needs to know which deployment caused each incident. Add a custom field to the Incident table:

  1. In ServiceNow:

    • Go to System Definition → Tables
    • Search for and open: incident
    • Click New under "Columns" tab

  2. Create Custom Field:

    • Column label: Caused By Deployment
    • Column name: u_caused_by_deployment
    • Type: String
    • Max length: 100
    • Default value: (leave empty)

  3. Add to Incident Form:

    • Go to Incident → Open an existing incident
    • Right-click form header → Configure → Form Layout
    • Drag "Caused By Deployment" field to appropriate section
    • Click Save

  4. Document the Field:

    • Create internal documentation explaining:
      • This field links incidents to deployments
      • Populate with change_id from deployment events
      • Example: CHG0012345

Step 3: Connect ServiceNow to DevGrid

  1. In DevGrid:

    • Navigate to Settings → Integrations
    • Click Add Integration
    • Select ServiceNow

  2. Enter Connection Details:

    • Instance URL: https://your-instance.service-now.com
    • Username: devgrid_integration
    • Password: [your integration user password]
    • Deployment Link Field: u_caused_by_deployment (or whatever you named your custom field)

  3. Configure Sync Settings:

    • Sync Frequency: Every 1 hour (recommended)
    • Incident Filters:
      • Include States: Resolved, Closed
      • Include Priorities: P1, P2, P3, P4 (or customize)
      • Date Range: Last 90 days (recommended for initial sync)

  4. Map Incident Priorities: DevGrid needs to understand your ServiceNow priority levels.

    Default mapping:

    ServiceNow PriorityDevGrid Priority
    1 - CriticalP1
    2 - HighP2
    3 - ModerateP3
    4 - LowP4
    5 - PlanningP5

    Customize if your organization uses different priority schemes.

  5. Test Connection:

    • Click Test Connection
    • Verify success message
    • Review any warnings or errors

  6. Save Integration:

    • Click Save
    • Initial sync will start automatically

Step 4: Verify Initial Sync

  1. Check Sync Status:

    • Go to Settings → Integrations → ServiceNow
    • View Last Sync timestamp
    • Check Sync Status (should show "Success")

  2. Review Synced Incidents:

    • In DevGrid, navigate to Incidents or Metrics
    • Filter by date range
    • Verify incidents appear with correct:
      • Priority
      • Created/Resolved timestamps
      • Status

  3. Troubleshoot if Issues:

    • Check ServiceNow API credentials
    • Verify network connectivity
    • Review DevGrid integration logs
    • See Troubleshooting section below

Linking Incidents to Deployments

Why This Matters

Change Failure Rate cannot be calculated without incident-to-deployment links.

Without this linkage, DevGrid doesn't know:

  • Which deployment caused which incident
  • How many deployments resulted in incidents
  • The failure rate of your deployments

How to Link Incidents

Option 1: During Incident Creation (Recommended)

When creating a new incident:

  1. Identify the Deployment:

    • Check deployment logs for recent deployments
    • Look for change management tickets (CHG numbers)
    • Example: CHG0012345

  2. Link in ServiceNow:

    • Open the incident
    • Find the Caused By Deployment field
    • Enter the change ID: CHG0012345
    • Save incident

Option 2: During Incident Investigation

After investigating root cause:

  1. Determine Root Cause:

    • Was this incident caused by a recent deployment?
    • Which change ticket represents that deployment?

  2. Update Incident:

    • Open the incident in ServiceNow
    • Populate Caused By Deployment field with change ID
    • Add notes explaining the linkage
    • Save

Option 3: Bulk Update (Historical Data)

For historical incidents that need linkage:

// ServiceNow Background Script
var gr = new GlideRecord('incident');
gr.addQuery('opened_at', '>', '2025-09-01');  // Last 2 months
gr.addQuery('u_caused_by_deployment', '');     // No deployment linked
gr.addQuery('state', 'Resolved');
gr.query();

while (gr.next()) {
  // Logic to determine deployment
  // This is custom to your organization
  // Example: link to deployment within 24 hours before incident

  var deploymentId = findRelatedDeployment(gr.opened_at);
  if (deploymentId) {
    gr.u_caused_by_deployment = deploymentId;
    gr.update();
  }
}

Note: Customize the above logic for your organization.

Best Practices for Linking

  1. Link During Triage:

    • Add to incident creation workflow
    • Make it part of incident investigation checklist

  2. Only Link Definite Causes:

    • Don't link every incident to nearest deployment
    • Only link when deployment definitively caused the incident
    • If uncertain, investigate before linking

  3. Update if Root Cause Changes:

    • If initial assessment was wrong, update the link
    • Remove link if deployment wasn't the actual cause

  4. Document Linkage Decisions:

    • Add comments explaining why incident was linked
    • Include evidence (logs, error messages, timing)

Sending Deployment Events with change_id

For CFR calculation to work, deployment events must include the change_id that matches ServiceNow.

Example Deployment Event

curl -X POST https://prod.api.devgrid.io/events \
  -H "x-api-key: $DEVGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "event-deploy",
      "entityId": "my-application-id",
      "timestamp": "2025-10-29T18:30:00Z",
      "attributes": {
        "env": "production",
        "status": "success",
        "build_commit_sha": "a1b2c3d4e5f6789",
        "change_id": "CHG0012345",
        "change_url": "https://yourcompany.service-now.com/change.do?sys_id=abc123",
        "change_title": "Deploy v2.3.1 to production",
        "change_author": "[email protected]",
        "change_approver": "[email protected]"
      }
    }]
  }'

Critical field:

{
  "change_id": "CHG0012345"  // Must match ServiceNow change request number
}

Where to Get change_id

The change_id should come from your change management process:

Automated Change Management

If you use ServiceNow change requests for deployments:

  1. Create change request in ServiceNow (manually or via API)
  2. Get change number from ServiceNow (e.g., CHG0012345)
  3. Pass to CI/CD pipeline as environment variable
  4. Include in deployment event

Example GitHub Actions:

env:
  CHANGE_ID: CHG0012345  # From ServiceNow change request

steps:
  - name: Send deployment event
    run: |
      curl -X POST https://prod.api.devgrid.io/events \
        -H "x-api-key: ${{ secrets.DEVGRID_API_KEY }}" \
        -d '{
          "events": [{
            "type": "event-deploy",
            "entityId": "${{ vars.DEVGRID_ENTITY_ID }}",
            "attributes": {
              "change_id": "${{ env.CHANGE_ID }}"
            }
          }]
        }'

Manual Change Management

If change requests are created manually:

  1. Create change in ServiceNow before deployment
  2. Document change number in deployment runbook
  3. Include in deployment event when triggered

Generated Change IDs

If you generate your own change IDs:

  1. Use consistent format (e.g., CHG-YYYY-MM-DD-NNNN)
  2. Ensure IDs are unique
  3. Populate same ID in both:
    • Deployment events to DevGrid
    • Incident linkage field in ServiceNow

Incident State Mapping

DevGrid needs to understand which ServiceNow states mean "resolved."

Default State Mapping

ServiceNow StateDevGrid StatusIncluded in MTTR?
NewOpenNo
In ProgressOpenNo
On HoldOpenNo
ResolvedResolvedYes
ClosedResolvedYes
CanceledExcludedNo

Custom State Mapping

If your ServiceNow instance uses custom states:

  1. In DevGrid:

    • Go to Settings → Integrations → ServiceNow
    • Click Configure State Mapping

  2. Map Each Custom State:

    • Select ServiceNow state
    • Map to: Open, Resolved, or Excluded
    • Save

Example custom states:

  • Pending Vendor → Open
  • Awaiting Approval → Open
  • Resolution Verified → Resolved

Calculating MTTR

Once ServiceNow is integrated, DevGrid automatically calculates MTTR.

MTTR Calculation

MTTR = Average(Resolved Timestamp - Created Timestamp)

For all resolved incidents in the selected time period.

Viewing MTTR

  1. In DevGrid:

    • Go to Metrics → DORA Metrics
    • Select your application
    • View Mean Time to Restore

  2. Filter by Priority:

    • All Priorities (combined)
    • P1 (critical incidents only)
    • P2 (high priority)
    • P3 (moderate)
    • P4 (low)

  3. Select Time Period:

    • Last 7 days
    • Last 30 days
    • Last 90 days
    • Custom date range

MTTR Best Practices

  1. Resolve Incidents Promptly:

    • Close incidents when actually resolved
    • Don't leave in "Resolved" state indefinitely

  2. Accurate Timestamps:

    • Created timestamp should be when issue was detected
    • Resolved timestamp should be when service was restored

  3. Filter by Priority:

    • Track P1 MTTR separately from P3/P4
    • Different SLAs for different priorities

  4. Track Trends:

    • Monitor MTTR over time
    • Investigate spikes or degradations

Calculating Change Failure Rate

CFR is calculated once both deployment events and incident linkages are in place.

CFR Calculation

CFR = (Number of deployments causing incidents / Total deployments) × 100

Viewing CFR

  1. In DevGrid:

    • Go to Metrics → DORA Metrics
    • Select your application
    • View Change Failure Rate

  2. Breakdown:

    • Percentage: 25% (example)
    • Failed deployments: 5
    • Total deployments: 20
    • Time period: Last 30 days

CFR Requirements Checklist

  • ✅ Deployment events sent to DevGrid with change_id
  • ✅ ServiceNow integration connected
  • ✅ Custom field created for deployment linkage
  • ✅ Incidents linked to deployments in ServiceNow
  • ✅ Incidents resolved (not still open)

CFR Best Practices

  1. Only Link Actual Failures:

    • Don't link incidents unrelated to deployments
    • Be accurate - this affects important metrics

  2. Review Linkages Periodically:

    • Audit incident-deployment links monthly
    • Remove incorrect linkages
    • Add missing linkages

  3. Track by Environment:

    • Production CFR (most important)
    • Staging CFR (leading indicator)

  4. Set Improvement Goals:

    • DORA Elite: < 15% CFR
    • DORA High: 16-30% CFR

Troubleshooting

No Incidents Appearing in DevGrid

Check:

  1. ✅ ServiceNow integration status is "Connected"
  2. ✅ Last sync timestamp is recent
  3. ✅ Sync filters include your incidents (date range, state, priority)
  4. ✅ API credentials are valid
  5. ✅ DevGrid has network access to your ServiceNow instance

Solution:

  • Go to Settings → Integrations → ServiceNow
  • Click Test Connection
  • Review error messages
  • Check ServiceNow API logs

MTTR Shows N/A

Check:

  1. ✅ Incidents are in "Resolved" or "Closed" state
  2. ✅ Incidents have both Created and Resolved timestamps
  3. ✅ Date range includes resolved incidents
  4. ✅ Incidents are associated with your application

Solution:

  • Verify incidents are syncing (check DevGrid Incidents page)
  • Ensure incidents are actually resolved in ServiceNow
  • Wait for next sync (hourly)

CFR Shows N/A

Check:

  1. ✅ Deployment events include change_id
  2. ✅ Incidents are linked to deployments in ServiceNow
  3. ✅ Custom field name matches DevGrid configuration
  4. ✅ Change IDs in events match Change IDs in incidents

Solution:

  • Review deployment events: Do they include change_id?
  • Check ServiceNow: Are incidents populated with deployment links?
  • Verify field name: u_caused_by_deployment or custom name
  • See Troubleshooting Guide

Sync Failing

Common Errors:

Authentication Error

Error: 401 Unauthorized

Solution:

  • Verify ServiceNow username/password
  • Check integration user still exists and is active
  • Regenerate password and update in DevGrid

Missing Field Error

Error: Field u_caused_by_deployment does not exist

Solution:

  • Verify custom field was created in ServiceNow
  • Check field name matches DevGrid configuration
  • Ensure integration user has read access to custom field

Network Error

Error: Unable to connect to ServiceNow instance

Solution:

  • Verify instance URL is correct
  • Check network connectivity
  • Ensure ServiceNow instance is accessible from DevGrid
  • Check firewall rules

Incidents Not Linking to Deployments

Check:

  1. ✅ change_id in deployment event exactly matches value in ServiceNow incident
  2. ✅ No typos or extra spaces
  3. ✅ Case-sensitive match (if applicable)
  4. ✅ Custom field populated in ServiceNow

Example of mismatch:

❌ Deployment Event:

{
  "change_id": "CHG0012345"
}

❌ ServiceNow Incident:

Caused By Deployment: chg0012345  (lowercase - doesn't match!)

✅ ServiceNow Incident:

Caused By Deployment: CHG0012345  (exact match!)

Data Privacy & Security

Data Collected from ServiceNow

DevGrid collects the following incident data:

  • Incident number
  • Created timestamp
  • Resolved timestamp
  • Priority/severity
  • State
  • Deployment linkage field value
  • Assignment group (optional)

DevGrid does not collect:

  • Incident descriptions (may contain sensitive info)
  • Comments or work notes
  • Attachments
  • Caller information (unless explicitly configured)

Security Best Practices

  1. Use Dedicated Integration User:

    • Don't use personal ServiceNow account
    • Limit permissions to read-only on incident table

  2. Secure API Credentials:

    • Store password in DevGrid (encrypted at rest)
    • Don't share credentials
    • Rotate password periodically

  3. Network Security:

    • Use HTTPS for all API calls
    • Consider IP whitelisting if supported

  4. Audit Logging:

    • Monitor ServiceNow API access logs
    • Review DevGrid integration logs periodically

Advanced Configuration

Filtering Incidents by Assignment Group

Only sync incidents for specific teams:

  1. In DevGrid:

    • Go to Settings → Integrations → ServiceNow
    • Advanced Settings → Assignment Group Filter

  2. Add Assignment Groups:

    • Platform Team
    • Infrastructure Team
    • Application Support Team

  3. Save:

    • Only incidents assigned to these groups will sync

Multiple ServiceNow Instances

If your organization has multiple ServiceNow instances:

  1. Configure separate integration per instance
  2. Map instances to specific DevGrid applications
  3. Use different API credentials for each

Custom Incident Fields

To sync additional incident fields:

  1. Contact DevGrid Support
  2. Provide field names and data types
  3. DevGrid will configure custom field sync

Updated 3 months ago