Configuring blackout 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

POST /events-service/api/v1.0/blackout_policies
 Create a blackout policy


Request URL
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_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.

Request Body
{
  "name": "string",
  "description": "string",
  "executionOrder": "integer",
  "eventSelectorCriteria": "string",
  "enabled": "Boolean",
  "configurations":
    {
        "definition": {
        "timeframeDetails": {
          "startDate": "Date",
          "startTime": "time",
          "endTime": "time",
          "endsOn": {
            "endDate": "Date"
          },
          "recurrencePattern": {
            "recurrence": "string"
          },
          "timeZone": {
            "id": "string",
            "offset": "time zone format"
          }
        },
        "processing_action": {
          "blackoutExistingEvents": "Boolean",
          "resetStatusOnBlackoutEnd": "Boolean"
        }
      }
    }
}


Example Request Body - Create a policy (time frame = one time)
{
  "name": "abcd",
  "description": "Blackout Policy 1",
  "executionOrder": 9999,
  "eventSelectorCriteria": "( class equals 'EVENT' ) AND _identifier within '123'",
  "enabled": false,
  "configurations":
    { 
        "definition": {
        "timeframeDetails": {
          "startDate": "14122020",
          "startTime": "17:27",
          "endTime": "17:27",
          "endsOn": {
            "endDate": "16122020"
          },
          "recurrencePattern": {
            "recurrence": "oneTime"
          },
          "timeZone": {
            "id": "Atlantic/Azores",
            "offset": "-01:00"
          }
        },
        "processing_action": {
          "blackoutExistingEvents": "true",
          "resetStatusOnBlackoutEnd": "false"
        }
      }
    }
}
Example Request Body - Create a policy (time frame = recurring, repeats = daily)
{
    "name": "testpolicy11",
    "description": "Blackout Policy 1",
    "executionOrder": 9999,
    "eventSelectorCriteria": "( class equals 'EVENT' ) AND _identifier within '123'",
    "enabled": false,
    "configurations": {        
        "definition": {
            "timeframeDetails": {
                "startDate": "03022021",
                "startTime": "10:35",
                "endTime": "11:36",
                "recurrencePattern": {
                    "recurrence": "daily",
                    "details": {
                        "days": "all"
                    }
                },
                "endsOn": {
                    "endDate": "04022021"
                },
                "timeZone": {
                    "id": "Atlantic/Azores",
                    "offset": "-01:00"
                }
            },
            "processing_action": {
                "blackoutExistingEvents": "true",
                "resetStatusOnBlackoutEnd": "false"
            }
        }       
    }
}
Example Request Body - Create a policy (time frame = recurring, repeats = weekly, days of the week = 3rd day of the week)
 {
    "name": "testpolicy12",
    "description": "Blackout Policy 1",
    "executionOrder": 9999,
    "eventSelectorCriteria": "( class equals 'EVENT' ) AND _identifier within '123'",
    "enabled": false,
    "configurations": 
        {                 
            "definition": {
                "timeframeDetails": {
                    "startDate": "03022021",
                    "startTime": "10:35",
                    "endTime": "11:36",
                    "endsOn": {
                        "occurrences": "5"
                    },
                    "recurrencePattern": {
                        "recurrence": "weekly",
                        "details": {
                            "daysOfWeek": [
                                3
                            ]
                        }
                    },
                    "timeZone": {
                        "id": "Atlantic/Azores",
                        "offset": "-01:00"
                    }
                },
                "processing_action": {
                    "blackoutExistingEvents": "true",
                    "resetStatusOnBlackoutEnd": "false"
                }
            }
        }
}
Example Request Body - Create a policy (time frame = recurring, repeats = weekly, days of the week = 3,4,7)
{
    "name": "testpolicy14",
    "description": "Blackout Policy 1",
    "executionOrder": 9999,
    "eventSelectorCriteria": "( class equals 'EVENT' ) AND _identifier within '123'",
    "enabled": false,
    "configurations": 
        {                      
            "definition": {
                "timeframeDetails": {
                    "startDate": "03022021",
                    "startTime": "10:35",
                    "endTime": "11:36",
                    "endsOn": {
                        "never": true
                    },
                    "recurrencePattern": {
                        "recurrence": "weekly",
                        "details": {
                            "daysOfWeek": [
                                3,
                                4,
                                7
                            ]
                        }
                    },
                    "timeZone": {
                        "id": "Atlantic/Azores",
                        "offset": "-01:00"
                    }
                },
                "processing_action": {
                    "blackoutExistingEvents": "true",
                    "resetStatusOnBlackoutEnd": "false"
                }
            }
        }
}
Example Request Body - Create a policy (time frame = recurring, repeats = monthly, dates = 1-15)
{
    "name": "testpolicy13",
    "description": "Blackout Policy 1",
    "executionOrder": 9999,
    "eventSelectorCriteria": "( class equals 'EVENT' ) AND _identifier within '123'",
    "enabled": false,
    "configurations": 
        {  
                 "definition": {
                "timeframeDetails": {
                    "startDate": "03022021",
                    "startTime": "10:35",
                    "endTime": "11:36",
                    "endsOn": {
                        "never": true
                    },
                    "recurrencePattern": {
                        "recurrence": "monthly",
                        "details": {
                            "dates": "1-15"
                        }
                    },
                    "timeZone": {
                        "id": "Atlantic/Azores",
                        "offset": "-01:00"
                    }
                },
                "processing_action": {
                    "blackoutExistingEvents": "true",
                    "resetStatusOnBlackoutEnd": "false"
                }
            }
        }
}
Example Request Body - Create a policy (time frame = recurring, repeats = daily, select No End Date and select Exclude Weekends)
{
    "name": "testpolicy15",
    "description": "Blackout Policy 1",
    "executionOrder": 9999,
    "eventSelectorCriteria": "( class equals 'EVENT' ) AND _identifier within '123'",
    "enabled": false,
    "configurations":
      {        
         "definition":{
            "timeframeDetails":{
               "startDate":"03022021",
               "startTime":"10:35",
               "endTime":"11:36",
               "endsOn":{
                  "never":true
               },
               "recurrencePattern":{
                  "recurrence":"daily",
                  "details":{
                     "days":"excludeWeekends"
                  }
               },
               "timeZone":{
                  "id":"Atlantic/Azores",
                  "offset":"-01:00"
               }
            },
            "processing_action":{
               "blackoutExistingEvents":"true",
               "resetStatusOnBlackoutEnd":"false"
            }
         }
      }
}

Parameter details

NameValue TypeDescriptionValid valuesMandatoryLocated in
namestring

Policy name

Unique valueyesbody
descriptionstring

Policy description

Any stringnobody

eventSelectorCriteria

string

Selection criteria

  • (
  • )
  • AND
  • OR
  • equals
  • contains
yesbody
timeframeDetailsstring

Time frame details


  • startDate         
  • startTime
  • endTime
  • endsOn
  • endDate
yesbody

startTime

stringStart time

Specify the time in the 24-hour time format.

yesbody

endTime

stringEnd time

Specify the time in the 24-hour time format.

yesbody
startDatestringSpecify the start dateSpecify the date in the mmddyyyy format.yesbody

endsOn

objectSpecify the ending criteria for the policy

The endsOn object must contain one of the following parameters:

  • endDate
  • occurrences
  • never
yesbody
endDatestringEnd date

Specify the date in the mmddyyyy format

Note: If you choose recurrence as oneTime, you can only use the endDate parameter in the endsOn object.

yesbody
occurrencesintegerFrequency

Specify an integer value.

Note: Set a value to this parameter only if you have set the recurrence value as daily, monthly, or weekly.

yesbody
neverboolean

Indicates if the time frame has an end date.

  • true: Set it to true to indicate no end date.
  • false: Set it to false to specify an end date

Note: If you set this value to false, specify either an endDate or set the occurrences value.

yesbody
executionOrderintegerPolicy precedence

0-9999

yesbody
enabledbooleanIndicates if the policy is enabled or disabled
  • true: Specifies that the policy is enabled.
  • false: Specifies that the policy disabled.

By default, the policy is disabled.

nobody

recurrence

stringSpecify the policy recurrence frequency
  • oneTime

  • daily         
  • weekly
  • monthly
yesbody
detailsobject

Specify the recurrence details


  • If the recurrence is set to daily, specify one of the following values in the details:
    • days: all (Indicates all the weekdays)
    • days: excludeWeekends (Indicates all the weekdays excluding the weekends)
  • If the recurrence is set to weekly, specify one of the following values in the details:

daysOfWeek:[Specify a comma-separated list of the day in the numerical format]

Sunday is the first day of the week.

For example, daysOfWeek: [1-3, 5 ], which means include Sunday to Tuesday, and Thursday.

  • If the recurrence is set to monthly, specify one of the following values in the details:

dates: [Specify a comma-separated list of the dates in the numerical format]

For example, dates: [1-3, 15 ]

yes

Note: This parameter is mandatory if you specify the recurrence value to daily, weekly, or monthly.

body
timezonestring

Time zone details

  • ID
  • offset

For a complete list of time zones and the offset values, see timezone_list.xlsx.

nobody

blackoutExistingEvents

BooleanIndicates if the events are blacked out.
  • true
  • false

Note: If set to true, the status of existing events that matched the eventSelectorcriteria changes from Open to Blackout at the start of the blackout window.

nobody

resetStatusOnBlackoutEnd

BooleanIndicates if the event status is reset.
  • true
  • false

Note: If set to true, the status of existing blacked-out events changes to their last status at the end of the blackout window.

nobody


Successful response

{
     "resourceId": [
        "ed2a0747-5f0d-11eb-aa8a-d76cefcf6197"
    ]
}

Unsuccessful response

Name is mandatory and cannot be null or empty.
DELETE /events-service/api/v1.0/blackout_policies/{ID}
 Delete a blackout policy.
Request URL
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies/{ID}
Request URL - Example
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies/7a53b0e0-5fe0-11eb-aa8a-3b1c79082b69


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
NameValue TypeDescriptionvalid parameterMandatoryLocated in
IDstring

Policy identifier to delete a policy

Unique String value

yesPath


Successful response

{
       "resourceId": [
        "7a53b0e0-5fe0-11eb-aa8a-3b1c79082b69"
    ]
}

Unsuccessful response

Scenario 1

Bad Request : Invalid resource id specified: 6898e009-7b19-11eb-b21b-f1af2da78f158
#When the UUID format is invalid, the preceding error message is displayed.

Scenario 2

{
    "responseTimeStamp": 1614666222794,
    "statusCode": "POLICY_NOT_EXIST",
    "statusMsg": "[Failed to delete policy, entry doesn't exist in database]"
}
#When the UUID format is valid, but it does not exist in the database, the preceding error message is displayed.
PUT /events-service/api/v1.0/blackout_policies/{ID}
 Update an existing policy.


Request URL
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies/{ID}
Request URL - Example
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies/2955a3c0-5f07-11eb-ad61-c1b170e13220
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
{
    "name": "string",
    "description": "string",
    "executionOrder": "integer",
    "eventSelectorCriteria": "string",
    "enabled": "Boolean",
    "configurations":
        {
            "definition": {
                "timeframeDetails": {
                    "endsOn": {
                        "endDate": "date"
                    },
                    "recurrencePattern": {
                        "recurrence": "string",
                        "details": {}
                    },
                    "timeZone": {
                        "offset": "time zone format",
                        "id": "string"
                    },
                    "startTime": "time",
                    "endTime": "time",
                    "startDate": "date"
                },
                "processing_action": {
                    "resetStatusOnBlackoutEnd": "Boolean",
                    "blackoutExistingEvents": "Boolean"
                }
            },
            "timeframeStatus": "string"
        }       
      }
    }
}


Example Request Body
{ 
    "name": "testpolicy3",
    "description": "Policy Updated 12334",
    "executionOrder": 466,
    "eventSelectorCriteria": "( class equals 'EVENT' ) AND ( msg contains 'Test Message' )",
    "enabled": true,
    "configurations": {
        "definition": {
            "timeframeDetails": {
                "endsOn": {
                    "endDate": "25012021"
                },
                "recurrencePattern": {
                    "recurrence": "oneTime",
                    "details": {}
                },
                "timeZone": {
                    "offset": "+05:30",
                    "id": "Asia/Kolkata"
                },
                "startTime": "17:46",
                "endTime": "17:51",
                "startDate": "25012021"
            },
            "processing_action": {
                "resetStatusOnBlackoutEnd": false,
                "blackoutExistingEvents": true
            }
        }
    }
}
Parameter details
NameValue TypeDescriptionValid valuesMandatoryLocated in
namestring

Policy name

Note: Ensure that you do not change the policy name. Provide the same name as the original policy name.yesbody
descriptionstring

Policy description

Any stringnobody

eventSelectorCriteria

string

Selection criteria

  • (
  • )
  • AND
  • OR
  • equals
  • contains
yesbody
timeframeDetailsstring

Time frame details


  • startDate         
  • startTime
  • endTime
  • endsOn
  • endDate
yesbody

startTime

stringStart time

Specify the time in the 24-hour time format.

yesbody

endTime

stringEnd time

Specify the time in the 24-hour time format.

yesbody
startDatestringSpecify the start dateSpecify the date in the mmddyyyy format.yesbody

endsOn

objectSpecify the ending criteria for the policy

The endsOn object must contain one of the following parameters:

  • endDate
  • occurrences
  • never
yesbody
endDatestringEnd date

Specify the date in the mmddyyyy format

Note: If you choose recurrence as oneTime, you can only use the endDate parameter in the endsOn object.

yesbody
occurrencesintegerFrequency

Specify an integer value.

Note: Set a value to this parameter only if you have set the recurrence value as daily, monthly, or weekly.

yesbody
neverboolean

Indicates if the time frame has an end date.

  • true: Set it to true to indicate no end date.
  • false: Set it to false to specify an end date

Note: If you set this value to false, specify either an endDate or set the occurrences value.

yesbody
executionOrderintegerPolicy precedence

0-9999

yesbody
configurationslistConfigurations of records on basis of attributes given
  • configOrder
  • type
  • definition
nobody
enabledbooleanIndicates if the policy is enabled or disabled
  • true: Specifies that the policy is enabled.
  • false: Specifies that the policy disabled.

By default, the policy is disabled.

nobody

recurrence

stringSpecify the policy recurrence frequency
  • oneTime

  • daily         
  • weekly
  • monthly
yesbody
detailsobject

Specify the recurrence details


  • If the recurrence is set to daily, specify one of the following values in the details:
    • days: all (Indicates all the weekdays)
    • days: excludeWeekends (Indicates all the weekdays excluding the weekends)
  • If the recurrence is set to weekly, specify one of the following values in the details:

daysOfWeek:[Specify a comma-separated list of the day in the numerical format]

Sunday is the first day of the week.

For example, daysOfWeek: [1-3, 5 ], which means include Sunday to Tuesday, and Thursday.

  • If the recurrence is set to monthly, specify one of the following values in the details:

dates: [Specify a comma-separated list of the dates in the numerical format]

For example, dates: [1-3, 15 ]

yes

Note: This parameter is mandatory if you specify the recurrence value to daily, weekly, or monthly.

body
timezonestring

Time zone details

  • ID
  • offset

For a complete list of time zones and the offset values, see timezone_list.xlsx.

nobody

blackoutExistingEvents

BooleanIndicates if the events are blacked out.
  • true
  • false

Note: If set to true, the status of existing events that matched the eventSelectorcriteria changes from Open to Blackout at the start of the blackout window.

nobody

resetStatusOnBlackoutEnd

BooleanIndicates if the event status is reset.
  • true
  • false

Note: If set to true, the status of existing blacked-out events changes to their last status at the end of the blackout window.

nobody


Successful response

{
    "resourceId": [
        "986fdcbf-5fe1-11eb-aa8a-35a509a3a64f"
    ]
}

Unsuccessful response

Scenario 1

Invalid eventSelectorCriteria: Matching brackets missing.

Scenario 2

Policy name should not be modified during update.
POST  /events-service/api/v1.0/blackout_policies/search
 Search a blackout policy.


Request URL
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_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.

Request Body
{
    "searchString": "string",
    "type": "string",
    "pageIndex": "integer,
    "recordsPerPage": "integer",
    "sortCriteria": {
        "attribute": "string",
        "order": "string"
    }
}


Example Request Body
{
    "searchString": "test",
    "type": "BLACKOUT",
    "pageIndex": 1,
    "recordsPerPage": 25,
    "sortCriteria": {
        "attribute": "modificationTime",
        "order": "ASC"
    }
}
Parameter details
NameValue TypeDescriptionValid valuesMandatory
pageIndexinteger

Page index

>= 1

no
recordsPerPageinteger

Number of records to display on a page

>= 1

no
attribute
stringPolicy sorting criteria
  • name
  • modificationTime
  • enabled
no
order
stringPolicy sorting order
  • ASC
  • DESC
no


Successful response

{
    "responseTimeStamp": 1614664916995,
    "statusCode": "200",
    "statusMsg": "OK",
    "totalRecords": 1,
    "policies": [
        {
            "name": "testpolicy3",
            "description": "Policy Updated 12334",
            "executionOrder": 466,
            "selector": "689647f8-7b19-11eb-b21b-f16b7b90db83",
            "eventSelectorCriteria": "( class equals 'EVENT' ) AND ( msg contains 'Test Message' )",
            "timeframes": [],
            "owner": "admin",
            "enabled": true,
            "readOnly": false,
            "creationTime": 1614663462432,
            "modificationTime": 1614663944484,
            "configurations": {
                "tenantId": "194864176",
                "policyId": "6898e009-7b19-11eb-b21b-f1af2da78f15",
                "id": "87ed8be3-7b1a-11eb-b21b-2fbe328e0339",
                "configOrder": 0,
                "creationTime": 0,
                "modificationTime": 0,
                "definition": {
                    "timeframeDetails": {
                        "endsOn": {
                            "endDate": "25012021"
                        },
                        "recurrencePattern": {
                            "recurrence": "oneTime",
                            "details": {}
                        },
                        "timeZone": {
                            "offset": "+05:30",
                            "id": "Asia/Kolkata"
                        },
                        "startTime": "17:46",
                        "endTime": "17:51",
                        "startDate": "25012021"
                    },
                    "processing_action": {
                        "resetStatusOnBlackoutEnd": false,
                        "blackoutExistingEvents": true
                    }
                },
                "timeframeStatus": "EXPIRED,LastRun:,NextRun:"
            }
        }
    ]
}

Unsuccessful response

Scenario 1

[
    {
        "key": "validation.schema.type",
        "level": "ERROR",
        "message": "[Path '/recordsPerPage'] Instance type (string) does not match any allowed primitive type (allowed: [\"integer\"])",
        "additionalInfo": []
    }
]

Scenario 2

[     
    {
        "key": "validation.schema.additionalProperties",
        "level": "ERROR",
        "message": "Object instance has properties which are not allowed by the schema: [\"searchString1\"]",
        "additionalInfo": []
    }
]
GET /events-service/api/v1.0/blackout_policies/{ID}
 Get policy details.


Request URL
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies/{ID}
Example Request URL
https://test.bmc.com/events-service/api/v1.0/blackout_policies/6898e009-7b19-11eb-b21b-f1af2da78f15


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

NameValue TypeDescriptionvalid parameterMandatoryLocated in
IDstring

Policy ID

Unique string value

yespath


Successful response

{
    "responseTimeStamp": 1614665610722,
    "statusCode": "200",
    "statusMsg": "[Policy found!]",
    "blackoutPolicy": {
        "name": "testpolicy3",
        "description": "Policy Updated 12334",
        "executionOrder": 466,
        "selector": "689647f8-7b19-11eb-b21b-f16b7b90db83",
        "eventSelectorCriteria": "( class equals 'EVENT' ) AND ( msg contains 'Test Message' )",
        "timeframes": [],
        "owner": "admin",
        "enabled": true,
        "readOnly": false,
        "creationTime": 1614663462432,
        "modificationTime": 1614663944484,
        "configurations": {
            "tenantId": "194864176",
            "policyId": "6898e009-7b19-11eb-b21b-f1af2da78f15",
            "id": "87ed8be3-7b1a-11eb-b21b-2fbe328e0339",
            "configOrder": 0,
            "creationTime": 0,
            "modificationTime": 0,
            "definition": {
                "timeframeDetails": {
                    "endsOn": {
                        "endDate": "25012021"
                    },
                    "recurrencePattern": {
                        "recurrence": "oneTime",
                        "details": {}
                    },
                    "timeZone": {
                        "offset": "+05:30",
                        "id": "Asia/Kolkata"
                    },
                    "startTime": "17:46",
                    "endTime": "17:51",
                    "startDate": "25012021"
                },
                "processing_action": {
                    "resetStatusOnBlackoutEnd": false,
                    "blackoutExistingEvents": true
                }
            },
            "timeframeStatus": "EXPIRED,LastRun:,NextRun:"
        }
    }
}


Unsuccessful response

Scenario 1

{
    "responseTimeStamp": 1614665656635,
    "statusCode": "500",
    "statusMsg": "[java.lang.IllegalArgumentException: UUID string too large]",
    "blackoutPolicy": null
}

Scenario 2

{
    "responseTimeStamp": 1614665718058,
    "statusCode": "500",
    "statusMsg": "[No policy found matching input request!]",
    "blackoutPolicy": null
}
Was this page helpful? Yes No Submitting... Thank you

Comments