Configure the MID WebService Event Collector Context

Configure the MID WebService Event Collector Context to provide a URL method to push event messages from an external source to the MID Server.

Before you begin

Ensure that the Event Management Connectors (sn_em_connector) plugin is installed on the ServiceNow AI Platform instance.

Role required: evt_mgmt_admin

About this task

The default format of the URL to push event messages from an external source to the MID Server is http://{MID_Server_IP}:{MID_Web_Server_Port}/api/mid/em/jsonv2. This URL provides good performance.

From an external source, to push event messages that are not in jsonv2 format, the format of the URL is: http://{MID_Server_IP}:{MID_Web_Server_Port}/api/mid/em/inbound_event?Transform={Name_of_Transform_Script}, where the {Name_of_Transform_Script} variable is the full name of the script and always begins with the text: TransformEvents_.

For example, assume the following values:

• {MID_Server_IP}: 10.118.69.27
• {MID_Web_Server_Port}: 8097
• Transform script name: EventsToProcess

The URL to be used is therefore: http://10.118.69.27:8097/api/mid/em/inbound_event/TransformEvents_EventsToProcess

Note:

• The URL in the format http://{MID_Server_IP}:{MID_Web_Server_Port}/api/mid/em/{transform_script_name}is also supported.

• The date format for events is yyyy-M-d h:mm:ss.

  If you receive an event whose date is in a different format, you must use a {transform_script_name} that is appropriate for the incoming event's date format. If you do not, the event will not be processed correctly.

  For example, if an event arrives on June 27, 2019 at 11:25 AM with a listed date of 2019/06/27/ 11:25:00 a, use a {transform_script_name} with a date format of yyyy/MM/dd/ HH:mm:ss a to match the format of the received event.

Procedure

1. Navigate to All > Event Management > Integrations > MID WebService Event Listener.

2. In the MID WebService Event Collector Contexts list, click New.

3. On the form, fill in the fields.

1. Right-click the form heading and click Save.

2. Under Related Links, click Start to start the collector.

   Related Link	Description
   Start	If it is not running, start the collector. This action verifies that a web service API endpoint with the Event Management application is running on the MID Server.
   Stop	Stops the running collector on the configured MID Server. If the collector is not running, no action is taken.
   Restart	Stops, then starts the collector on the configured MID Server.
   Update parameters	Sends updated parameters to the collector. Parameters are also updated when the Event Management MID Server context extension is updated. If you click this control when the collector is not running, no update is made.

Example

Showing the use of the URL to transform JSON v2 formatted event messages

Assume that JSON v2 formatted event messages are sent to the MID Server. When using the jsonv2 URL, there is no need to use a script include.

Replace the variables in the default format of the URL http://<my-instance>.service-now.com/api/global/em/jsonv2with values from the preceding table:http://10.218.64.27:8097/api/global/em/jsonv2

Example showing the URL to push messages not in jsonv2 format

The format of the URL to push event messages from an external source that are not in jsonv2 format is http://{MID_Server_IP}:{MID_Web_Server_Port}/api/mid/em/inbound_event/Transform={Name_of_Transform_Script} where the {Name_of_Transform_Script} variable is the full name of the script and always begins with the text: TransformEvents_. The script name must be specified as the Transform header parameter and must always start with the prefix TransformEvents_.

For this example, assume that the script name is EventsToProcess, the URL is therefore:http://10.138.64.27:8097/api/mid/em/inbound_event/TransformEvents_EventsToProcess

Example showing JSON v2 formatted event messages

Note: When copying and pasting the text following, hidden characters might also be copied and can cause unexpected results.

curl -v -H "Accept: application/json" -H "Content-Type: application/json" -X POST --data "{
    \"records"\:
    [ {
         \"source\" : \"Simulated\",
        \"node\" : \"nameofnode\",
        \"type\" : \"High Virtual Memory\",
        \"resource\" : \"C:\",
        \"severity\" : \"5\",
        \"description\" : \"Virtual memory usage exceeds 98%\",
        \"ci_type\":\"cmdb_ci_app_server_tomcat\",
        \"additional_info\":\"{\\\"name\\\":\\\"My Airlines\\\"}\"
      },
      {
      \"source\" : \"Simulated\",
      \"node\" : \"01.myairlines.com\",
      \"type\" : \"High CPU Utilization\",
      \"resource\" : \"D:\",
      \"severity\" : \"5\",
      \"description\" : \"CPU on 01.my.com at 60%\"
      }
   ]
}" -u UserName:Password http://{MID_Server_IP}:{MID_Web_Server_Port}/api/mid/em/jsonv2

Example

Example showing JSON v2 formatted event messages with MID Web Server API key

Note: When copying and pasting the text following, hidden characters might also be copied and can cause unexpected results.

curl --location -g --request POST 'http://{MID_Server_IP}:{MID_Web_Server_Port}/api/mid/em/jsonv2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: key <mid_webserver_api_key>' \
--data-raw '{
   "records":
    [ {
         \"source\" : \"Simulated\",
        \"node\" : \"nameofnode\",
        \"type\" : \"High Virtual Memory\",
        \"resource\" : \"C:\",
        \"severity\" : \"5\",
        \"description\" : \"Virtual memory usage exceeds 98%\",
        \"ci_type\":\"cmdb_ci_app_server_tomcat\",
        \"additional_info\":\"{\\\"name\\\":\\\"My Airlines\\\"}\"
      },
      {
      \"source\" : \"Simulated\",
      \"node\" : \"01.myairlines.com\",
      \"type\" : \"High CPU Utilization\",
      \"resource\" : \"D:\",
      \"severity\" : \"5\",
      \"description\" : \"CPU on 01.my.com at 60%\"
      }
   ]
}'

Configuring external API integrations with MID Server failover

To ensure high availability for external API integrations, deploy an external load balancer that distributes traffic across multiple MID servers. Note that the MID cluster web server configuration handles internal processing only (through ecc_queue) and can't manage inbound external API traffic.

Reference the external load balancer hostname in your webhook URL rather than individual MID Server addresses. Replace the variables in the default format: https://<load-balancer>/api/mid/em/inbound_event?Transform=<format> with values from the preceding table: https:///mid-cluster.example.com/api/mid/em/inbound_event?Transform=jsonv2.

This configuration distributes incoming requests across both MID servers, and if one server becomes unavailable, the load balancer automatically routes traffic to the remaining operational server without service interruption.

Related topics

Configure the MID Web Server extension

Event collection from BMC TrueSight

Event collection from Microsoft Azure Monitor

Event collection from Google Cloud Platform