Event collection via 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

Use these web service API's to insert records in the event table (em_event):
  • Web service API to create multiple records with a single call https://<instancename>.service-now.com/em_event.do?JSONv2&sysparm_action=insertMultiple
  • Web service API to create one record for each single call https://<instancename>.service-now.com/api/now/table/em_event

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 field of the event. For more information about how to include additional fields in events, see Populate custom alert fields.

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.
    Source Instance (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 can 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 deduplication 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 – Info, with the severity of 0 – Clear. Original severity values should be sent as part of the additional information.
    additional_info This field is in JSON key/value format, and is meant to contain any information that might be of use to the user. It does not map to a pre-defined ServiceNow event field. Examples include IDs of objects in the event source, event priority (if it is not the same as severity), assignment group information, and so on. Values in the Additional information field of an Event that are not in JSON key/value format are normalized to JSON format when the event is processed.
    time_of_event Time when the event occurred on the event origin.
    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://<instance name>.service-now.com/em_event.do?JSONv2&sysparm_action=insertMultiple
    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':'High',
         						'metric-value':'5833',
         						'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 <instance name> variable is replaced with the name of the required instance:
    https://<instancename>.service-now.com/api/now/table/em_event
    Note: Use of this URL is limited as far as the rate of events it can support.
    Example showing the payload for one event that is sent in a single web service call:
    {	"record":	
    [
         {
         "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':'41',
         						'os_type':'Windows.Server.2008'
         					}"
          }     
       ]
    }"