Managing alarm policies 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
Run APIs to create, update, enable, disable, delete, and search for alarm policies.
Managing alarm policies
Use REST APIs to create, update, enable, disable, and delete alarm policies.
POST alarm_policies
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies
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 | Located in |
---|---|---|---|---|
| String | Yes | The policy name. Any unique value is a valid value. | Body |
description | String | No | The policy description. Any value is a valid value. | Body |
executionOrder | Integer | Yes | The policy precedence. Values between 0-9999 are valid values. | Body |
enabled | Boolean | No | Indicates whether the policy is enabled or disabled. The following values are valid:
By default, the policy is disabled. | Body |
entityTypeId | String | Yes | The monitor type. | Body |
metricId | String | Yes | The attribute name. | Body |
label | String | Yes | The display name of an attribute. | Body |
unit | String | Yes | The unit of measurement. | Body |
path | String | Yes | The full path of attributes. | Body |
order | Integer | Yes | The order of the metric. Valid values are 0 and above. | Body |
comparison | String | Yes | The comparison operator. The following values are valid:
| Body |
threshold | Integer | Yes | The threshold value for the policy. An integer is a valid value. | Body |
duration | Integer | Yes | The duration in minutes. A positive integer is a valid value. | Body |
severity | String | Yes | The severity of the alarm. The following values are valid:
| Body |
autoClose | Boolean | Yes | The auto-close for the alarm. The following values are valid:
| Body |
configOrder | Integer | Yes | Metric value within the instance. Valid values are 0-2. | Body |
type | String | Yes | The policy type. The following types are valid:
| Body |
evaluationCriteria | String | Yes | The selection criteria for the policy. The following logical operators are valid:
The following conditions are valid:
The following condition operators are valid:
| Body |
Request body
{
"entityThresholds":[
{
"metricDetails":{
"entityTypeId":"String",
"metricId":"String",
"label":"String",
"unit":"String",
"path":"String"
},
"order":Integer,
"alarmConfigurations":[
{
"condition":{
"comparison":"String",
"threshold":"String",
"duration":Integer
},
"action":{
"severity":"String",
"autoClose":Boolean
},
"configOrder":Integer
}
],
"type":"String",
"evaluationCriteria":"String"
}
],
"enabled":Boolean,
"policyName":"String",
"description":"String",
"executionOrder":Integer
}
Example request body
{
"entityThresholds":[
{
"metricDetails":{
"entityTypeId":"IAK_WPAR",
"metricId":"UsedMemory",
"label":"Memory Used",
"unit":"MB",
"path":"iak/1.1.20/IAK_WPAR/UsedMemory"
},
"order":0,
"alarmConfigurations":[
{
"condition":{
"comparison":"above",
"threshold":18,
"duration":10
},
"action":{
"severity":"CRITICAL",
"autoClose":false
},
"configOrder":0
}
],
"type":"MULTI",
"evaluationCriteria":"( agent_host_name starts-with 'clm-pun-' ) AND ( agent_os contains 'Windows' ) "
}
],
"enabled":true,
"policyName":"Test_Alarm_2",
"description":"Creating Alarm Policy",
"executionOrder":9999
}
Successful response
{
"statusCode": "200",
"resourceId": [
"fbddd7eb-9e56-495e-bb27-36c0b540553c"
]
}
Unsuccessful responses
Scenario 1
Invalid condition name : agent_host_name_dummy.
There must be exactly one space character on each side of the following elements:
• Operator
• Parenthesis
Scenario 2
{
"statusCode": "POLICY_ALREADY_EXIST",
"resourceId": null
}
PUT alarm_policies/<policy ID>
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/<Policy Id>
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/0ab07dd5-277b-4d6a-9f8a-a578bb86ed8d
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 | Located in |
---|---|---|---|---|
| String | Yes | The policy name. Any unique value is a valid value. | Body |
description | String | No | The policy description. Any value is a valid value. | Body |
executionOrder | Integer | Yes | The policy precedence. Values between 0-9999 are valid values. | Body |
enabled | Boolean | No | Indicates whether the policy is enabled or disabled. The following values are valid:
By default, the policy is disabled. | Body |
entityTypeId | String | Yes | The monitor type. | Body |
metricId | String | Yes | The attribute name. | Body |
label | String | Yes | The display name of an attribute. | Body |
unit | String | Yes | The unit of measurement. | Body |
path | String | Yes | The full path of attributes. | Body |
order | Integer | Yes | The order of the metric. Valid values are 0 and above. | Body |
comparison | String | Yes | The comparison operator. The following values are valid:
| Body |
threshold | Integer | Yes | The threshold value for the policy. An integer is a valid value. | Body |
duration | Integer | Yes | The duration in minutes. A positive integer is a valid value. | Body |
severity | String | Yes | The severity of the alarm. The following values are valid:
| Body |
autoClose | Boolean | Yes | The auto-close for the alarm. The following values are valid:
| Body |
configOrder | Integer | Yes | Metric value within the instance. Valid values are 0-2. | Body |
type | String | Yes | The policy type. The following types are valid:
| Body |
evaluationCriteria | String | Yes | The selection criteria for the policy. The following logical operators are valid:
The following conditions are valid:
The following condition operators are valid:
| Body |
Request body
{
"entityThresholds":[
{
"metricDetails":{
"entityTypeId":"String",
"metricId":"String",
"label":"String",
"unit":"String",
"path":"String"
},
"order":Integer,
"alarmConfigurations":[
{
"condition":{
"comparison":"String",
"threshold":"String",
"duration":Integer
},
"action":{
"severity":"String",
"autoClose":Boolean
},
"configOrder":Integer
}
],
"type":"String",
"evaluationCriteria":"String"
}
],
"enabled":Boolean,
"policyName":"String",
"description":"String",
"executionOrder":Integer
}
Example request body
{
"id":"f835a4f5-116f-4282-b489-fcae7d46a913",
"policyName":"Test_Alarm_2",
"description":"Creating Alarm Policy",
"enabled":false,
"entityThresholds":[
{
"metricDetails":{
"entityTypeId":"IAK_WPAR",
"metricId":"UsedMemory",
"label":"Memory Used",
"unit":"MB",
"path":"iak/1.1.20/IAK_WPAR/UsedMemory"
},
"type":"MULTI",
"evaluationCriteria":"( agent_host_name starts-with 'clm-pun-' ) AND ( agent_os contains 'Windows' ) ",
"alarmConfigurations":[
{
"configId":"daf17a3b-0daa-4418-a8eb-efdb673cc4db",
"condition":{
"comparison":"above",
"threshold":18,
"duration":10,
"occurrence":0
},
"action":{
"severity":"CRITICAL",
"autoClose":false
},
"configOrder":0
}
],
"order":0
}
],
"executionOrder":9999
}
Successful response
{
"statusCode": "200",
"resourceId": [
"27391336-80e8-457c-ab6c-2ab0e27a2954"
]
}
Unsuccessful responses
Scenario 1: Policy does not exist
{
"statusCode": "POLICY_NOT_EXIST",
"resourceId": null
}
Scenario 2: Incorrect or invalid policy precedence
The Execution Order (policy precedence) parameter must be a positive number and must be between 0 and 9999.
Scenario 3: The EntityTypeID
parameter is empty
{
"statusCode": "500",
The EntityTypeId parameter cannot be empty or null.
}
Scenario 4: The EntityTypeID
parameter is invalid
{
"statusCode": "500",
Invalid EntityTypeId.
}
Scenario 1: Invalid instance type
{
"statusCode": "500",
Invalid type : nIK3HXRc
}
POST alarm_policies/<policy ID>/enable
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/<Policy Id>/enable
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/0ab07dd5-277b-4d6a-9f8a-a578bb86ed8d/enable
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 | Located in |
---|---|---|---|---|
| String | Yes | The identifier to enable a policy. Any unique value is a valid value. | Path |
{
"statusCode":"200"
}
Unsuccessful responses
Scenario 1: Invalid policy ID
{
"statusCode":"500"
Invalid UUID string: 263927105892830
}
Scenario 2: Incorrect policy ID format
{
"statusCode":"500"
Error at index 9 in: "d38ccf559re7"
}
POST alarm_policies/<policy ID>/disable
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/<Policy Id>/disable
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/0ab07dd5-277b-4d6a-9f8a-a578bb86ed8d/disable
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 | Located in |
---|---|---|---|---|
| String | Yes | The identifier to disable a policy. Any unique value is a valid value. | Path |
{
"statusCode":"200"
}
Unsuccessful responses
Scenario 1: Invalid policy ID
{
"statusCode":"500"
Invalid UUID string: 263927105892830
}
Scenario 2: Incorrect policy ID format
{
"statusCode":"500"
Error at index 9 in: "d38ccf559re7"
}
DELETE alarm_policies/<policy ID>
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/<Policy Id>
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/0ab07dd5-277b-4d6a-9f8a-a578bb86ed8d
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 | Located in |
---|---|---|---|---|
| String | Yes | The identifier to delete a policy. Any unique value is a valid value. | Path |
{
"statusCode":"200",
"customMsg":"[Deleted policies.]"
}
Unsuccessful responses
Scenario 1: Incorrect policy ID
{
"statusCode": "500"
}
Scenario 1: Invalid policy ID
{
"statusCode": "404"
}
Searching for alarm policies
You can search for alarm policies based on one of the following criterion:
- Policy ID
- Other criteria that you specify
Run the APIs in this section to search for alarm policies.
GET alarm_policies/<policy ID>
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/<Policy Id>
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/5b5cc184-055c-4e29-b0df-2098cf1235c5
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 | Located in |
---|---|---|---|---|
ID | String | Yes | The policy ID. A unique string value is a valid value. | Path |
{
"responseTimeStamp":1613549398716,
"statusCode":"200",
"statusMsg":"policy list success",
"totalRecords":1,
"policies":[
{
"tenantId":"1786266992",
"id":"a3328dc5-3c2a-420c-a3e4-8b895eca0b87",
"policyName":"Test_Alarm_1",
"description":"",
"enabled":false,
"owner":"admin",
"createdTime":1613542081767,
"modifiedTime":1613542081767,
"entityThresholds":[
{
"metricDetails":{
"entityTypeId":"IAK_WPAR",
"metricId":"CPUUtilization",
"unit":"%",
"label":"CPU Utilization",
"path":"iak/1.1.20/IAK_WPAR/CPUUtilization"
},
"type":"MULTI",
"evaluationCriteria":"agent_os contains 'AIX' ",
"alarmConfigurations":[
{
"configId":"06177e2f-0a9d-482b-8fe3-35eec9adeef2",
"condition":{
"comparison":"above",
"threshold":19.0,
"duration":10,
"occurrence":0
},
"action":{
"severity":"CRITICAL",
"autoClose":true,
"closeDuration":-1
},
"configOrder":0
}
],
"order":0
}
],
"executionOrder":9999
}
]
}
POST alarm_policies/search
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/search
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/search
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 | Located in |
---|---|---|---|---|
searchString | String | No | The value that you specify for the search. The policy name is a valid value. | Body |
attribute | String | No | The criteria to sort policies. Valid values:
| Body |
order | String | No | The ascending or descending order to sort policies. Valid values:
| Body |
Request body
{
"searchString":"String",
"sortCriteria":{
"attribute":"String",
"order":"String"
}
}
Example request body
{
"sortCriteria":{
"attribute":"modifiedTime",
"order":"DESC"
}
}
Successful response
{
"responseTimeStamp":1613549398716,
"statusCode":"200",
"statusMsg":"policy list success",
"totalRecords":1,
"policies":[
{
"tenantId":"1786266992",
"id":"a3328dc5-3c2a-420c-a3e4-8b895eca0b87",
"policyName":"Test_Alarm_1",
"description":"",
"enabled":false,
"owner":"admin",
"createdTime":1613542081767,
"modifiedTime":1613542081767,
"entityThresholds":[
{
"metricDetails":{
"entityTypeId":"IAK_WPAR",
"metricId":"CPUUtilization",
"unit":"%",
"label":"CPU Utilization",
"path":"iak/1.1.20/IAK_WPAR/CPUUtilization"
},
"type":"MULTI",
"evaluationCriteria":"agent_os contains 'AIX' ",
"alarmConfigurations":[
{
"configId":"06177e2f-0a9d-482b-8fe3-35eec9adeef2",
"condition":{
"comparison":"above",
"threshold":19.0,
"duration":10,
"occurrence":0
},
"action":{
"severity":"CRITICAL",
"autoClose":true,
"closeDuration":-1
},
"configOrder":0
}
],
"order":0
}
],
"executionOrder":9999
}
]
}
Comments
Log in or register to comment.