Maintenance windows API - POST a maintenance window

Creates a new maintenance window.

The request consumes and produces an application/json payload.

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

Parameters

The body must not provide an ID. An ID is assigned automatically by the Dynatrace server.

Parameter Type Description In Required
body MaintenanceWindow

The JSON body of the request. Contains parameters of the new 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.

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/validator
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/config/v1/maintenanceWindows/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 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 & 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 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

api-examples/config/mw/post-mw.json
Download
{
  "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",
        "managementZoneId": 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:

POST example