Incidents & ITSM

Overview

The Incidents & ITSM plugin connects NetStacks to your IT Service Management platform, enabling automatic incident creation from alerts, bi-directional status synchronization, and unified incident tracking across your network operations and service desk workflows.

Supported ITSM Platforms

• ServiceNow -- full integration with Incident, Change, and CMDB tables via REST API
• Jira Service Management -- create and sync incidents via Jira REST API with custom field mapping

Key Features

• Auto-creation rules -- define which alerts automatically create ITSM incidents based on severity, source, and device criteria
• Bi-directional sync -- status changes, comments, and assignments sync between NetStacks and the ITSM platform in both directions
• Severity mapping -- map NetStacks alert severity levels to ITSM priority values
• Resolution sync -- when an incident is resolved in the ITSM platform, the corresponding NetStacks alert is automatically resolved

How It Works

Alert-to-Incident Flow

1. Alert triggers -- an alert in the Alert Pipeline matches an auto-creation rule configured in the Incidents plugin
2. Incident creation -- the plugin calls the ITSM platform API to create an incident with mapped fields (summary, description, priority, assignment group)
3. Linking -- the ITSM incident ID is stored against the NetStacks alert, creating a bi-directional reference
4. Sync loop -- a background sync process polls the ITSM platform for status changes and updates the NetStacks alert accordingly (and vice versa)
5. Resolution -- when the incident is resolved on either side, the resolution is synced to the other platform

Bi-Directional Sync

The sync process runs at a configurable interval (default 60 seconds). It checks for changes on both sides:

• NetStacks → ITSM: alert acknowledged, alert resolved, comments added, severity changed
• ITSM → NetStacks: incident assigned, status changed, comments added, priority updated, incident resolved

Severity-to-Priority Mapping

Priority mapping is fully customizable in the plugin configuration.

Step-by-Step Guide

Workflow 1: Configure ServiceNow Integration

1. Navigate to Administration → Plugins → Incidents & ITSM
2. Select ServiceNow as the ITSM platform
3. Enter your ServiceNow instance URL (e.g., https://company.service-now.com)
4. Enter the service account username and password or OAuth credentials
5. Click Test Connection to verify connectivity
6. Configure field mapping (assignment group, category, impact)
7. Click Save & Start

Workflow 2: Configure Jira Service Management Integration

1. Select Jira Service Management as the ITSM platform
2. Enter the Jira Cloud URL and generate an API token from your Atlassian account
3. Select the Jira project and issue type for incidents
4. Map custom fields (priority, assignee, labels) to NetStacks alert fields
5. Click Test Connection and then Save & Start

Workflow 3: Set Up Auto-Creation Rules

1. Navigate to Incidents → Auto-Creation Rules
2. Click Add Rule
3. Define which alerts trigger incident creation: severity level, source, device pattern, labels
4. Set the incident template: priority mapping, assignment group, description format
5. Enable or disable the rule and save

Workflow 4: Monitor Sync Status

1. Navigate to Incidents → Sync Status
2. View the sync dashboard showing last sync time, pending changes, and any sync errors
3. Click a synced incident to see the full history of changes on both sides

Code Examples

ServiceNow Connection Configuration

{
  "platform": "servicenow",
  "instance_url": "https://company.service-now.com",
  "auth": {
    "type": "oauth",
    "client_id": "your_client_id",
    "client_secret": "********",
    "token_url": "https://company.service-now.com/oauth_token.do"
  },
  "table": "incident",
  "field_mapping": {
    "short_description": "{{alert.message}}",
    "description": "Alert from {{alert.device}} at {{alert.timestamp}}\n\nDetails: {{alert.labels | json}}",
    "urgency": "{{severity_map[alert.severity]}}",
    "assignment_group": "Network Operations",
    "category": "Network",
    "subcategory": "{{alert.labels.protocol}}"
  },
  "sync_interval_seconds": 60
}

Jira Service Management Configuration

{
  "platform": "jira",
  "base_url": "https://company.atlassian.net",
  "auth": {
    "type": "api_token",
    "email": "service-account@company.com",
    "api_token": "********"
  },
  "project_key": "NOC",
  "issue_type": "Incident",
  "field_mapping": {
    "summary": "[NetStacks] {{alert.message}}",
    "description": "Alert Details:\n* Device: {{alert.device}}\n* Severity: {{alert.severity}}\n* Source: {{alert.source}}\n* Time: {{alert.timestamp}}",
    "priority": "{{severity_map[alert.severity]}}",
    "labels": ["netstacks", "{{alert.labels.protocol}}"]
  }
}

Incident Auto-Creation Rule

{
  "name": "Critical core device alerts",
  "enabled": true,
  "match": {
    "severity": ["critical"],
    "device_pattern": "core-*",
    "labels": {
      "protocol": ["bgp", "ospf", "isis"]
    }
  },
  "incident_template": {
    "priority": "P1",
    "assignment_group": "Network Operations",
    "description_format": "Critical {{alert.labels.protocol}} alert on {{alert.device}}: {{alert.message}}",
    "auto_resolve": true,
    "resolve_on": "alert.resolved"
  }
}

Test ITSM Connectivity

# Test ServiceNow connection
curl -X POST https://netstacks.example.com/api/v1/plugins/incidents/test-connection \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"platform": "servicenow"}'

# Response
{
  "status": "success",
  "platform": "servicenow",
  "instance": "company.service-now.com",
  "api_version": "v2",
  "permissions": {
    "incident_read": true,
    "incident_write": true,
    "cmdb_read": true
  }
}

Example Incident Payload

{
  "incident_id": "INC0012345",
  "netstacks_alert_id": "alert_abc123",
  "platform": "servicenow",
  "status": "open",
  "priority": "P1",
  "summary": "BGP peer 10.0.0.2 down on core-rtr-01.dc1",
  "device": "core-rtr-01.dc1",
  "created_at": "2025-12-15T14:31:00Z",
  "assigned_to": "Network Operations",
  "sync_status": "synced",
  "last_synced": "2025-12-15T14:32:00Z",
  "changes": [
    {
      "timestamp": "2025-12-15T14:31:00Z",
      "source": "netstacks",
      "action": "created",
      "details": "Auto-created from critical BGP alert"
    }
  ]
}

Terminal Integration

Starting with v0.0.9, incidents can be managed directly from the NetStacks Terminal without switching to the Admin UI. The Terminal activity bar includes an Incidents panel that provides full CRUD access to your incident data.

IncidentDetailTab

Click any incident in the sidebar list to open it in a detail tab. The IncidentDetailTab supports three modes:

• Create — open a blank form to create a new incident with title, description, severity, and assignment fields
• View — read-only view of incident details including ITSM sync status, timeline, and resolution data
• Edit — inline editing for incident title, description, and severity directly in the detail view. Click any editable field to modify it in place.

Comment Threads

Add comments to incidents directly from the Terminal. Comments are bi-directionally synced with the connected ITSM platform. Each comment shows the author, timestamp, and sync status.

Activity Bar Integration

The Incidents icon in the Terminal activity bar opens a sidebar panel listing all incidents with clickable rows. Use the Create button to start a new incident, or click an existing incident to open its detail tab. The sidebar supports filtering by status and severity.

Q&A

Q: Which ITSM platforms are supported?

A: NetStacks currently supports ServiceNow and Jira Service Management. Both support full bi-directional sync including incident creation, status updates, comments, and resolution. Additional platforms can be added through the plugin system.

Q: How does bi-directional sync work?

A: A background process polls both NetStacks and the ITSM platform at a configurable interval (default 60 seconds). Changes detected on either side (status updates, comments, assignments, resolution) are synced to the other platform. Conflict resolution uses last-write-wins based on timestamps.

Q: How do I map alert severity to incident priority?

A: The severity-to-priority mapping is configured in the plugin settings. The default maps Critical to P1, Warning to P2, and Info to P3. You can customize this mapping for your organization's priority scheme in the field mapping configuration.

Q: Can I customize which alerts create incidents?

A: Yes. Auto-creation rules define exactly which alerts trigger incident creation based on severity, source, device pattern, and label selectors. You can create multiple rules with different criteria and incident templates for different scenarios.

Q: What happens if the ITSM platform is unreachable?

A: When the ITSM platform is unreachable, incident creation and sync operations are queued and retried automatically with exponential backoff. Alerts continue to be processed normally in NetStacks. The sync status dashboard shows pending operations and connection errors.

Q: How do I set up ServiceNow integration?

A: Navigate to Administration → Plugins → Incidents & ITSM, select ServiceNow, enter your instance URL, configure OAuth credentials (or basic auth with a service account), map fields to ServiceNow incident table columns, and test the connection. See the step-by-step guide above for details.

Troubleshooting

ITSM Connection Failures

• Verify the instance URL is correct and accessible from the NetStacks server
• Check that the service account credentials are valid and have not expired
• For OAuth, verify the client ID and secret are correct and the token endpoint is accessible
• Use the Test Connection button to diagnose specific errors

Sync Conflicts

• Sync conflicts occur when the same field is updated on both platforms between sync intervals. The last-write-wins strategy is used by default
• Increase the sync interval to reduce the chance of conflicts, or configure specific fields as one-directional

Duplicate Incidents

• Duplicate incidents can occur if the Alert Pipeline deduplication window is too short and the same alert creates multiple incidents
• Check the auto-creation rule to ensure it is not too broad in its match criteria
• Enable the "check existing" option in the auto-creation rule to query the ITSM platform for existing incidents before creating a new one

Field Mapping Errors

• Verify field names match the ITSM platform's schema exactly (ServiceNow uses snake_case, Jira uses specific field IDs)
• Check that mapped values are valid for the target field type (e.g., priority values must match the platform's allowed values)
• Review the sync error log for specific field validation failures

Authentication Issues

• ServiceNow OAuth tokens expire -- ensure the refresh token flow is configured correctly
• Jira API tokens are tied to the user account -- verify the account has the required project permissions
• Rotate credentials periodically and update them in the plugin configuration

Related Features

• Plugin System -- understand the plugin architecture powering the Incidents integration
• Alert Pipeline -- the alert source that feeds incidents to ITSM platforms
• System Settings -- configure system-wide settings affecting incident creation
• Task Monitoring -- monitor automation tasks triggered by incident events