Pushing events to the instance using web service API

You can use a web service interface, supported by ServiceNow, that operates on the JSON object as the data input and output format.

Before you begin

Role required: evt_mgmt_integration

About this task

To insert records in the event [em_event] table with a single call, use this web service API:

https://<instancename>.service-now.com/api/global/em/jsonv2

Note:

Business rules on the event table are not invoked when this URL is used.

Do not add additional fields to an event by adding a custom field to the event table [em_event]. However, additional fields should be included in the Additional information [additional_info] field of the event. For more information about how to include additional fields in events, see Custom alert fields.

For information about troubleshooting performance issues with inbound integrations, see Troubleshooting inbound integrations performance.

The URL in the format: http://<instancename>.service-now.com/em_event.do?JSONv2&sysparm_action=insertMultiple is also supported in case you do want to activate Business rules. However, the performance of the first URL is superior.

To work with the URL that ends with =insertMultiple, add the following properties, with their respective values, to the MID Server:

• "mid.probe.event.queue.compress" - value: false
• "mid.probe.event.bulk_size" - value: 100
• "mid.probe.event.endpoint.url" - value: em_event.do?JSONv2%26sysparm_action=insertMultiple

Procedure

1. Send the request with these headers:

   Parameter	Type	Description
   Accept	String	The acceptable type for this message. The default value is application/json.
   Content-Type	String	The content type for this message. The default value is application/json.
   POST	String	The request type is POST, with one or more trailing records.

2. One or more events in JSON format can be sent as the payload of the web service call.
   Event fields that should be populated are:

   Variable	Description
   source	The name of the event source type. For example, SCOM or SolarWinds.
   event_class	Specific instance of the source. For example, SCOM 2012 on 10.20.30.40
   node	The node field should contain an identifier for the Host (Server/Switch/Router/etc.) that the event was triggered for. The value of the node field can be one of the following identifiers of the Host: Name FQDN IP Mac Address If it exists in the CMDB, this value is also used to bind the event to the corresponding ServiceNow CI.
   resource	If the event refers to a device, such as, Disk, CPU, or Network Adapter, or to an application or service running on a Host, the name of the device or application must be populated in this field. For example, Disk C:\ or Nic 001 or Trade web application.
   metric_name	Name of the metric that triggered the alert. For example, Used Memory or Total CPU utilization.
   type	The type of event. This type might be similar to the metric_name field, but is used for general grouping of event types.
   message_key	This value is used for de-duplication of events. For example, there might be two events for the same CI, where one event has CPU of 50% and the next event has CPU of 99%. Where both events must be mapped to the same ServiceNow alert, they should have the same message key. The field can be left empty, in which case the field value defaults to source+node+type+resource+metric_name. The message_key should be populated only when there is a better identifier than the default.
   severity	Severity of the event. ServiceNow values for severity range from 1 – Critical to 5 – OK, with the severity of 0 – Clear. Original severity values should be sent as part of the additional information.
   additional_info	This field contains a JSON string (stringified JSON) with key/value pairs representing supplemental information not mapped to standard event fields. Examples include IDs of objects in the event source, event priority (if different from severity), and assignment group information. Values not already in JSON key/value format are normalized to stringified JSON when the event is processed.
   time_of_event	Time when the event occurred on the event origin. The format is: yyyy-MM-dd HH:mm:ss The specified time must be according to GMT.
   resolution_state	Optional – To indicate that an event has been resolved or no longer occurring, some event monitors use ‘clear’ severity, while other event monitors use a ‘close’ value for severity. This field is used for those monitors proffering the latter. Valid values are New and Closing.

3. To create multiple records with a single call, trigger the event web service using the following URL, where the <instance name> variable is replaced with the name of the required instance:
   https://<instancename>.service-now.com/api/global/em/jsonv2
   Example showing the payload for two events that are sent in a single web service call:

   {
     "records": [
       {
         "source": "SCOM",
         "event_class": "SCOM 2012 on scom.server.com",
         "resource": "D:",
         "node": "name.of.node.com",
         "metric_name": "Percentage Logical Disk Free Space",
         "type": "Disk space",
         "severity": "4",
         "description": "The disk D: on computer V-W2K8-abc.abc.com is running out of disk space. The value that exceeded the threshold is 38% free space.",
         "additional_info": "{\"scom-severity\": \"Medium\", \"metric-value\": \"38\", \"os_type\": \"Windows.Server.2008\"}"
         }
       },
       {
         "source": "SCOM",
         "event_class": "SCOM 2012 on scom.server.com",
         "resource": "MSSQL-database-name",
         "node": "other.node.com",
         "metric_name": "DB Allocated Size (MB)",
         "type": "Database Storage",
         "severity": "3",
         "description": "High number of active connections for MSSQL-database-name running on name.of.node.com. Active connections exceed 5000.",
         "additional_info": "{\"scom-severity\": \"Medium\", \"metric-value\": \"38\", \"os_type\": \"Windows.Server.2008\"}"
         }
       }
     ]
   }

4. To create one record with a single call, trigger the event web service using the following URL, where the <instancename> variable is replaced with the name of the required instance:
   https://<instancename>.service-now.com/api/global/em/jsonv2
   Example showing the payload for one event that is sent in a single web service call:

   {
     "records": [
       {
         "source": "SCOM",
         "event_class": "SCOM 2007 on scom.server.com",
         "resource": "C:",
         "node": "name.of.node.com",
         "metric_name": "Percentage Logical Disk Free Space",
         "type": "Disk space",
         "severity": "4",
         "description": "The disk C: on computer V-W2K8-dfg.dfg.com is running out of disk space. The value that exceeded the threshold is 41% free space.",
         "additional_info": "{\"scom-severity\": \"Medium\", \"metric-value\": \"38\", \"os_type\": \"Windows.Server.2008\"}"
         }
       }
     ]
   }

   Example: cURL request:

   {
     curl -X POST "https://<instancename>.service-now.com/api/global/em/jsonv2" \
     --header "Content-Type: application/json" \
     --user "username:password" \
     --data '{
       "records": [
         {
           "source": "SCOM",
           "event_class": "SCOM 2007 on scom.server.com",
           "resource": "C:",
           "node": "name.of.node.com",
           "metric_name": "Percentage Logical Disk Free Space",
           "type": "Disk space",
           "severity": "4",
           "description": "The disk C: on computer V-W2K8-dfg.dfg.com is running out of disk space. The value that exceeded the threshold is 41% free space.",
           "additional_info": "{\"scom-severity\": \"Medium\", \"metric-value\": \"38\", \"os_type\": \"Windows.Server.2008\"}"
           }
         }
       ]
     }'
    

Related concepts

• Pushing events to the MID Server using web service API