Maintenance windows API - PUT a maintenance window

Updates the specified maintenance window. If a maintenance window with the specified ID doesn't exist, a new one is created.

The request consumes and produces an application/json payload.

PUT
  • Managed https://{your-domain}/e/{your-environment-id}/api/config/v1/maintenanceWindows/{id}
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/config/v1/maintenanceWindows/{id}

Parameters

Parameter Type Description In Required
id string

The ID of the maintenance window to be updated.

path required
body MaintenanceWindow

The JSON body of the request. Contains updated parameters of the maintenance window.

body optional

The MaintenanceWindow object

Configuration of a maintenance window.

Element Type Description Required
metadata ConfigurationMetadata

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.

The type element can hold these values.
required
suppression string

The type of suppression of alerting and problem detection during the maintenance.

The suppression element can hold these values.
required
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 date, time, and recurrence of the maintenance window.

required

The Schedule object

The schedule of the maintenance window.

Element Type Description Required
recurrenceType string

The type of the schedule recurrence.

The recurrenceType element can hold these values.
required
recurrence Recurrence

The recurrence of the schedule.

Not applicable if recurrenceType is Once.

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 UTC+01:00 format or the IANA Time Zone Database format (for example, Europe/Vienna).

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 THURSDAY.

The dayOfWeek element can hold these values.
optional
dayOfMonth integer

The day of the month for monthly maintenance.

The value of 31 is treated as the last day of the month for months that don't have a 31st day. The value of 30 is also treated as the last day of the month for February.

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

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 MonitoredEntityFilter[]

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.

The type element can hold these values.
optional
managementZoneId integer

The ID of a management zone to which the matched entities must belong.

optional
tags TagInfo[]

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.

The tagCombination element can hold these values.
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 CONTEXTLESS value.

The context element can hold these values.
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 ConfigurationMetadata object

Metadata useful for debugging

Element Type Description Required
configurationVersions integer[]

A Sorted list of the version numbers of the configuration.

optional
clusterVersion string

Dynatrace server version.

optional

Possible values

Possible values for the dayOfWeek element in the Recurrence object:

  • FRIDAY
  • MONDAY
  • SATURDAY
  • SUNDAY
  • THURSDAY
  • TUESDAY
  • WEDNESDAY

Possible values for the recurrenceType element in the Schedule object:

  • DAILY
  • MONTHLY
  • ONCE
  • WEEKLY

Possible values for the tagCombination element in the MonitoredEntityFilter object:

  • AND
  • OR

Possible values for the context element in the TagInfo object:

  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_CLOUD
  • KUBERNETES

Possible values for the type element in the MonitoredEntityFilter object:

  • APPLICATION
  • APPLICATION_METHOD
  • APPLICATION_METHOD_GROUP
  • AUTO_SCALING_GROUP
  • AUXILIARY_SYNTHETIC_TEST
  • AWS_APPLICATION_LOAD_BALANCER
  • AWS_AVAILABILITY_ZONE
  • AWS_CREDENTIALS
  • AWS_LAMBDA_FUNCTION
  • AWS_NETWORK_LOAD_BALANCER
  • AZURE_API_MANAGEMENT_SERVICE
  • AZURE_APPLICATION_GATEWAY
  • AZURE_COSMOS_DB
  • AZURE_EVENT_HUB
  • AZURE_EVENT_HUB_NAMESPACE
  • AZURE_FUNCTION_APP
  • AZURE_IOT_HUB
  • AZURE_LOAD_BALANCER
  • AZURE_REDIS_CACHE
  • AZURE_REGION
  • AZURE_SERVICE_BUS_NAMESPACE
  • AZURE_SERVICE_BUS_QUEUE
  • AZURE_SERVICE_BUS_TOPIC
  • AZURE_SQL_DATABASE
  • AZURE_SQL_ELASTIC_POOL
  • AZURE_SQL_SERVER
  • AZURE_STORAGE_ACCOUNT
  • AZURE_SUBSCRIPTION
  • AZURE_VM
  • AZURE_VM_SCALE_SET
  • AZURE_WEB_APP
  • CF_APPLICATION
  • CF_FOUNDATION
  • CINDER_VOLUME
  • CUSTOM_APPLICATION
  • CUSTOM_DEVICE
  • CUSTOM_DEVICE_GROUP
  • DCRUM_APPLICATION
  • DCRUM_SERVICE
  • DCRUM_SERVICE_INSTANCE
  • DISK
  • DOCKER_CONTAINER_GROUP_INSTANCE
  • DYNAMO_DB_TABLE
  • EBS_VOLUME
  • EC2_INSTANCE
  • ELASTIC_LOAD_BALANCER
  • ENVIRONMENT
  • EXTERNAL_SYNTHETIC_TEST_STEP
  • GCP_ZONE
  • GEOLOCATION
  • GEOLOC_SITE
  • GOOGLE_COMPUTE_ENGINE
  • HOST
  • HOST_GROUP
  • HTTP_CHECK
  • HTTP_CHECK_STEP
  • HYPERVISOR
  • KUBERNETES_CLUSTER
  • KUBERNETES_NODE
  • MOBILE_APPLICATION
  • NETWORK_INTERFACE
  • NEUTRON_SUBNET
  • OPENSTACK_PROJECT
  • OPENSTACK_REGION
  • OPENSTACK_VM
  • OS
  • PROCESS_GROUP
  • PROCESS_GROUP_INSTANCE
  • RELATIONAL_DATABASE_SERVICE
  • SERVICE
  • SERVICE_INSTANCE
  • SERVICE_METHOD
  • SERVICE_METHOD_GROUP
  • SWIFT_CONTAINER
  • SYNTHETIC_LOCATION
  • SYNTHETIC_TEST
  • SYNTHETIC_TEST_STEP
  • VIRTUALMACHINE
  • VMWARE_DATACENTER

Possible values for the suppression element in the MaintenanceWindow object:

  • DETECT_PROBLEMS_AND_ALERT
  • DETECT_PROBLEMS_DONT_ALERT
  • DONT_DETECT_PROBLEMS

Possible values for the type element in the MaintenanceWindow object:

  • PLANNED
  • UNPLANNED

Response format

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 codes

Code Description
201

Success. The new maintenance window has been created. The response body contains its ID.

204

Success. The maintenance window has been updated. The response doesn't have a body.

400

Failed. The input is invalid.

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.

POST
  • Managed https://{your-domain}/e/{your-environment-id}/api/config/v1/maintenanceWindows/{id}/validator
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/config/v1/maintenanceWindows/{id}/validator

Response codes

Code Description
204 Validated. The submitted configuration is valid. Response doesn't have a body
400 Failed. The input is invalid.

Example

In this example, the request updates the infrastructure maintenance maintenance window from the GET request example

The initial configuration is the following:

GET example

The request changes the recurrence to weekly maintenance on Mondays. It also adds hosts with tags TestWindows and TestLinux to the scope.

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.

Curl

curl -X PUT \
  https://mySampleEnv.live.dynatrace.com/api/config/v1/maintenanceWindows/0b989446-e56f-4837-a521-96f4d39a9b76 \
  -H 'Authorization: Api-token abcdefjhij1234567890' \
  -H 'Content-Type: application/json' \  
  -d '{ <truncated - see the Request body section > }'

Request URL

https://mySampleEnv.live.dynatrace.com/api/config/v1/maintenanceWindows/0b989446-e56f-4837-a521-96f4d39a9b76

Request body

api-examples/config/mw/put-mw.json
Download
{  
  "name": "infrastructure maintenance",
  "description": "Weekly check-up of infrastructure",
  "type": "PLANNED",
  "suppression": "DETECT_PROBLEMS_DONT_ALERT",
  "scope": {
    "entities": [],
    "matches": [
      {
        "type": "HOST",
        "managementZoneId": null,
        "tags": [
          {
            "context": "CONTEXTLESS",
            "key": "InfWindows"
          },
          {
            "context": "CONTEXTLESS",
            "key": "InfLinux"
          },
          {
            "context": "CONTEXTLESS",
            "key": "TestWindows"
          },
          {
            "context": "CONTEXTLESS",
            "key": "TestLinux"
          }
        ],
        "tagCombination": "OR"
      }
    ]
  },
  "schedule": {
    "recurrenceType": "WEEKLY",
    "recurrence": {
      "dayOfWeek": "MONDAY",
      "startTime": "19:00",
      "durationMinutes": 60
    },
    "start": "2019-07-01 00:00",
    "end": "2020-07-31 23:59",
    "zoneId": "Europe/Vienna"
  }
}

Response code

204

Result

The updated maintenance window has the following parameters:

PUT example