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.

POST /events/classes

Create an event class

Request URL

 https://<BMC Helix Portal URL>/events-service/api/v1.0/events/classes

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/classes

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details

Parameter Name Value Type Mandatory Description

name String Yes Name with which you want to create the event class.

parentClassName

String

No

Name of the parent class under which you want to create the class. This value must be EVENT class.

Default: EVENT

attributes

Object (List)

Yes

List of event slots that you want to create for the new event class.

The following parameters are supported:

nameName of the slot.
dataType
Data type you want to specify for the slot.
For more information, see the list of supported data types.
default(Optional) Default value that you want to specify for the slot.
enumIndicates whether the slot must have enumeration values. For enumeration data types, the value of this parameter is mandatory and you must set it as true. If you do not set the value, the value false is set automatically. For non-enumeration data types, the value is optional and you can set it as false.
For more information, see the list of out-of-the-box enumeration data types.
allFacet(Optional) Facets control aspects of a class instance’s processing and they control values that a slot can have. You can assign the following facet types:
- Mandatory
- Read-only
- Hidden
- Dup-detect
For more information, see the list of supported facets.

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

{
			"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"
				}
			]
		}

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

{    "responseTimeStamp": 1600425222656, 
     "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"
}

Back to top

PUT /events/classes

Update an event class

You can perform the following operations while updating an event class:

Add new slots to the existing event class.
Update the default value and facets.

Note

You cannot update the slot name, data type, and enum information.

Request URL

https://<BMC Helix Portal URL>/events-service/api/v1.0/events/classes/<event_class_identifier>

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/classes/91063dd6-ca15-11e9-901e-df18c2b43854

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details (in the request URL)

Parameter Name	Value Type	Mandatory	Description
`event_class_identifier`	String	Yes	Unique name of ID of the event class.

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)

Parameter Name	Value Type	Mandatory	Description
`attributes`	Object (List)	Yes	List of new attributes you want to add in the existing event class.

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
}

Back to top

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.

Request URL

 https://<BMC Helix Portal URL>/events-service/api/v1.0/events/classes/<event_class_identifier>

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/classes/91063dd6-ca15-11e9-901e-df18c2b43854

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details

Name Value Type Mandatory Description

idType

String

Yes

Type of identifier by which you want to perform the operation.

The value can be id or name based on the resources passed in the request body.

resources

List

Yes

Comma-separated list of event classes to be deleted.

The value can be a single event class name or ID or a list of event class names or IDs. This value must match the idType specified.

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

{    "responseTimeStamp": 1600425861254,
     "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
}

Back to top

GET /events/classes

Get details of all event classes and their tenant details

Request URL

https://<BMC Helix Portal URL>/events-service/api/v1.0/events/classes

Example URL

https://HostA.bmc.com/events-service/api/v1.0/events/classes

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on 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.

Back to top

GET /events/classes

Get details of a single event class

Request URL

 /events-service/api/v1.0/events/classes/<event_class_identifier/event_class_name>?idType=<id/name>

Example request URL: Get event class by ID

https://HostA.bmc.com/events-service/api/v1.0/events/classes/91063dd6-ca15-11e9-901e-df18c2b43854?idType=id

    Example request URL: Get event class by name, where the event class name is custom_class
    

https://HostA.bmc.com/events-service/api/v1.0/events/classes/custom_class?idType=name

    Example request URL: Get event class by name, where the event class name is EVENT
    

https://HostA.bmc.com/events-service/api/v1.0/events/classes/EVENT?idType=name

Parameter details (in the request URL)

Parameter Name Value Type Mandatory Description

event_class_identifier/event_class_name String Yes Unique name of ID of the event class.

idType=id/name

String

Yes

Type of identifier by which you want to perform the operation.

The value can be id or name based on the class_identifier value passed 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

{    "responseTimeStamp": 1600425963675, 
     "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
}

Back to top

Managing event data

You can use the event ingestion API to send events from third-party applications to Helix Monitor with custom class and custom slot details.

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.
Paste the API key in a text file and use it to run this API.

Request URL

https://<BMC Helix Portal URL>/events-service/api/v1.0/events

Example request URL

https://HostA.bmc.com/events-service/api/v1.0/events

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token> OR apiKey <tentant_API_key>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Request body (for single event)

[
{
  "class": "<event>",
  "severity": "<severity>",
  "object": "<host component>",
  "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",
  "object": "/usr/bin",
  "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",
"object":    "cpu_0",
"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 without the class slot value as empty

In this case, the event is ingested and the default class is EVENT.

[
{
"class": "",
"severity": "CRITICAL",
"object": "166a3f14-89c7-4692-ae0e-8cd175f23a1b:NT_LOGICAL_DISKS:Logical Disks",
"object_class" : "NT_LOGICAL_DISKS",
"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",
"object":    "/usr/bin",
"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

[
{
"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-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"
}
}
]

Request body (for multiple events)

[
  {
    "class": "<event_class>",
    "severity": "<severity>",
    "object": "<host_component>",
    "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>",
    "object": "<host component>",
    "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",
    "object": "/usr/bin",
    "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",
    "object": "/usr/bin",
    "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

Parameter Name	Value Type	Mandatory	Description
`class`	String	No	Custom class name with which you want to associate the event. Default value: EVENT
severity	Enum	No	Severity value of the event. Default value: WARNING Possible Values: CRITICAL, MAJOR, MINOR, WARNING, INFO, OK, UNKNOWN
object	String	Yes	Component of the host to which the event is related. For example, name of the disk on which the event is reporting the problem.
object_class	String	No	Identifies the class of an object. If the object class cannot be derived from the original event, it must be filled in during enrichment.
msg	String	Yes	Event summary (text description) in brief
status	String	No	Status value of the event. Default value: OPEN Possible Values: OPEN, ACK, ASSIGNED, CLOSED, BLACKOUT
source_identifier	String	Yes	Unique identifier of the event source identifier. The identifier can differ based on the type of event source. By default, for PATROL Agents, the event source is added in the format, agentHostName:Port. Furthermore, for alarms, the internally generated alarm ID is added.
source_attributes : { source_address source_hostname source_port }	Object (Map)	No	Additional source attribute slots for source identification.
creation_time	String	No	Epoch time (in milliseconds) when the event was received from the event source. The event source can be PATROL Agent or a third party event provider (event generated via the API).
category	String	No	High-level normalized category of the object that the event represents. This is based on appropriate Information and Technology Infrastructure Library (ITIL) core process. Possible Values: SLA_MANAGEMENT, CAPACITY_MANAGEMENT, SERVICE_CONTINUITY_MANAGEMENT, AVAILABILITY_MANAGEMENT, INCIDENT_MANAGEMENT, CONFIGURATION_MANAGEMENT, RELEASE_MANAGEMENT, PROBLEM_MANAGEMENT, CHANGE_MANAGEMENT
sub_category	String	No	Subcategory of the object the event represents based on the appropriate Information Technology Infrastructure Library (ITIL) core process. Possible values: `OTHER` `APPLICATION` `DATABASE` `NETWORK` `SYSTEM` `USER_TRANSACTIONS`
priority	Enum	No	Records the original priority of the event upon insertion. Also, records current priority of the event. Possible values: `PRIORITY_5 (lowest priority)` `PRIORITY_4` `PRIORITY_3` `PRIORITY_2` `PRIORITY_1 (highest priority)`
details	String	No	Detailed information about the event. Expands the information in the `msg`slot.
alias	String	No	Will be used for event association with the CI. You can provide a combination of slots to form the alias value, for example, BMC_ComputerSystem:source_host:source_por

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"
    }
  }
]

Back to top

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 be updated in the payload.

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.
Paste the API key in a text file and use it to run this API.

Request URL

https://<BMC Helix Portal URL>/events-service/api/v1.0/events/<event-id>

Example URL

https://HostA/events-service/api/v1.0/events/eps.544054987.5787269843597304.55ba9187-e171-4890-80af-25443afd0763

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token> OR apiKey <tentant_API_key>

For instructions on 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"
    ]
}

Back to top

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 .

Raw document query

Search events for a specific date range in the raw document format.

Request URL

https://<host_name>/events-service/api/v1.0/events/msearch

Example request URL

https://HostA.bmc.com/events-service/api/v1.0/events/msearch

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Request body

{"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":{}}

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.

Request URL

https://<host_name>/events-service/api/v1.0/events/msearch

Example request URL

https://HostA.bmc.com/events-service/api/v1.0/events/msearch

Request body

{"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.

Request URL

https://<host_name>/events-service/api/v1.0/events/msearch

Example request URL

https://HostA.bmc.com/events-service/api/v1.0/events/msearch

Request body

{"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.

Request URL

https://<host_name>/events-service/api/v1.0/events/msearch

Example request URL

https://HostA.bmc.com/events-service/api/v1.0/events/msearch

Request body

{"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.

Back to top

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.

Request URL

https://<host_name>/events-service/api/v1.0/events/mapping

Example request URL

https://HostA.bmc.com/events-service/api/v1.0/events/mapping

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Request body

None

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.

Back to top

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

Request URL

 https://<BMC Helix Portal URL>/events-service/api/v1.0/events/operations/assign

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/operations/assign

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details

Parameter Name	Value Type	Mandatory	Description
`eventIds`	String	Yes	Comma-separated list of event IDs to assign to a user.
`slots`	String	Yes	List of event slots to update while assigning the events: `assigned_user`Name of the user to whom you want to assign the events. Note: This API doesn't validate the user name to whom you assign the events. Ensure that you provide a valid username. (Optional) `notes`A note for the current operation.

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

Request URL

 https://<BMC Helix Portal URL>/events-service/api/v1.0/events/operations/close

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/operations/close

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details

Parameter Name	Value Type	Mandatory	Description
`eventIds`	String	Yes	Comma-separated list of event IDs with which you close the events.
`slots`	String	No	Includes the `notes` parameter that you can specify for closing the events.

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

Request URL

 https://<BMC Helix Portal URL>/events-service/api/v1.0/events/operations/setPriority

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/operations/setPriority

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details

Parameter Name Value Type Mandatory Description

eventIds

String

Yes

Comma-separated list of event IDs that you assign a priority level.

slots

String

Yes

List of event slots to update while setting priorities for the events.

priority
Assign a priority level for the events.
Possible values:
- PRIORITY_5 (lowest priority)
- PRIORITY_4
- PRIORITY_3
- PRIORITY_2
- PRIORITY_1 (highest priority)
(Optional) notesA note for the current operation.

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

Request URL

 https://<BMC Helix Portal URL>/events-service/api/v1.0/events/operations/takeOwnership

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/operations/takeOwnership

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details

Parameter Name	Value Type	Mandatory	Description
`eventIds`	String	Yes	Comma-separated list of event IDs for which you take ownership.
`slots`	String	No	Includes the `notes` parameter that you can specify for the current operation.

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

Request URL

 https://<BMC Helix Portal URL>/events-service/api/v1.0/events/operations/declineOwnership

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/operations/declineOwnership

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details

Parameter Name	Value Type	Mandatory	Description
`eventIds`	String	Yes	Comma-separated list of event IDs for which you decline ownership. This operation changes the event status to Acknowledged.
`slots`	String	No	Includes the `notes` parameter that you can specify for the current operation.

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

Request URL

 https://<BMC Helix Portal URL>/events-service/api/v1.0/events/operations/addNote

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/operations/addNote

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details

Parameter Name	Value Type	Mandatory	Description
`eventIds`	String	Yes	Comma-separated list of event IDs for which you add a note.
`slots`	String	Yes	Includes the `notes` parameter that you have to specify while adding a note to the events.

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

Request URL

 https://<BMC Helix Portal URL>/events-service/api/v1.0/events/operations/acknowledge

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/operations/acknowledge

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details

Parameter Name Value Type Mandatory Description

eventIds

String

Yes

Comma-separated list of event IDs that you acknowledge.

This operation changes the event status from Open to Acknowledged.

slots

String

No

Includes the notes parameter that you can specify while acknowledging the events.

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

Request URL

 https://<BMC Helix Portal URL>/events-service/api/v1.0/events/operations/unacknowledge

Example request URL

 https://HostA.bmc.com/events-service/api/v1.0/events/operations/unacknowledge

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Parameter details

Parameter Name	Value Type	Mandatory	Description
`eventIds`	String	Yes	Comma-separated list of event IDs of previously acknowledged events that you want to change to the Open state.
`slots`	String	No	Includes the `notes` parameter that you can specify for the current operation.

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": []
    }
]

Managing events with REST APIs

Managing event classes

POST /events/classes

PUT /events/classes

DELETE /events/classes

GET /events/classes

GET /events/classes

Managing event data

Mandatory slots

POST /events

PATCH /events

POST /msearch

Raw document query

Aggregation query

Group By query

Terms query

GET /mapping

Managing event operations

POST /events/service

POST /events/service

POST /events/service

POST /events/service

POST /events/service

POST /events/service

POST /events/service

POST /events/service

Comments