Managing events with REST APIs
The following section provides a list of supported endpoints and an overview about running these endpoints. Before you run an endpoint, you must authenticate yourself. For more information, see Access and authentication for the REST API
Managing event classes
You can create, update, delete, and get details of event classes by running APIs.
Important
Creating event class slots with the same name but different data types across multiple custom classes are not supported.
For example, if the application slot is defined as a String in MyCustomClass, then it cannot be defined as an Integer in MyOtherClass.
POST /events/classes
Create an event class
Important
Make sure that you specify the request body only in the English locale.
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Request body
"name": "<class_name>",
"parentClassName": "<parent_classname>",
"attributes": [
{
"name":"<slot_name1>",
"dataType":"<slot_datatype>",
"default":"<default_value>",
"enum":<enum>,
"allFacet":[
{
"name":"<facet1>",
"value":"<value>"
},
{
"name":"<facet2>",
"value":"<value>"
}
]
},
{
"name": "<slot_name2>",
"dataType": "<slot_datatype>"
}
]
}
Example request body
Creating an event class
"name": "NAGIOS_EV",
"parentClassName": "EVENT",
"attributes": [
{
"name":"pn_severity",
"dataType":"SEVERITY",
"default":"WARNING",
"enum":true,
"allFacet":[
{
"name":"mandatory",
"value":"true"
}
]
},
{
"name": "N_SERVICEPROBLEMID",
"dataType": "INTEGER"
}
]
}
Specifying a custom enumeration as a custom class attribute
Here, ROUTER_STATE, custom_slot_german, and custom_slot_chinese are custom enumeration names.
For information about managing custom enumerations, see Managing-custom-enumerations-with-REST-APIs.
"name": "custom_class_enum_display",
"parentClassName": "EVENT",
"attributes": [
{
"name": "ROUTER_STATE",
"dataType": "ROUTER_STATE",
"default": "UP",
"enum": true,
"allFacet": []
},
{
"name": "custom_slot_german",
"dataType": "custom_slot_german",
"default": "open",
"enum": true,
"allFacet": [
{
"name": "dup_detect",
"value": "true"
}
]
},
{
"name": "custom_slot_chinese",
"dataType": "custom_slot_chinese",
"default": "minor",
"enum": true,
"allFacet": [
{
"name": "dup_detect",
"value": "true"
}
]
}
]
}
Successful response
"responseTimeStamp": 1600258296455,
"statusCode": "OK",
"statusMsg": "[Successfully created event class.]",
"resourceId": [
"c48b5ac9-f815-11ea-9387-4b66d296b3bd"
],
"resourceName": null,
"failedResource": null
Unsuccessful responses
Scenario 1: Duplicate class
"responseTimeStamp": 1600423987155,
"statusCode": "EVCLASS_ALREADY_EXIST",
"statusMsg": "[Failed to create event class, entry with same name already exists]",
"resourceId": null,
"resourceName": null,
"failedResource": null
}
Scenario 2: Invalid parent class
"responseTimeStamp": 1600424373056,
"statusCode": "PARENTCLASS_NOT_EXIST",
"statusMsg": "[Failed to create event class, parent class doesn't exists]",
"resourceId": null,
"resourceName": null,
"failedResource": null
}
Scenario 3: Mandatory field (class name) missing
{
"key": "validation.schema.required",
"level": "ERROR",
"message": "Object has missing required properties ([\"name\"])",
"additionalInfo": []
}
]
Scenario 4:
- Enum value missing for enum data type
- Invalid enum value for enum data type
"statusCode": "ENUM_NOT_EXIST",
"statusMsg": "[Validation failed, enum doesn't exist]",
"resourceId": null,
"resourceName": null,
"failedResource": null
}
"responseTimeStamp": 1567511499957,
"statusCode": "400",
"statusMsg": "Bad Request : Enum value is either not supplied or false for data type PRIORITY"
}
PUT /events/classes
Update an event class
While updating an event class:
You Can | You Cannot |
|---|---|
Add new slots to the existing event class. | Rename the slot. |
Update the default slot value and facets. | Change the slot data type and enum information. |
Delete the slot. |
Note
Make sure that you specify the request body only in the English locale.
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details (in the request URL)
Request body
"attributes":[
{
"name":"<slot_name1>",
"dataType":"<slot_datatype>",
"default":"<default_value>",
"enum":<enum>,
"allFacet":[
{
"name":"<facet1>",
"value":"<value>"
},
{
"name":"<facet2>",
"value":"<value>"
}
]
}
]
}
Parameter details (in the request body)
Example request body
"attributes":[
{
"name":"pn_slot",
"dataType":"STRING",
"enum":false
}
]
}
Successful response
"responseTimeStamp": 1600258534062,
"statusCode": "OK",
"statusMsg": "[Successfully updated event class.]",
"resourceId": [
"c48b5ac9-f815-11ea-9387-4b66d296b3bd"
],
"resourceName": null,
"failedResource": null
}
Unsuccessful responses
Scenario 1: Valid ID, same attributes, but incorrect data type
"responseTimeStamp": 1600258908501,
"statusCode": "ATTR_EXIST_WITH_DIFF_TYPE",
"statusMsg": "[Validation failed, class attribute already exist with different data type]",
"resourceId": null,
"resourceName": null,
"failedResource": null
}
Scenario 2: New enum value for enum data type
"responseTimeStamp": 1567574692841,
"statusCode": "400",
"statusMsg": "Bad Request : Enum value is either not supplied or false for data type SEVERITY"
}
Scenario 3: Invalid class ID
"responseTimeStamp": 1600258782398,
"statusCode": "EVCLASS_NOT_EXIST",
"statusMsg": "[Failed to update event class, given entry doesn't exist in database]",
"resourceId": null,
"resourceName": null,
"failedResource": null
}
DELETE /events/classes
Delete a single event class by ID
Note
You can only delete custom event classes and not out-of-the-box event classes.
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Successful responses
"responseTimeStamp": 1600258614402,
"statusCode": "OK",
"statusMsg": "[Event class deletion successful.]",
"resourceId": [
"c48b5ac9-f815-11ea-9387-4b66d296b3bd"
],
"resourceName": null,
"failedResource": null
}
Unsuccessful response
Scenario: Non-existing or out-of-the-box event class deletion failed
"responseTimeStamp": 1600258192867,
"statusCode": "EVCLASS_NOT_EXIST",
"statusMsg": "[Operation failed, given entry doesn't exist in database or is a default entry]",
"resourceId": null,
"resourceName": null,
"failedResource": null
}
Scenario: Deleting class with an open event
"statusCode": "409",
"statusMsg": "[There are 6 open events for class - testclass. Please close these events and retry deleting the class.]",
"resourceId": null,
"resourceName": null,
"failedResource": null
}
GET /events/classes
Get details of all event classes and their tenant details
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Successful response
"responseTimeStamp": 1600259415190,
"statusCode": "200",
"statusMsg": "[Event Classes found successfully for specified Tenant:690188083]",
"classList": [
"PATROL_EV",
"ALARM",
"INCIDENT_INFO",
"EVENT",
"HELIX_SM_EV",
"ANOMALY"
],
"eventClassList": [
{...
... },
{
"name": "an_mean",
"dataType": "STRING",
"default": "",
"allFacet": [],
"enumElements": [],
"enum": false
}
]
}
]
}
See the text file with a dump of event classes.
GET /events/classes
Get details of a single event class
Parameter details (in the request URL)
Successful response
"responseTimeStamp": 1567057922470,
"statusCode": "200",
"statusMsg": "[Event Class found successfully for specified ID or Name.]",
"eventClass": {
"id": "91063dd6-ca15-11e9-901e-df18c2b43854",
"name": "EVENT",
"parentClassName": "",
"childClassNames": [
"PATROL_EV",
"ALARM"
],
"allAttributes": [...
... },
{
"name": "_relation_source",
"dataType": "STRING",
"default": "",
"allFacet": [
{
"name": "read_only",
"value": "true"
}
],
"enumElements": [],
"enum": false
}
]
}
}
See the text file with details of the EVENT base event class.
Unsuccessful response
Scenario: Invalid ID
"statusCode": "EVCLASS_NOT_EXIST",
"statusMsg": "[Operation failed, given entry doesn't exist in database or is a default entry]",
"resourceId": null,
"resourceName": null,
"failedResource": null
}
Managing event data
You can use the event ingestion API to send events from third-party applications to BMC Helix Operations Management with custom class and custom slot details.
Important
For the event slots that have the string or list of string data types, the character limit of the slot value is 32766. If the value goes above this limit, the value is trimmed, which results in data loss.
Mandatory slots
The following slots are mandatory for the Event-base-event-class.
- msg
- source_identifier
For custom classes, you can define additional mandatory slots.
POST /events
Send third-party events to BMC Helix Operations Management
To be able to run this API, you need the API key. To generate the API key, do the following:
- Log in to the BMC Helix Operations Management console and navigate to Administration > Repository.
- Click Copy API Key. The API key is copied to the clipboard in the following format:
tenantid::access key::secret keyFor example: 1938340892::G5MBF27TMFL9ITLH25RLR20UM0WBFZ::OK3StB006fIGbXH2pNDgFXiKmtzsE0PLScZUfFtQKemgqWGFXA - Paste the API key in a text file and use it to run this API.
Important
- For event slots that have the List of string data type, "" is considered as an empty list.
For example, Tags="" is considered as an empty list. - Events are not ingested in the following situations:
- The _identifier slot value contains invalid characters.
- The value for the msg or source_identifier slots is not available.
If you specify a slot multiple times with different values, only the latest value is used to ingest an event.
For example, if you specify the severity slot values in the following order, the endpoint ingests the event with the severity as MINOR.
[
{
"class": "EVENT",
"severity": "CRITICAL",
"severity": "MINOR"
}
]
Authorization: Bearer <JWT_token> OR apiKey <tentant_API_key>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Request body (for single event)
{
"class": "<event>",
"severity": "<severity>",
"msg": "<msg>",
"source_identifier": "source_id",
"status": "<status>",
"category": "<object_category>",
"priority": "<priority>",
"details": "<detailed_msg>",
"source_attributes":{
"source_hostname": "hostname",
"source_port": "<port>",
"source_address": "<ip_address>"
},
"class_slots": {
"<custom_slot1>": "<slotValue1>",
"<custom_slot2>": "<slotValue2>"
}
}
]
Example request body
Scenario: Single event
{
"class": "EVENT",
"severity": "MAJOR",
"msg": "Event summary text goes here (msg)",
"source_identifier": "clm-HostA:3181",
"status": "OPEN",
"category": "APPLICATION",
"priority": "PRIORITY_3",
"details": "Detail information about the event situation",
"source_attributes": {
"source_hostname": "clm-HostA",
"source_port": "3181",
"source_address": "ip_address"
},
"class_slots": {
"pn_severity": "MAJOR",
"pn_id": "abcd1111"
}
}
]
Scenario: An event is sent without the class slot
In this case, the event is ingested and the default class is EVENT.
{
"severity": "MINOR",
"msg": "jjJYThjjh",
"status" : "OPEN",
"source_identifier": "host_name:3181",
"source_attributes" : {
"source_hostname": "host_name",
"source_port": "3181",
"source_address" : "ip_address"
},
"class_slots" : {
"p_parameter": "CPU usage",
"p_parameter_value": "52",
"p_parameter_unit": "%",
"p_publish_hostname": "clm-HostA",
"p_agent_port": "3181",
"p_instance": "cpu_0",
"p_application": "NT",
"p_agent_version": "V12.0.00i",
"p_catalog": "FINNOVA1-JCS1.PRD_1234.b_zv5678",
"p_class": "0",
"p_node": "node_name"
}
}
]
Scenario: An event is sent with the class slot value as empty
In this case, the event is ingested and the default class is EVENT.
{
"class": "",
"severity": "CRITICAL",
"msg": "Total Busy Disk Time >= 40 for 3 min.",
"status" : "OPEN",
"source_identifier": "12ff23f8-7c82-481b-becc5-dbb04a985bf3",
"source_attributes" : {
"source_hostname": "clm-HostA",
"source_port": "3181",
"source_address" : "ip_address"
},
"class_slots" : {
"al_alarm_id": "12ff23f8-7c82-481b-bcc5-dbb04a9r85bf3",
"al_parameter_name": "LDldDiskTimePercent",
"al_parameter_value": "45.0",
"al_parameter_unit": "",
"al_baseline_type": "HOURLY",
"al_end_time": 4294967295,
"al_thresh_duration": 180,
"al_thresh_id": "166a3f14-89c7-4692-ae0e-8cd175f323a1b:NT_LOGICAL_DISKS:Logical Disks:LDldDiskTimePercent:Critical",
"al_thresh_type": "INSTABSTHRESHOLDS",
"al_old_severity": "MINOR"
}
}
]
Scenario: An event is sent with the class name in the upper case
In this case, the event is ingested because the class name case matches with known class names, such as PATROL_EV or EVENT.
{
"CLASS": "EVENT",
"severity": "MAJOR",
"msg": "Event summary text goes here (msg)",
"source_identifier": "host_name:3181",
"status" : "OPEN",
"source_attributes" : {
"source_hostname": "clm-HostA",
"source_port": "3181",
"source_address" : "ip_address"
},
"creation_time": "1509356071",
"category": "APPLICATION",
"priority": "PRIORITY_3",
"details": "Detail information about the event situation"
}
]
Scenario: An event is sent without the event class, severity, category, and priority slots
In this case, the defaults are set as follows:
- Class: EVENT
- Severity: MINOR
- Category: OPERATIONS_MANAGEMENT
- Priority: PRIORITY_5
{
"msg": "Total Busy Disk Time >= 40 for 4 min.",
"status" : "OPEN",
"source_identifier": "2212ff23f8-7c82-481b-becc45-dbb04a985bf3",
"source_attributes" : {
"source_hostname": "clm-HostA",
"source_port": "3181",
"source_address" : "<ip_address>"
},
"class_slots" : {
"al_alarm_id": "2212ff23ft8-7c82-481b-bcc5-dbb04a9r85bf3",
"al_parameter_name": "LDldDiskTimePercent",
"al_parameter_value": "45.0",
"al_parameter_unit": "",
"al_baseline_type": "HOURLY",
"al_end_time": 42944967295,
"al_thresh_duration": 180,
"al_thresh_id": "12266a3f14-89c7-4692-ae0e-8cd175f323a1b:NT_LOGICAL_DISKS:Logical Disks:LDldDiskTimePercent:Critical",
"al_thresh_type": "INSTABSTHRESHOLDS",
"al_old_severity": "MINOR"
}
}
]
Scenario: An event is sent with incorrect values in a mandatory slot
In this case, the severity slot is sent to _unmapped_data and the default severity is set to MINOR.
{
"class": "PATROL_EV",
"severity": 8175192739,
"msg": "sample msg",
"object": "cpu_0",
"status" : "OPEN",
"source_identifier": "clm-HostA:3181",
"source_attributes" : {
"source_hostname": "clm-HostA",
"source_port": "3181",
"source_address" : "<ip_address>"
},
"class_slots" : {
"p_parameter": "CPU usage",
"p_parameter_value": "52",
"p_parameter_unit": "%",
"p_publish_hostname": "clm-HostA",
"p_agent_port": "3181",
"p_instance": "cpu_0",
"p_application": "NT",
"p_agent_version": "V12.0.00i",
"p_catalog": "FINNOVA1-JCS1.PRD_1234.b_zv5678",
"p_class": "0",
"p_node": "node_name"
}
}
]
Scenario: An event is sent with a custom enumeration as a slot
Here device_status is the custom enumeration.
Important
While creating an event for event classes, if you do not specify the custom enumeration details in the request body, then the default value for the enumeration is set automatically.
{
"class": "NAGIOS_EVENT",
"severity": "MINOR",
"tag": "jWrAEu.hostA.bmc.com@3181.1635507541109.9333317384",
"object": "hostA.bmc.com",
"msg": "CustomEnumTest",
"category": "CAPACITY_MANAGEMENT",
"details": "device state",
"source_attributes": {
"source_hostname": "hostA",
"source_port": 3181,
"source_address": "<source_address>"
},
"source_identifier": "jWrAEu.hostA.bmc.com@3181.1635507541109.9333317384",
"event_id": false,
"location": "Houston",
"device_status": "UP"
}
]
Request body (for multiple events)
{
"class": "<event_class>",
"severity": "<severity>",
"msg": "<msg>",
"source_identifier": "source_id",
"status": "<status>",
"category": "<object_category>",
"priority": "<priority>",
"details": "<detailed_msg>",
"source_attributes": {
"source_hostname": "hostname",
"source_port": "<port>",
"source_address": "<ip_address>"
},
"class_slots": {
"<custom_slot1>": "<slotValue1>",
"<custom_slot2>": "<slotValue2>"
}
},
{
"class": "<event_class>",
"severity": "<severity>",
"msg": "<msg>",
"source_identifier": "source_id",
"status": "<status>",
"category": "<object_category>",
"priority": "<priority>",
"details": "<detailed_msg>",
"source_attributes": {
"source_hostname": "hostname",
"source_port": "<port>",
"source_address": "<ip_address>"
},
"class_slots": {
"<custom_slot1>": "<slotValue1>",
"<custom_slot2>": "<slotValue2>"
}
}
]
Example request body (for multiple events)
{
"class": "CLASS1",
"severity": "MAJOR",
"msg": "First event summary text goes here (msg)",
"source_identifier": "clm-HostA:3181",
"status": "OPEN",
"category": "APPLICATION",
"priority": "PRIORITY_3",
"details": "Detail information about the event situation",
"source_attributes": {
"source_hostname": "clm-HostA",
"source_port": "3181",
"source_address": "123.23.24.56"
},
"class_slots": {
"pn_severity": "MAJOR",
"pn_id": "1111"
}
},
{
"class": "CLASS2",
"severity": "CRITICAL",
"msg": "Second event summary text goes here (msg)",
"source_identifier": "clm-HostA:3181",
"status": "OPEN",
"category": "APPLICATION",
"priority": "PRIORITY_2",
"details": "Detail information about the event situation",
"source_attributes": {
"source_hostname": "clm-HostA",
"source_port": "3181",
"source_address": "123.23.24.56"
},
"class_slots": {
"pn_severity": "CRITICAL",
"pn_id": "22222"
}
}
]
Parameter details
Successful response
Status code 200 OK
"responseTimeStamp": 1600259952253,
"statusCode": "200",
"statusMsg": "OK",
"resourceId": [
"eps.690188083.4831460694718336.c99a2ffe-c6c9-4871-bfb0-af2639507577"
]
}
In this response, eps.690188083.4831460694718336.c99a2ffe-c6c9-4871-bfb0-af2639507577 is the event ID.
Unsuccessful response
Scenario: An event is sent without a mandatory slot
{
"key": "validation.schema.required",
"level": "ERROR",
"message": "[Path '/0'] Object has missing required properties ([\"msg\",\"source_identifier\"])",
"additionalInfo": []
}
]
Scenario: An event is sent with the class name in the lower case
In this case, the event response is OK. However, the event gets dropped because the class name does not match known class names. For example, the known class name PATROL_EV is in the upper case. If an event arrives with the class name patrol_ev in the lower case, it gets dropped.
{
"class": "alarm",
"severity": "CRITICAL",
"object": "22166a3f14-89c7-4692-ae0e-8cd175f243a1b:NT_LOGICAL_DISKS:Logical Disks",
"object_class": "NT_LOGICAL_DISKS",
"msg": "Total Busy Disk Time >= 40 for 4 min.",
"status": "OPEN",
"source_identifier": "2212ff23f8-7c82-481b-becc45-dbb04a985bf3",
"source_attributes": {
"source_hostname": "clm-pun-spygbh",
"source_port": "3181",
"source_address": "22887.23.24.56"
},
"class_slots": {
"al_alarm_id": "2212ff23ft8-7c82-481b-bcc5-dbb04a9r85bf3",
"al_parameter_name": "LDldDiskTimePercent",
"al_parameter_value": "45.0",
"al_parameter_unit": "",
"al_baseline_type": "HOURLY",
"al_end_time": 42944967295,
"al_thresh_duration": 180,
"al_thresh_id": "12266a3f14-89c7-4692-ae0e-8cd175f323a1b:NT_LOGICAL_DISKS:Logical Disks:LDldDiskTimePercent:Critical",
"al_thresh_type": "INSTABSTHRESHOLDS",
"al_old_severity": "MINOR"
}
}
]
PATCH /events
Update an event
You can update an event by providing slot names and values in the payload.
Note
- Internal and read-only slots are not updated in the payload.
If you specify a slot multiple times with different values, only the latest value is updated in the event.
For example, if you specify the severity slot values in the following order, the endpoint updates the event severity to MINOR, assuming that the original event severity is MAJOR,
{
"severity": "CRITICAL",
"severity": "MINOR"
}
To be able to run this API, you need the API key. To generate the API key, do the following:
- Log in to the BMC Helix Operations Management console and navigate to Administration > Repository.
- Click Copy API Key. The API key is copied to the clipboard in the following format:
tenantid::access key::secret keyFor example: 1938340892::G5MBF27TMFL9ITLH25RLR20UM0WBFZ::OK3StB006fIGbXH2pNDgFXiKmtzsE0PLScZUfFtQKemgqWGFXA - Paste the API key in a text file and use it to run this API.
Authorization: Bearer <JWT_token> OR apiKey <tentant_API_key>
For instructions about obtaining the API JWT token, see Access and authentication for the REST API..
Example request payload
"status": "ACK",
"msg": "updated event",
"severity": "CRITICAL"
}
This request updates existing events with the status, msg, or severity slots.
Successful response (Status code 200 OK)
"responseTimeStamp": 1600260444163,
"statusCode": "200",
"statusMsg": "OK",
"successfullEventIds": [
"eps.690188083.4831895306669881.c4478cfe-6319-40e2-bb4e-723515dfec2c"
]
}
Unsuccessful response
Scenario: Update a closed event
"responseTimeStamp": 1600260577333,
"statusCode": "400",
"statusMsg": "Provided event is closed.",
"failedEventIDs": [
"eps.690188083.4831895306669881.c4478cfe-6319-40e2-bb4e-723515dfec2c"
]
}
Scenario: Update an event with a read-only or an internal slot
"responseTimeStamp": 1600261101813,
"statusCode": "400",
"statusMsg": "Slot names: - [_repeat_count, class]Slots are not valid as they are read_only or internal or data type validation failed for provided class",
"failedEventIDs": [
"eps.690188083.4832293142128186.ea949c5f-7d05-4961-906e-1edb73345e05"
]
}
POST /msearch
Search for events
You can use this API for event search and aggregation.
The Elastic Search API DSL query language is used search events. For more information about the query language, see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html.
Important
We recommend that you specify a space after the slot value for custom slots of the String type to avoid intermittent parsing issues.
Raw document query
Search events for a specific date range in the raw document format.
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Important
Make sure that you format the request body in a single line before you send the request payload.
Example request body
Example: Search events for a specific date range in the raw document format
"size": 500,
"query": {
"bool": {
"filter": [
{
"range": {
"creation_time": {
"gte": 1603860684000,
"lte": 1603864284000,
"format": "epoch_millis"
}
}
},
{
"query_string": {
"analyze_wildcard": true,
"query": "status:OPEN"
}
}
]
}
},
"sort": {
"creation_time": {
"order": "desc",
"unmapped_type": "boolean"
}
},
"script_fields": {}
}
Example: Search open events that have the severity as critical or major in the raw document format
"size": 500,
"query": {
"bool": {
"filter": [
{
"query_string": {
"analyze_wildcard": true,
"query": "(severity:CRITICAL OR severity:MAJOR) AND (status:OPEN)"
}
}
]
}
},
"sort": {
"creation_time": {
"order": "desc",
"unmapped_type": "boolean"
}
},
"script_fields": {}
}
Successful response
Status code 200 OK
"took": 19,
"status": 200,
"responses": [
{
"took": 18,
"timed_out": false,
"_shards": {
"total": 10,
"successful": 10,
"skipped": 7,
"failed": 0
},
"hits": {
"total": {
"value": 80,
"relation": "eq"
},
"max_score": null,
"hits": [
{
"_score": null,
"_source": {
"msg": "9cd6e9f9c33fc4a",
"creation_time": 1603862648418,
"_tenant_id": "1846876061",
"severity_ordinal": 60,
"sub_category": "OTHER",
"modelname": "",
"source_identifier": "9cd6e9f9c33fc4a.clm-pun-t8x5kf.bmc.com@3181.1603862648418.9726262116",
"_tenant_name": "",
"_errors": "[]",
"incident_id": "",
"_operations": "[]",
"incident_company": "",
"_ci_id": "",
"source_port": 3181,
"source_address": "10.10.10.10",
"alias": [
"BMC_ComputerSystem:clm-pun-t8x5kf.bmc.com"...
...
"status": "OPEN",
"al_extremeness": 0,
"al_parameter_threshold": "",
"al_baseline_hourly_low": "",
"al_thresh_above_ordinal": 20,
"al_thresh_above": null,
"al_pts_exceeded": 0,
"incident_item": "",
"al_event_score": 0.0,
"object": "clm-pun-t8x5kf.bmc.com",
"al_end_time": 1603862534075,
"al_predict_to_occur_time": 1603862534075,
"al_agent_port": "",
"al_thresh_id": "4449542027",
"incident_operational_category1": "",
"cross_launch_uri": "",
"al_avg_value": "",
"incident_operational_category2": "",
"object_class": "",
"al_is_predicted_ordinal": 10,
"al_is_predicted": null,
"al_agent_name": "",
"al_parameter_name": "zPTZ9GkwwB",
"incident_operational_category3": "",
"al_baseline_weekly_low": "",
"al_thresh_duration": 1,
"al_agent_os": "",
"al_baseline_daily_high": "",
"al_baseline_weekly_high": "",
"al_prediction_severity": "CRITICAL",
"incident_type": "",
"al_parameter_unit": "MB",
"al_last_time": "0",
"al_alarm_id": "4718821724",
"al_baseline_hourly_high": "",
"al_thresh_type": "Custom",
"object_id": "",
"al_pts_total": 0,
"al_highest_severity_ordinal": 40,
"al_highest_severity": "WARNING",
"al_old_severity_ordinal": 40,
"al_old_severity": "WARNING",
"al_parameter_value": "79",
"al_baseline_daily_low": "",
"incident_category": "",
"al_device_ipaddress": "",
"al_baseline_type_ordinal": 10,
"al_baseline_type": "HOURLY"
},
"sort": [
1603862534075
]
}
]
},
"status": 200
}
]
}
In this response, the event search query is: status:OPEN
All events with the status OPEN event are searched and the response is in the raw document format.
Aggregation query
Perform event search and aggregation on a specific time range.
"size": 0,
"query": {
"bool": {
"filter": [
{
"range": {
"creation_time": {
"gte": 1603860684000,
"lte": 1603864284000,
"format": "epoch_millis"
}
}
},
{
"query_string": {
"analyze_wildcard": true,
"query": "status:OPEN"
}
}
]
}
},
"aggs": {
"2": {
"date_histogram": {
"interval": "15m",
"field": "creation_time",
"min_doc_count": 0,
"extended_bounds": {
"min": 1603860684000,
"max": 1603864284000
},
"format": "epoch_millis"
},
"aggs": {}
}
}
}
Successful response
Status code 200 OK
"took": 5,
"status": 200,
"responses": [
{
"took": 4,
"timed_out": false,
"_shards": {
"total": 10,
"successful": 10,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 80,
"relation": "eq"
},
"max_score": null,
"hits": []
},
"aggregations": {
"date_histogram#2": {
"buckets": [
{
"key_as_string": "1603860300000",
"key": 1603860300000,
"doc_count": 0
},
{
"key_as_string": "1603861200000",
"key": 1603861200000,
"doc_count": 0
},
{
"key_as_string": "1603862100000",
"key": 1603862100000,
"doc_count": 80
},
{
"key_as_string": "1603863000000",
"key": 1603863000000,
"doc_count": 0
},
{
"key_as_string": "1603863900000",
"key": 1603863900000,
"doc_count": 0
}
]
}
},
"status": 200
}
]
}
In this response, the event search query is: status:OPEN
All events with the status OPEN event are searched and the response is in the aggregate format.
Group By query
Perform event search and aggregation on a specific time range.
"size": 0,
"query": {
"bool": {
"filter": [
{
"range": {
"creation_time": {
"gte": 1603860684000,
"lte": 1603864284000,
"format": "epoch_millis"
}
}
},
{
"query_string": {
"analyze_wildcard": true,
"query": "*"
}
}
]
}
},
"aggs": {
"3": {
"terms": {
"field": "severity",
"size": 10,
"order": {
"_key": "desc"
},
"min_doc_count": 1
},
"aggs": {
"2": {
"date_histogram": {
"interval": "5m",
"field": "creation_time",
"min_doc_count": 0,
"extended_bounds": {
"min": 1603860684000,
"max": 1603864284000
},
"format": "epoch_millis"
},
"aggs": {}
}
}
}
}
}
Successful response
Status code 200 OK
"took": 9,
"status": 200,
"responses": [
{
"took": 8,
"timed_out": false,
"_shards": {
"total": 10,
"successful": 10,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 190,
"relation": "eq"
},
"max_score": null,
"hits": []
},
"aggregations": {
"sterms#3": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "WARNING",
"doc_count": 65,
"date_histogram#2": {
"buckets": [
{
"key_as_string": "1603860600000",
"key": 1603860600000,
"doc_count": 0
},
{
"key_as_string": "1603860900000",
"key": 1603860900000,
"doc_count": 0
},
{
"key_as_string": "1603861200000",
"key": 1603861200000,
"doc_count": 0
},
{
"key_as_string": "1603861500000",
"key": 1603861500000,
"doc_count": 0
},
{
"key_as_string": "1603861800000",
"key": 1603861800000,
"doc_count": 0
},
{
"key_as_string": "1603862100000",
"key": 1603862100000,
"doc_count": 0
},
{
"key_as_string": "1603862400000",
"key": 1603862400000,
"doc_count": 16
},
{
"key_as_string": "1603862700000",
"key": 1603862700000,
"doc_count": 49
},
{
"key_as_string": "1603863000000",
"key": 1603863000000,
"doc_count": 0
},
{
"key_as_string": "1603863300000",
"key": 1603863300000,
"doc_count": 0
},
{
"key_as_string": "1603863600000",
"key": 1603863600000,
"doc_count": 0
},
{
"key_as_string": "1603863900000",
"key": 1603863900000,
"doc_count": 0
},
{
"key_as_string": "1603864200000",
"key": 1603864200000,
"doc_count": 0
}
]
}
},
{
"key": "MINOR",
"doc_count": 25,
"date_histogram#2": {
"buckets": [
{
"key_as_string": "1603860600000",
"key": 1603860600000,
"doc_count": 0
},
{
"key_as_string": "1603860900000",
"key": 1603860900000,
"doc_count": 0
},
{
"key_as_string": "1603861200000",
"key": 1603861200000,
"doc_count": 0
},
{
"key_as_string": "1603861500000",
"key": 1603861500000,
"doc_count": 0
},
{
"key_as_string": "1603861800000",
"key": 1603861800000,
"doc_count": 0
},
{
"key_as_string": "1603862100000",
"key": 1603862100000,
"doc_count": 0
},
{
"key_as_string": "1603862400000",
"key": 1603862400000,
"doc_count": 25
},
{
"key_as_string": "1603862700000",
"key": 1603862700000,
"doc_count": 0
},
{
"key_as_string": "1603863000000",
"key": 1603863000000,
"doc_count": 0
},
{
"key_as_string": "1603863300000",
"key": 1603863300000,
"doc_count": 0
},
{
"key_as_string": "1603863600000",
"key": 1603863600000,
"doc_count": 0
},
{
"key_as_string": "1603863900000",
"key": 1603863900000,
"doc_count": 0
},
{
"key_as_string": "1603864200000",
"key": 1603864200000,
"doc_count": 0
}
]
}
},
{
"key": "MAJOR",
"doc_count": 65,
"date_histogram#2": {
"buckets": [
{
"key_as_string": "1603860600000",
"key": 1603860600000,
"doc_count": 0
},
{
"key_as_string": "1603860900000",
"key": 1603860900000,
"doc_count": 0
},
{
"key_as_string": "1603861200000",
"key": 1603861200000,
"doc_count": 0
},
{
"key_as_string": "1603861500000",
"key": 1603861500000,
"doc_count": 0
},
{
"key_as_string": "1603861800000",
"key": 1603861800000,
"doc_count": 0
},
{
"key_as_string": "1603862100000",
"key": 1603862100000,
"doc_count": 0
},
{
"key_as_string": "1603862400000",
"key": 1603862400000,
"doc_count": 65
},
{
"key_as_string": "1603862700000",
"key": 1603862700000,
"doc_count": 0
},
{
"key_as_string": "1603863000000",
"key": 1603863000000,
"doc_count": 0
},
{
"key_as_string": "1603863300000",
"key": 1603863300000,
"doc_count": 0
},
{
"key_as_string": "1603863600000",
"key": 1603863600000,
"doc_count": 0
},
{
"key_as_string": "1603863900000",
"key": 1603863900000,
"doc_count": 0
},
{
"key_as_string": "1603864200000",
"key": 1603864200000,
"doc_count": 0
}
]
}
},
{
"key": "CRITICAL",
"doc_count": 35,
"date_histogram#2": {
"buckets": [
{
"key_as_string": "1603860600000",
"key": 1603860600000,
"doc_count": 0
},
{
"key_as_string": "1603860900000",
"key": 1603860900000,
"doc_count": 0
},
{
"key_as_string": "1603861200000",
"key": 1603861200000,
"doc_count": 0
},
{
"key_as_string": "1603861500000",
"key": 1603861500000,
"doc_count": 0
},
{
"key_as_string": "1603861800000",
"key": 1603861800000,
"doc_count": 0
},
{
"key_as_string": "1603862100000",
"key": 1603862100000,
"doc_count": 0
},
{
"key_as_string": "1603862400000",
"key": 1603862400000,
"doc_count": 35
},
{
"key_as_string": "1603862700000",
"key": 1603862700000,
"doc_count": 0
},
{
"key_as_string": "1603863000000",
"key": 1603863000000,
"doc_count": 0
},
{
"key_as_string": "1603863300000",
"key": 1603863300000,
"doc_count": 0
},
{
"key_as_string": "1603863600000",
"key": 1603863600000,
"doc_count": 0
},
{
"key_as_string": "1603863900000",
"key": 1603863900000,
"doc_count": 0
},
{
"key_as_string": "1603864200000",
"key": 1603864200000,
"doc_count": 0
}
]
}
}
]
}
},
"status": 200
}
]
}
In this response, the event search query is * and the terms field is severity.
All events are searched and the response is in the group format with severity.
Terms query
Perform event search and aggregation on source_hostname.
"size": 0,
"query": {
"bool": {
"filter": [
{
"range": {
"creation_time": {
"gte": 1603860684000,
"lte": 1603864284000,
"format": "epoch_millis"
}
}
},
{
"query_string": {
"analyze_wildcard": true,
"query": "*"
}
}
]
}
},
"aggs": {
"2": {
"terms": {
"field": "source_hostname.keyword",
"size": 10,
"order": {
"_key": "desc"
},
"min_doc_count": 1
},
"aggs": {}
}
}
}
Successful response
Status code 200 OK
"took": 5,
"status": 200,
"responses": [
{
"took": 4,
"timed_out": false,
"_shards": {
"total": 10,
"successful": 10,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 190,
"relation": "eq"
},
"max_score": null,
"hits": []
},
"aggregations": {
"sterms#2": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "clm-pun-t8x5kf.bmc.com",
"doc_count": 175
},
{
"key": "clm-pun-52612",
"doc_count": 5
},
{
"key": "clm-pun-526",
"doc_count": 5
},
{
"key": "clm-pun-458",
"doc_count": 5
}
]
}
},
"status": 200
}
]
}
In this response, the event search query is * and the terms field is source_hostname.keyword.
All events are searched and the response is in the group format with source_hostname.keyword.
GET /mapping
Obtain the event classes schema mapping as per the ES structure
You can obtain the event classes schema mapping as per the Elastic Search structure.
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Successful response
Status code 200 OK
"event-0_r0": {
"mappings": {
"properties": {
"_arrival_time": {
"type": "date"
},
"_modified_time": {
"type": "date"
},
"al_agent_name": {
"type": "text",
"fields": {
"keyword": {
"ignore_above": 256,
"type": "keyword"
}
}
},
"al_agent_os": {
"type": "text",
"fields": {
"keyword": {
"ignore_above": 256,
"type": "keyword"
}
}...
...
"Temp10": {
"type": "text",
"fields": {
"keyword": {
"ignore_above": 256,
"type": "keyword"
}
}
},
"user_assigned": {
"type": "keyword",
"fields": {
"ignore_case": {
"type": "keyword",
"normalizer": "lc_norm"
}
}
}
}
}
}
}
In this response, eps.690188083.4831460694718336.c99a2ffe-c6c9-4871-bfb0-af2639507577 is the event ID.
Managing event operations
You can perform the following event operations by running APIs.
Tip
Get the event ID by viewing the event details or by exporting the events.
POST /events/service
Assign events
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Request body
"eventIds": [
"eventId1", "eventId2", "eventIdn"
],
"slots": {
"assigned_user": "user_name",
"notes": "add a note to the current operation"
}
}
Example request body
"eventIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
],
"slots": {
"assigned_user": "Mark",
"notes": "assign this event to Mark"
}
}
Successful response
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": true,
"passedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
Unsuccessful responses
Scenario : Mandatory event slot is missing
"responseTimeStamp": 1620823213851,
"statusCode": "400",
"statusMsg": "Missing mandatory event slot 'assigned_user' for operation : [AssignTo]",
"failedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
POST /events/service
Close events
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Request body
"eventIds": [
"eventId1", "eventId2", "eventIdn"
],
"slots": {
"notes": "add a note to the current operation"
}
}
Example request body
"eventIds": [
"eps.1311824585.14845808440222688.338b4c04-78b7-4289-85cc-4beec7056e1e"
],
"slots": {
"notes": "closing this event"
}
}
Successful response
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": true,
"passedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
Unsuccessful responses
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": false,
"failedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
POST /events/service
Set priority for events
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Request body
"eventIds": [
"eventId1", "eventId2", "eventIdn"
],
"slots": {
"priority": "PRIORITY_4",
"notes": "add a note to the current operation"
}
}
Example request body
"eventIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
],
"slots": {
"priority": "PRIORITY_4",
"notes": "change event priority"
}
}
Successful response
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": true,
"passedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
Unsuccessful responses
Scenario: Mandatory event slot is missing
"responseTimeStamp": 1620823213851,
"statusCode": "400",
"statusMsg": "Missing mandatory event slot 'priority' for operation : [SetPriority]",
"failedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
POST /events/service
Take ownership of events
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Request body
"eventIds": [
"eventId1", "eventId2", "eventIdn"
],
"slots": {
"notes": "add a note to the current operation"
}
}
Example request body
"eventIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
],
"slots": {
"notes": "Take Ownership"
}
}
Successful response
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": true,
"passedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
Unsuccessful responses
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": false,
"failedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
POST /events/service
Decline ownership of events
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Request body
"eventIds": [
"eventId1", "eventId2", "eventIdn"
],
"slots": {
"notes": "add a note to the current operation"
}
}
Example request body
"eventIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
],
"slots": {
"notes": "decline ownership"
}
}
Successful response
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": true,
"passedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
Unsuccessful responses
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": false,
"failedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
POST /events/service
Add a note to events
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Request body
"eventIds": [
"eventId1", "eventId2", "eventIdn"
],
"slots": {
"notes": "add a note to the current operation"
}
}
Example request body
"eventIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
],
"slots": {
"notes": "adding a respective note to events"
}
}
Successful response
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": true,
"passedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
Unsuccessful responses
Scenario: Mandatory event slot is missing
"responseTimeStamp": 1620823213851,
"statusCode": "400",
"statusMsg": "Missing mandatory event slot 'notes' for operation : [addNote]",
"failedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
POST /events/service
Acknowledge events
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Request body
"eventIds": [
"eventId1", "eventId2", "eventIdn"
],
"slots": {
"notes": "add a note to the current operation"
}
}
Example request body
"eventIds": [
"ff181c33-0567-47de-b0ae-ea6125f48d38"
],
"slots": {
"notes": "acknowledging the events"
}
}
Successful response
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": true,
"passedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
Unsuccessful responses
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": false,
"failedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
POST /events/service
Unacknowledge an event
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Request body
"eventIds": [
"eventId1", "eventId2", "eventIdn"
],
"slots": {
"notes": "add a note to the current operation"
}
}
Example request body
"eventIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
],
"slots": {
"notes": "unacknowledging the events"
}
}
Successful response
"responseTimeStamp": 1620793458647,
"statusCode": "200",
"statusMsg": "OK",
"response": true,
"passedIds": [
"eps.283198267.12868788805515522.edeb077e-cdc7-4908-9223-94f6c869882d"
]
}
Unsuccessful responses
Scenario: Missing object properties
{
"key": "validation.schema.required",
"level": "ERROR",
"message": "Object has missing required properties ([\"eventIds\"])",
"additionalInfo": []
}
]
POST /events/operations/incident
Create an incident for events
Authorization: Bearer <JWT_token>
For instructions about obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
Request body
"eventIds": [
"eventId1",
"eventId2",
"eventIdn"
]
}
Example request body
"eventIds": [
"eps.1220296999.32042773063967749.8953ee55-b393-4314-8964-4b851dabc7d6"
]
}
Successful response
"responseTimeStamp": 1641469008322,
"statusCode": "200",
"statusMsg": "OK",
"response": true,
"passedIds": [
"eps.1220296999.34995522708619637.5ba9b5af-1c74-42c7-91f6-9815a722fe28"
]
}
Unsuccessful responses
Scenario 1: Incident creation is not enabled for a tenant
{
"key": "500",
"level": "ERROR",
"message": "Manual Incident Creation feature is not enabled for tenant 1003829062",
"additionalInfo": null
}
]
Scenario 2: BMC Helix ITSM integration is not available
{
"key": "500",
"level": "ERROR",
"message": "Integration with ITSM is not available. Contact Administrator.",
"additionalInfo": null
}
]