Maintenance windows API - POST a maintenance window
This API is deprecated. Use the Settings API with the Maintenance windows (builtin:alerting.maintenance-window
) schema instead.
Creates a new maintenance window.
The request consumes and produces an application/json
payload.
POST | ManagedDynatrace for Government | https://{your-domain}/e/{your-environment-id}/api/config/v1/maintenanceWindows |
SaaS | https://{your-environment-id}.live.dynatrace.com/api/config/v1/maintenanceWindows | |
Environment ActiveGate | https://{your-activegate-domain}/e/{your-environment-id}/api/config/v1/maintenanceWindows |
Authentication
To execute this request, you need an access token with WriteConfig
scope.
To learn how to obtain and use it, see Tokens and authentication.
Parameters
The body must not provide an ID. An ID is assigned automatically by Dynatrace.
Parameter | Type | Description | In | Required |
---|---|---|---|---|
body | Maintenance | The JSON body of the request. Contains parameters of the new maintenance window. | body | optional |
Request body objects
The MaintenanceWindow
object
Configuration of a maintenance window.
Element | Type | Description | Required |
---|---|---|---|
metadata | Configuration | Metadata useful for debugging | optional |
id | string | The ID of the maintenance window. | optional |
name | string | The name of the maintenance window, displayed in the UI. | required |
description | string | A short description of the maintenance purpose. | required |
type | string | The type of the maintenance: planned or unplanned. | required |
suppression | string | The type of suppression of alerting and problem detection during the maintenance. | required |
suppressSyntheticMonitorsExecution | boolean | Suppress execution of synthetic monitors during the maintenance. | optional |
scope | Scope | The scope of the maintenance window. The scope restricts the alert/problem detection suppression to certain Dynatrace entities. It can contain a list of entities and/or matching rules for dynamic formation of the scope. If no scope is specified, the alert/problem detection suppression applies to the entire environment. | optional |
schedule | Schedule | The schedule of the maintenance window. | required |
The ConfigurationMetadata
object
Metadata useful for debugging
Element | Type | Description | Required |
---|---|---|---|
configurationVersions | integer[] | A sorted list of the version numbers of the configuration. | optional |
currentConfigurationVersions | string[] | A sorted list of version numbers of the configuration. | optional |
clusterVersion | string | Dynatrace version. | optional |
The Scope
object
The scope of the maintenance window.
The scope restricts the alert/problem detection suppression to certain Dynatrace entities. It can contain a list of entities and/or matching rules for dynamic formation of the scope.
If no scope is specified, the alert/problem detection suppression applies to the entire environment.
Element | Type | Description | Required |
---|---|---|---|
entities | string[] | A list of Dynatrace entities (for example, hosts or services) to be included in the scope. Allowed values are Dynatrace entity IDs. | required |
matches | Monitored | A list of matching rules for dynamic scope formation. If several rules are set, the OR logic applies. | required |
The MonitoredEntityFilter
object
A matching rule for Dynatrace entities.
Element | Type | Description | Required |
---|---|---|---|
type | string | The type of the Dynatrace entities (for example, hosts or services) you want to pick up by matching. | optional |
mzId | string | The ID of a management zone to which the matched entities must belong. | optional |
tags | Tag | The tag you want to use for matching. You can use custom tags from the UI, AWS tags, Cloud Foundry tags, OpenShift/Kubernetes, and tags based on environment variables. | required |
tagCombination | string | The logic that applies when several tags are specified: AND/OR. If not set, the OR logic is used. | optional |
The TagInfo
object
Tag of a Dynatrace entity.
Element | Type | Description | Required |
---|---|---|---|
context | string | The origin of the tag, such as AWS or Cloud Foundry. Custom tags use the | required |
key | string | The key of the tag. Custom tags have the tag value here. | required |
value | string | The value of the tag. Not applicable to custom tags. | optional |
The Schedule
object
The schedule of the maintenance window.
Element | Type | Description | Required |
---|---|---|---|
recurrenceType | string | The type of the schedule recurrence. | required |
recurrence | Recurrence | The recurrence of the maintenance window. | optional |
start | string | The start date and time of the maintenance window validity period in yyyy-mm-dd HH:mm format. | required |
end | string | The end date and time of the maintenance window validity period in yyyy-mm-dd HH:mm format. | required |
zoneId | string | The time zone of the start and end time. Default time zone is UTC. You can use either UTC offset | required |
The Recurrence
object
The recurrence of the maintenance window.
Element | Type | Description | Required |
---|---|---|---|
dayOfWeek | string | The day of the week for weekly maintenance. The format is the full name of the day in upper case, for example | optional |
dayOfMonth | integer | The day of the month for monthly maintenance. The value of | optional |
startTime | string | The start time of the maintenance window in HH:mm format. | required |
durationMinutes | integer | The duration of the maintenance window in minutes. | required |
Request body JSON model
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.
{
"metadata": {
"configurationVersions": [
4,
2
],
"clusterVersion": "Mock version"
},
"name": "Example Window",
"description": "An example Maintenance window",
"type": "UNPLANNED",
"suppression": "DETECT_PROBLEMS_AND_ALERT",
"suppressSyntheticMonitorsExecution": "true",
"scope": {
"entities": [
"HOST-0000000000123456"
],
"matches": [
{
"type": "HOST",
"mzId": "123456789",
"tags": [
{
"key": "testkey",
"value": "testvalue",
"context": "AWS"
}
],
"tagCombination": "AND"
}
]
},
"schedule": {
"recurrenceType": "MONTHLY",
"recurrence": {
"dayOfMonth": "23",
"startTime": "16:28",
"durationMinutes": "60"
},
"start": "2018-08-02 00:00",
"end": "2019-02-27 00:00",
"zoneId": "Europe/Vienna"
}
}
Response
Response codes
Code | Type | Description |
---|---|---|
201 | Entity | Success. The new maintenance window has been created. The response body contains its ID. |
400 | ErrorEnvelope | Failed. The input is invalid |
Response body objects
The EntityShortRepresentation
object
The short representation of a Dynatrace entity.
Element | Type | Description |
---|---|---|
id | string | The ID of the Dynatrace entity. |
name | string | The name of the Dynatrace entity. |
description | string | A short description of the Dynatrace entity. |
Response body JSON model
{
"id": "6a98d7bc-abb9-44f8-ae6a-73e68e71812a",
"name": "Dynatrace entity",
"description": "Dynatrace entity for the REST API example"
}
Validate payload
We recommend that you validate the payload before submitting it with an actual request. A response code of 204 indicates a valid payload.
The request consumes an application/json
payload.
POST | ManagedDynatrace for Government | https://{your-domain}/e/{your-environment-id}/api/config/v1/maintenanceWindows/validator |
SaaS | https://{your-environment-id}.live.dynatrace.com/api/config/v1/maintenanceWindows/validator | |
Environment ActiveGate | https://{your-activegate-domain}/e/{your-environment-id}/api/config/v1/maintenanceWindows/validator |
Authentication
To execute this request, you need an access token with WriteConfig
scope.
To learn how to obtain and use it, see Tokens and authentication.
Response
Response codes
Code | Type | Description |
---|---|---|
204 | Validated. The submitted configuration is valid. Response doesn't have a body. | |
400 | ErrorEnvelope | Failed. The input is invalid |
Example
In this example, the request creates a new maintenance window for a one-time planned maintenance. The maintenance window begins at 8:00 am and ends at 1:00 pm on July 31st, 2019. It affects the application with the ID of APPLICATION-61A89B82DF26BCFC and all the hosts that have the MainApp custom tag. Problem detection is suppressed during this maintenance.
The API token is passed in the Authorization header.
The request body is lengthy, so it is truncated in the Curl section. See the full body in the Request body section. You can download or copy the example request body to try it out on your own. Be sure to use the entity IDs and tags that are available in your environment. You can retrieve the list of monitored entities with the Topology and Smartscape API and the list of tags with the Automatically applied tags API.
Curl
curl -X POST \
"https://mySampleEnv.live.dynatrace.com/api/config/v1/maintenanceWindows" \
-H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
-H 'Content-Type: application/json' \
-d '{ <truncated - see the Request body section > }'
Request URL
https://mySampleEnv.live.dynatrace.com/api/config/v1/maintenanceWindows
Request body
{
"name": "Main app update",
"description": "Deployment of a new version of the main application",
"type": "PLANNED",
"suppression": "DONT_DETECT_PROBLEMS",
"scope": {
"entities": ["APPLICATION-61A89B82DF26BCFC"],
"matches": [
{
"type": "HOST",
"mzId": null,
"tags": [
{
"context": "CONTEXTLESS",
"key": "MainApp"
}
],
"tagCombination": "OR"
}
]
},
"schedule": {
"recurrenceType": "ONCE",
"start": "2019-07-31 08:00",
"end": "2019-07-31 13:00",
"zoneId": "Europe/Vienna"
}
}
Response body
{
"id": "ac6f245d-e945-4e0c-85b1-8c134d0b05ad",
"name": "Main app update",
"description": "Deployment of a new version of the main app"
}
Response code
201
Result
The new maintenance window looks like this in the UI: