This documentation supports an earlier version of BMC Helix Operations Management.

To view the documentation for the latest version, select 23.2 from the Product version picker.

Alarm policy management endpoints in the REST API


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 Open link

Run APIs to create, update, enable, disable, delete, and search for alarm policies.


Alarm policy management

Use REST APIs to create, update, enable, disable, and delete alarm policies.

POST alarm_policies

Request URL
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies
Example request URL with optional parameters
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies
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. Open link .

Parameter details


Parameter NameValue TypeMandatoryDescriptionLocated in

policyName

StringYes

The policy name.

Any unique value is a valid value.

Body
descriptionStringNo

The policy description.

Any value is a valid value.

Body
executionOrderIntegerYes

The policy precedence.

Values between 0-9999 are valid values.

Body
enabledBooleanNo

Indicates whether the policy is enabled or disabled.

The following values are valid:

  • true: Specifies that the policy is enabled.
  • false: Specifies that the policy disabled.

By default, the policy is disabled.

Body
entityTypeIdStringYesThe monitor type.Body
metricIdStringYesThe attribute name.Body
labelStringYesThe display name of an attribute.Body
unitStringYesThe unit of measurement.Body
pathStringYesThe full path of attributes.Body
orderIntegerYes

The order of the metric.

Valid values are 0 and above.

Body
comparisonStringYes

The comparison operator.

The following values are valid:

  • above
  • below
  • equal
Body
thresholdIntegerYes

The threshold value for the policy.

An integer is a valid value.

Body
durationIntegerYes

The duration in minutes.

A positive integer is a valid value.

Body
severityStringYes

The severity of the alarm.

The following values are valid:

  • CRITICAL
  • MAJOR
  • MINOR
Body
autoCloseBooleanYes

The auto-close for the alarm.

The following values are valid:

  • true
  • false
Body
configOrderIntegerYes

Metric value within the instance.

Valid values are 0-2.

Body
typeStringYes

The policy type.

The following types are valid:

  • All instances
  • Multi instances
Body
evaluationCriteriaStringYes

The selection criteria for the policy.

The following logical operators are valid:

  • AND
  • OR

The following conditions are valid:

  • agent_tag
  • agent_host_name
  • agent_os
  • agent_port
  • device_host_name
  • instance_name

The following condition operators are valid:

  • string-equals
  • string-not-equals
  • starts-with
  • ends-with
  • matches
  • not_equals
  • smaller_than
  • greater_than
  • greater_or_equals
  • smaller_or_equals
  • contains
  • not_contains
  • number-equals
  • less-than
  • greater-than-equal
  • less-than-equal
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
}


Back to top

PUT alarm_policies/<policy ID>

Request URL
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/<Policy Id>
Example request URL with optional parameters
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/0ab07dd5-277b-4d6a-9f8a-a578bb86ed8d
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. Open link .

Parameter details


Parameter NameValue TypeMandatoryDescriptionLocated in

policyName

StringYes

The policy name.

Any unique value is a valid value.

Body
descriptionStringNo

The policy description.

Any value is a valid value.

Body
executionOrderIntegerYes

The policy precedence.

Values between 0-9999 are valid values.

Body
enabledBooleanNo

Indicates whether the policy is enabled or disabled.

The following values are valid:

  • true: Specifies that the policy is enabled.
  • false: Specifies that the policy disabled.

By default, the policy is disabled.

Body
entityTypeIdStringYesThe monitor type.Body
metricIdStringYesThe attribute name.Body
labelStringYesThe display name of an attribute.Body
unitStringYesThe unit of measurement.Body
pathStringYesThe full path of attributes.Body
orderIntegerYes

The order of the metric.

Valid values are 0 and above.

Body
comparisonStringYes

The comparison operator.

The following values are valid:

  • above
  • below
  • equal
Body
thresholdIntegerYes

The threshold value for the policy.

An integer is a valid value.

Body
durationIntegerYes

The duration in minutes.

A positive integer is a valid value.

Body
severityStringYes

The severity of the alarm.

The following values are valid:

  • CRITICAL
  • MAJOR
  • MINOR
Body
autoCloseBooleanYes

The auto-close for the alarm.

The following values are valid:

  • true
  • false
Body
configOrderIntegerYes

Metric value within the instance.

Valid values are 0-2.

Body
typeStringYes

The policy type.

The following types are valid:

  • All instances
  • Multi instances
Body
evaluationCriteriaStringYes

The selection criteria for the policy.

The following logical operators are valid:

  • AND
  • OR

The following conditions are valid:

  • agent_tag
  • agent_host_name
  • agent_os
  • agent_port
  • device_host_name
  • instance_name

The following condition operators are valid:

  • string-equals
  • string-not-equals
  • starts-with
  • ends-with
  • matches
  • not_equals
  • smaller_than
  • greater_than
  • greater_or_equals
  • smaller_or_equals
  • contains
  • not_contains
  • number-equals
  • less-than
  • greater-than-equal
  • less-than-equal
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
}


Back to top

POST alarm_policies/<policy ID>/enable

Request URL
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/<Policy Id>/enable
Example request URL with optional parameters
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/0ab07dd5-277b-4d6a-9f8a-a578bb86ed8d/enable
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. Open link .

Parameter details


Parameter NameValue TypeMandatoryDescriptionLocated in

Policy Id

StringYes

The identifier to enable a policy.

Any unique value is a valid value.

Path
Successful response

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

Back to top

POST alarm_policies/<policy ID>/disable

Request URL
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/<Policy Id>/disable
Example request URL with optional parameters
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/0ab07dd5-277b-4d6a-9f8a-a578bb86ed8d/disable
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. Open link .

Parameter details


Parameter NameValue TypeMandatoryDescriptionLocated in

Policy Id

StringYes

The identifier to disable a policy.

Any unique value is a valid value.

Path
Successful response

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

Back to top

DELETE alarm_policies/<policy ID>

Request URL
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/<Policy Id>
Example request URL with optional parameters
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/0ab07dd5-277b-4d6a-9f8a-a578bb86ed8d
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. Open link .

Parameter details


Parameter NameValue TypeMandatoryDescriptionLocated in

Policy Id

StringYes

The identifier to delete a policy.

Any unique value is a valid value.

Path
Successful response

{
  "statusCode":"200",
   "customMsg":"[Deleted policies.]"
}


Unsuccessful responses

Scenario 1: Incorrect policy ID

{
    "statusCode": "500"
}

Scenario 1: Invalid policy ID

{
    "statusCode": "404"
}

Back to top


Alarm policy search

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>

Request URL
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/<Policy Id>
Example request URL with optional parameters
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/5b5cc184-055c-4e29-b0df-2098cf1235c5
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. Open link .

Parameter details


Parameter NameValue TypeMandatoryDescriptionLocated in
IDStringYes

The policy ID.

A unique string value is a valid value.

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

Back to top

POST alarm_policies/search

Request URL
https://<BMC Helix Portal URL>/alarm-service/api/v1.0/alarm_policies/search
Example request URL with optional parameters
https://test.bmc.com/alarm-service/api/v1.0/alarm_policies/search
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. Open link .

Parameter details


Parameter NameValue TypeMandatoryDescriptionLocated in
searchStringStringNo

The value that you specify for the search.

The policy name is a valid value.

Body
attributeStringNo

The criteria to sort policies.

Valid values:

  • name
  • modificationTime
  • enabled
Body
orderStringNo

The ascending or descending order to sort policies.

Valid values:

  • ASC
  • DSC
Body

Request body

{
   "searchString":"String",
   "sortCriteria":{
      "attribute":"String",
      "order":"String"
   }
}

Example request body

{
  "searchString": "PATROL Knowledge Module for Linux",
  "sortCriteria": {
    "attribute": "modifiedTime",
    "order": "DESC"
  }
}


Successful response

{
  "statusCode": "200",
  "totalRecords": 1,
  "policies": [
    {
      "tenantId": "1877651219",
      "id": "6d87d1b0-ba46-4a60-a35d-3c6cd84f1fd2",
      "policyName": "PATROL Knowledge Module for Linux",
      "description": "Global threshold configuration policy for Collection status(Disks), Collection status(File Systems), FileSystem Mount Status(File System), Process Count Check(Process), Process Ownership Check(Process), Parent PID is 1(Process).  ",
      "enabled": true,
      "owner": "admin",
      "createdTime": 1664271514462,
      "modifiedTime": 1694685867428,
      "executionOrder": 9999,
      "entityThresholds": [
        {
          "metricDetails": {
            "entityTypeId": "NUK_Disk_Container",
            "metricId": "_CollectionStatus",
            "unit": "1 - OK, 2 - Not OK",
            "label": "Collection status",
            "path": "nuk/22.4.11/NUK_Disk_Container/_CollectionStatus"
          },
          "type": "ALL",
          "evaluationCriteria": "",
          "alarmConfigurations": [
            {
              "configId": "5b81b51f-f18c-4861-9909-c72de3915319",
              "condition": {
                "comparison": "equal",
                "threshold": 2,
                "duration": 5,
                "occurrence": 0,
                "baseline": false
              },
              "action": {
                "severity": "CRITICAL",
                "autoClose": true,
                "closeDuration": -1
              },
              "configOrder": 0
            }
          ],
          "order": 0
        },
        {
          "metricDetails": {
            "entityTypeId": "NUK_FileSystem_Container",
            "metricId": "_CollectionStatus",
            "unit": "1 - OK, 2 - Not OK",
            "label": "Collection status",
            "path": "nuk/22.4.11/NUK_FileSystem_Container/_CollectionStatus"
          },
          "type": "ALL",
          "evaluationCriteria": "",
          "alarmConfigurations": [
            {
              "configId": "e5f025ff-610c-4cf7-b5ed-2072e2e1db52",
              "condition": {
                "comparison": "equal",
                "threshold": 2,
                "duration": 5,
                "occurrence": 0,
                "baseline": false
              },
              "action": {
                "severity": "CRITICAL",
                "autoClose": true,
                "closeDuration": -1
              },
              "configOrder": 0
            }
          ],
          "order": 1
        },
        {
          "metricDetails": {
            "entityTypeId": "NUK_FileSystem",
            "metricId": "MountStatus",
            "unit": "0 - OK, 1 - Unmounted, 2 - Unknown",
            "label": "Filesystem mount status",
            "path": "nuk/22.4.11/NUK_FileSystem/MountStatus"
          },
          "type": "ALL",
          "evaluationCriteria": "",
          "alarmConfigurations": [
            {
              "configId": "348ea3b6-1b02-4217-9d1d-82b9a8d7a8dc",
              "condition": {
                "comparison": "equal",
                "threshold": 1,
                "duration": 5,
                "occurrence": 0,
                "baseline": false
              },
              "action": {
                "severity": "CRITICAL",
                "autoClose": true,
                "closeDuration": -1
              },
              "configOrder": 0
            }
          ],
          "order": 2
        },
        {
          "metricDetails": {
            "entityTypeId": "NUK_Process",
            "metricId": "ProcessCountCheck",
            "unit": "0 - OK, 1 - Warning, 2 - Alarm",
            "label": "Process count check",
            "path": "nuk/22.4.11/NUK_Process/ProcessCountCheck"
          },
          "type": "ALL",
          "evaluationCriteria": "",
          "alarmConfigurations": [
            {
              "configId": "0579bbc3-736a-405a-8cd4-867fb610c4f5",
              "condition": {
                "comparison": "equal",
                "threshold": 2,
                "duration": 5,
                "occurrence": 0,
                "baseline": false
              },
              "action": {
                "severity": "CRITICAL",
                "autoClose": true,
                "closeDuration": -1
              },
              "configOrder": 0
            }
          ],
          "order": 3
        },
        {
          "metricDetails": {
            "entityTypeId": "NUK_Process",
            "metricId": "ProcessOwnerCheck",
            "unit": "0 - OK, 1 - Warning, 2 - Alarm",
            "label": "Process ownership check",
            "path": "nuk/22.4.11/NUK_Process/ProcessOwnerCheck"
          },
          "type": "ALL",
          "evaluationCriteria": "",
          "alarmConfigurations": [
            {
              "configId": "b390e582-5fa8-40d7-aed2-680440b2bf9b",
              "condition": {
                "comparison": "equal",
                "threshold": 2,
                "duration": 5,
                "occurrence": 0,
                "baseline": false
              },
              "action": {
                "severity": "CRITICAL",
                "autoClose": true,
                "closeDuration": -1
              },
              "configOrder": 0
            }
          ],
          "order": 4
        },
        {
          "metricDetails": {
            "entityTypeId": "NUK_Process",
            "metricId": "ProcessParentPID1",
            "unit": "0 - OK, 1 - Warning, 2 - Alarm",
            "label": "Parent PID is 1",
            "path": "nuk/22.4.11/NUK_Process/ProcessParentPID1"
          },
          "type": "ALL",
          "evaluationCriteria": "",
          "alarmConfigurations": [
            {
              "configId": "6ca0a52a-c9f7-4746-944e-53c10f2bbe09",
              "condition": {
                "comparison": "equal",
                "threshold": 2,
                "duration": 5,
                "occurrence": 0,
                "baseline": false
              },
              "action": {
                "severity": "CRITICAL",
                "autoClose": true,
                "closeDuration": -1
              },
              "configOrder": 0
            }
          ],
          "order": 5
        }
      ]
    }
  ]
}

Back to top

Was this page helpful? Yes No Submitting... Thank you

Comments