Blackout policy configuration 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
POST /events-service/api/v1.0/blackout_policies
Create a blackout policy
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 ddmmyyyy 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 ddmmyyyy 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
DELETE /events-service/api/v1.0/blackout_policies/{ID}
Delete a blackout policy.
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
#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.
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 ddmmyyyy 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 ddmmyyyy 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
Scenario 2
Scenario 3: You attempt to update an active blackout policy.
"responseTimeStamp": 1659592746962,
"statusCode": "BLACKOUT_POLICY_ACTIVE",
"statusMsg": "[Failed to update, policy is in active state]"
}
POST /events-service/api/v1.0/blackout_policies/search
Search a blackout policy.
Authorization: Bearer <JWT_token>
For instructions on obtaining the JWT token, see Access and authentication for the REST API.
"searchString": "string",
"pageIndex": "integer,
"recordsPerPage": "integer",
"sortCriteria": {
"attribute": "string",
"order": "string"
}
}
"searchString": "test",
"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}
Get policy details.
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
Enable multiple blackout policies
Authorization: Bearer <JWT_token>
For instructions on obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
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
Disable multiple blackout policies
Authorization: Bearer <JWT_token>
For instructions on obtaining the JWT token, see Access and authentication for the REST API..
Parameter details
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": []
}
]