Plugin Configuration

Configure the plugin from the OpenNMS web interface at Plugins > ServiceNow.

Settings

Field Description

ServiceNow Base API URL

Your ServiceNow instance URL in the format https://<instance>.service-now.com

Username / Password

Credentials for the ServiceNow integration user (see ServiceNow Instance Setup)

Forward Alarms

Forward OpenNMS alarms to ServiceNow Event Management. Alarms are correlated using message_key (set to the OpenNMS reduction key).

Forward Events

Forward OpenNMS events to ServiceNow Event Management.

Forward Tickets

Create and update ServiceNow incidents from OpenNMS alarms. Requires the ticketer plugin (see Installation).

CMDB Import

Import configuration items from the ServiceNow CMDB.

Status

Shows Connected or Disconnected after saving.

Click Update to save the configuration.

Choosing between event and alarm forwarding

Alarm forwarding is recommended for alert lifecycle management. Alarms set message_key (the OpenNMS reduction key) which ServiceNow uses to correlate and deduplicate events into a single alert. When an alarm clears, the plugin sends a closing event that automatically closes the corresponding ServiceNow alert.

Event forwarding provides a raw audit trail in ServiceNow’s em_event table. Events do not set message_key, so each event creates a separate alert that cannot be automatically closed.

If both are enabled, node events will create duplicate alerts — one closeable (from alarm forwarding) and one that remains open (from event forwarding). In general, alarm forwarding alone is sufficient for most use cases. Enable event forwarding only if you need a record of every individual event in ServiceNow, and be aware that the resulting alerts will not auto-close.

How Ticket Forwarding Works

When Forward Tickets is enabled, the plugin creates and updates incidents in ServiceNow using the Incident Table API (/api/now/table/incident).

  • When a ticket is created in OpenNMS, a new incident is created in ServiceNow and the sys_id is stored as the ticket ID.

  • When a ticket is updated or closed in OpenNMS, the corresponding incident is updated in ServiceNow.

  • Alarm severity is mapped to ServiceNow impact and urgency fields.

  • When resolving an incident, close_code and close_notes are set automatically.

  • If the node label matches a configuration item in the ServiceNow CMDB, the incident is linked to it automatically.

  • Work notes are added with OpenNMS context (node label, node ID, IP address, alarm ID).

How CMDB Import Works

The ServiceNow Configuration Management Database (CMDB) is a central repository that stores information about your IT infrastructure — servers, routers, switches, applications, and their relationships. Each item in the CMDB is called a Configuration Item (CI).

When CMDB Import is enabled, the plugin imports CIs from ServiceNow into OpenNMS as managed nodes.

  • CIs are fetched from /api/now/table/cmdb_ci, filtered to those with a valid name and IP address.

  • Each CI is mapped to an OpenNMS node under the foreign source servicenow.

  • The import runs automatically every 24 hours and on plugin startup (after a 2-minute delay to allow services to initialize).

  • An immediate import is also triggered whenever the plugin configuration is saved.

CMDB CI Field OpenNMS Node Field

sys_id

Foreign ID

name

Node Label

ip_address

Primary IP Interface

sys_class_name

Node Category (defaults to "ServiceNow")

serial_number

Asset: Serial Number

asset_tag

Asset: Asset Number

manufacturer

Asset: Vendor

model_id

Asset: Model Number

os

Asset: Operating System

description

Asset: Description

Additionally, when creating incidents with Forward Tickets enabled, the plugin automatically links the incident to a CMDB CI if the OpenNMS node label matches a CI name in ServiceNow.

Field Mappings

Event and Alarm Mapping

Events and alarms are sent to the ServiceNow Event Web Service API (/api/global/em/jsonv2). Events use event_class = OpenNMS.Event and alarms use event_class = OpenNMS.Alarm.

ServiceNow Field OpenNMS Source (Events) OpenNMS Source (Alarms)

source

Instance ID (opennms.instance.id system property)

Instance ID (opennms.instance.id system property)

event_class

OpenNMS.Event

OpenNMS.Alarm

node

Node label (from NodeDao)

Node label (from alarm)

resource

IP address : service name (falls back to node label)

Event parameter: ifIpAddress : service (falls back to node label)

metric_name

Event parameter: ds, metric, ifDescr, ifLabel, or service name

Event parameter: ds, metric, ifDescr, ifLabel (falls back to managed object type)

type

Event UEI

Last event UEI

severity

Mapped from event severity (see table below)

Mapped from alarm severity (see table below)

description

Event parameter: description, reason, or eventReason

Alarm description

additional_info

All event parameters (JSON)

Alarm ID, reduction key, acknowledged (JSON)

time_of_event

Event time (UTC)

Last event time (UTC)

resolution_state

New

New (or Closing when severity is CLEARED)

message_key

(not set)

Alarm reduction key (for correlation)

ci_identifier

Node label

Node label

Severity Mapping (Events and Alarms)

OpenNMS Severity ServiceNow Severity

CRITICAL

1 (Critical)

MAJOR

2 (Major)

MINOR

3 (Minor)

WARNING

4 (Warning)

CLEARED

0 (Clear)

NORMAL / INDETERMINATE

5 (OK)

Incident Mapping (Ticketing)

Incidents are created and updated via the ServiceNow Incident Table API (/api/now/table/incident).

ServiceNow Incident Field OpenNMS Source

short_description

Node label + alarm log message (e.g., mynode: OpenNMS: High threshold exceeded)

description

Alarm description

caller_id

Ticket user (if set)

state

Ticket state: OPEN = 1 (New), CLOSED = 6 (Resolved), CANCELLED = 8 (Cancelled)

impact

Mapped from alarm severity (see table below)

urgency

Mapped from alarm severity (see table below)

correlation_id

OpenNMS:Alarm:<alarmId>

category

Network

cmdb_ci

CMDB CI sys_id (if node label matches a CI name in ServiceNow)

work_notes

OpenNMS context: instance ID, node label, node ID, IP address, alarm ID

close_code

Solution provided (set when resolving)

close_notes

Resolved via OpenNMS alarm lifecycle. OpenNMS Alarm ID: <id>

Impact and Urgency Mapping

OpenNMS Alarm Severity ServiceNow Impact ServiceNow Urgency

CRITICAL

1 (High)

1 (High)

MAJOR

1 (High)

2 (Medium)

MINOR

2 (Medium)

2 (Medium)

WARNING

2 (Medium)

3 (Low)

Other

3 (Low)

3 (Low)

State Mapping (ServiceNow to OpenNMS)

When reading incidents back from ServiceNow:

ServiceNow Incident State OpenNMS Ticket State

1 (New), 2 (In Progress), 3 (On Hold)

OPEN

6 (Resolved), 7 (Closed)

CLOSED

8 (Cancelled)

CANCELLED

Filtering

The plugin supports JEXL expression-based filters for events, alarms, and tickets, plus a ServiceNow query filter for CMDB imports. Configure filters from the Filters tab in the plugin UI.

  • An empty filter means all items pass through (no filtering).

  • Invalid filter expressions are rejected at save time with an inline error message. The previously saved valid filter is preserved.

  • At runtime, if a compiled filter fails to evaluate, the item passes through (fail-open).

Event Filter

Controls which OpenNMS events are forwarded to ServiceNow Event Management.

The default filter excludes internal and trouble ticket events:

!(event.uei =~ 'uei.opennms.org/internal/.*') and !(event.uei =~ 'uei.opennms.org/troubleTicket/.*')
Table 1. Available fields
Field Description

event.uei

Event unique identifier (UEI)

event.severity

Event severity object (use event.severity.id for numeric comparison)

event.nodeId

Node ID (integer)

event.service

Service name

event.parameters

Event parameters (list)

Alarm Filter

Controls which OpenNMS alarms are forwarded to ServiceNow Event Management.

The default filter excludes internal and trouble ticket alarms:

!(alarm.reductionKey =~ 'uei.opennms.org/internal/.*') and !(alarm.reductionKey =~ 'uei.opennms.org/troubleTicket/.*')
Table 2. Available fields
Field Description

alarm.reductionKey

Alarm reduction key

alarm.id

Alarm ID (integer)

alarm.severity

Alarm severity object (use alarm.severity.id for numeric comparison)

alarm.node.label

Node label

alarm.node.location

Node location

alarm.situation

Whether the alarm is a situation (boolean)

alarm.acknowledged

Whether the alarm is acknowledged (boolean)

alarm.logMessage

Alarm log message

alarm.description

Alarm description

alarm.type

Alarm type
Cleared alarms are always sent with severity 0 and resolution state Closing, allowing ServiceNow to close the corresponding alert.

Ticket Filter

Controls which alarms are eligible for incident creation in ServiceNow. The filter is evaluated against the alarm associated with the ticket.

An empty filter (the default) allows incidents for all alarms.

Example: Only create incidents for MAJOR or higher severity
alarm.severity.id >= 4

The available fields are the same as the Alarm Filter.

CMDB Filter

Controls which configuration items are imported from the ServiceNow CMDB. This filter uses ServiceNow sysparm_query syntax (not JEXL) and is appended to the base query that requires a valid name and IP address.

An empty filter (the default) imports all CIs with a name and IP address.

Examples
sys_class_name=cmdb_ci_server
sys_class_nameINcmdb_ci_server,cmdb_ci_linux_server^manufacturer=Dell

JEXL Expression Syntax

Filters use Apache JEXL 3 expression syntax.

Table 3. Operators
Operator Description

==, !=

Equality / inequality

<, ⇐, >, >=

Numeric comparison

=~

Regex match (e.g., event.uei =~ 'uei.opennms.org/internal/.*')

!~

Regex non-match

and, or, not / !

Logical operators
Examples
# Forward only MAJOR (4) or higher severity
alarm.severity.id >= 4

# Exclude internal events and only forward MINOR or higher
!(event.uei =~ 'uei.opennms.org/internal/.*') and event.severity.id >= 3

# Only forward acknowledged alarms from a specific location
alarm.acknowledged and alarm.node.location == 'DC-East'

Customizing Filters in ServiceNow

You can customize how events are transformed into alerts by configuring Event Rules in ServiceNow:

  1. Navigate to All > Event Management > Event Rules in ServiceNow.

  2. Create rules to filter by event_class, severity, source, or other fields.

  3. Event Rules control how event fields map to alert fields (e.g., severity, description, node).