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
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies
Content-Type: application/json
Authorization: Bearer <JWT_token>
For instructions on obtaining the JWT token, see
Access and authentication for the REST API.
{
"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"
}
}
}
}
{
"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"
}
}
}
}
{
"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"
}
}
}
}
{
"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"
}
}
}
}
{
"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"
}
}
}
}
{
"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"
}
}
}
}
{
"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
Name | Value Type | Description | Valid values | Mandatory | Located in |
---|---|---|---|---|---|
name | string | Policy name | Unique value | yes | body |
description | string | Policy description | Any string | no | body |
eventSelectorCriteria | string | Selection criteria |
| yes | body |
timeframeDetails | string | Time frame details |
| yes | body |
startTime | string | Start time | Specify the time in the 24-hour time format. | yes | body |
endTime | string | End time | Specify the time in the 24-hour time format. | yes | body |
startDate | string | Specify the start date | Specify the date in the mmddyyyy format. | yes | body |
endsOn | object | Specify the ending criteria for the policy | The endsOn object must contain one of the following parameters:
| yes | body |
endDate | string | End 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. | yes | body |
occurrences | integer | Frequency | Specify an integer value. Note: Set a value to this parameter only if you have set the recurrence value as daily, monthly, or weekly. | yes | body |
never | boolean | Indicates if the time frame has an end date. |
Note: If you set this value to false, specify either an endDate or set the occurrences value. | yes | body |
executionOrder | integer | Policy precedence | 0-9999 | yes | body |
enabled | boolean | Indicates if the policy is enabled or disabled |
By default, the policy is disabled. | no | body |
recurrence | string | Specify the policy recurrence frequency |
| yes | body |
details | object | Specify the recurrence 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.
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 |
timezone | string | Time zone details |
For a complete list of time zones and the offset values, see timezone_list.xlsx. | no | body |
blackoutExistingEvents | Boolean | Indicates if the events are blacked out. |
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. | no | body |
resetStatusOnBlackoutEnd | Boolean | Indicates if the event status is reset. |
Note: If set to true, the status of existing blacked-out events changes to their last status at the end of the blackout window. | no | body |
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}
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies/{ID}
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies/7a53b0e0-5fe0-11eb-aa8a-3b1c79082b69
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 | Description | valid parameter | Mandatory | Located in |
---|---|---|---|---|---|
ID | string | Policy identifier to delete a policy | Unique String value | yes | Path |
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}
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies/{ID}
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies/2955a3c0-5f07-11eb-ad61-c1b170e13220
Content-Type: application/json
Authorization: Bearer <JWT_token>
For instructions on obtaining the JWT token, see
Access and authentication for the REST API.
{
"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"
}
}
}
}
{
"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
Name | Value Type | Description | Valid values | Mandatory | Located in |
---|---|---|---|---|---|
name | string | Policy name | Note: Ensure that you do not change the policy name. Provide the same name as the original policy name. | yes | body |
description | string | Policy description | Any string | no | body |
eventSelectorCriteria | string | Selection criteria |
| yes | body |
timeframeDetails | string | Time frame details |
| yes | body |
startTime | string | Start time | Specify the time in the 24-hour time format. | yes | body |
endTime | string | End time | Specify the time in the 24-hour time format. | yes | body |
startDate | string | Specify the start date | Specify the date in the mmddyyyy format. | yes | body |
endsOn | object | Specify the ending criteria for the policy | The endsOn object must contain one of the following parameters:
| yes | body |
endDate | string | End 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. | yes | body |
occurrences | integer | Frequency | Specify an integer value. Note: Set a value to this parameter only if you have set the recurrence value as daily, monthly, or weekly. | yes | body |
never | boolean | Indicates if the time frame has an end date. |
Note: If you set this value to false, specify either an endDate or set the occurrences value. | yes | body |
executionOrder | integer | Policy precedence | 0-9999 | yes | body |
configurations | list | Configurations of records on basis of attributes given |
| no | body |
enabled | boolean | Indicates if the policy is enabled or disabled |
By default, the policy is disabled. | no | body |
recurrence | string | Specify the policy recurrence frequency |
| yes | body |
details | object | Specify the recurrence 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.
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 |
timezone | string | Time zone details |
For a complete list of time zones and the offset values, see timezone_list.xlsx. | no | body |
blackoutExistingEvents | Boolean | Indicates if the events are blacked out. |
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. | no | body |
resetStatusOnBlackoutEnd | Boolean | Indicates if the event status is reset. |
Note: If set to true, the status of existing blacked-out events changes to their last status at the end of the blackout window. | no | body |
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
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_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.
{
"searchString": "string",
"type": "string",
"pageIndex": "integer,
"recordsPerPage": "integer",
"sortCriteria": {
"attribute": "string",
"order": "string"
}
}
{
"searchString": "test",
"type": "BLACKOUT",
"pageIndex": 1,
"recordsPerPage": 25,
"sortCriteria": {
"attribute": "modificationTime",
"order": "ASC"
}
}
Parameter details
Name | Value Type | Description | Valid values | Mandatory |
---|---|---|---|---|
pageIndex | integer | Page index | >= 1 | no |
recordsPerPage | integer | Number of records to display on a page | >= 1 | no |
attribute | string | Policy sorting criteria |
| no |
order | string | Policy sorting order |
| 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}
https://<BMC Helix Portal URL>/events-service/api/v1.0/blackout_policies/{ID}
https://test.bmc.com/events-service/api/v1.0/blackout_policies/6898e009-7b19-11eb-b21b-f1af2da78f15
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 | Description | valid parameter | Mandatory | Located in |
---|---|---|---|---|---|
ID | string | Policy ID | Unique string value | yes | path |
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
}
POST /events-service/api/v1.0/blackout_policies/enable
https://<tenant-url>/events-service/api/v1.0/blackout_policies/enable
https://HostA.bmc.com/events-service/api/v1.0/blackout_policies/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 | Located In | Mandatory | Description |
---|---|---|---|---|
ids | String | Body | Yes | Comma-separated list of policy IDs |
Request body
{
"ids": [
"string"
]
}
Example request body
{
"ids": [
"d6d8863c-3df8-11eb-9812-a972fa20cf57",
"d32fc78e-3558-11eb-9812-c3cbbc933af7"
]
}
Successful response
{
"message": "Enabled event policies",
"object": [
"696447ff-008d-4ef7-a417-2c506abad552"
]
}
Unsuccessful responses
Scenario 1: You do not specify a blackout policy ID
[
{
"key": "400",
"level": "ERROR",
"message": "Bad Request : Property is null or empty : resources",
"additionalInfo": []
}
]
Scenario 2: You specify an invalid blackout policy ID
[
{
"key": "400",
"level": "ERROR",
"message": "Bad Request : Invalid resource id specified: 11",
"additionalInfo": []
}
]
POST /events-service/api/v1.0/blackout_policies/disable
https://<tenant-url>/events-service/api/v1.0/blackout_policies/disable
https://HostA.bmc.com/events-service/api/v1.0/blackout_policies/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 | Located In | Mandatory | Description |
---|---|---|---|---|
ids | String | Body | Yes | Comma-separated list of policy IDs |
Request body
{
"ids": [
"string"
]
}
Example request body
{
"ids": [
"d6d8863c-3df8-11eb-9812-a972fa20cf57",
"d32fc78e-3558-11eb-9812-c3cbbc933af7"
]
}
Successful response
{
"message": "Disabled event policies",
"object": [
"696447ff-008d-4ef7-a417-2c506abad552"
]
}
Unsuccessful responses
Scenario 1: You do not specify a blackout policy ID
[
{
"key": "400",
"level": "ERROR",
"message": "Bad Request : Property is null or empty : resources",
"additionalInfo": []
}
]
Scenario 2: You specify an invalid blackout policy ID
[
{
"key": "400",
"level": "ERROR",
"message": "Bad Request : Invalid resource id specified: 11",
"additionalInfo": []
}
]
Comments
Log in or register to comment.