Settings API - Maintenance windows schema table

Maintenance windows (builtin:alerting.maintenance-window)

Maintenance windows are typically planned, recurring periods of system downtime during which your DevOps team can perform preventative maintenance and system upgrades outside of peak traffic hours. Documentation

To avoid having Dynatrace report on any performance anomalies that may result from such events, set up maintenance windows below that correspond with your organization's maintenance window schedule.

Schema ID
Schema groups
Scope
builtin:alerting.maintenance-window
  • group:maintenance
environment
GETManagedhttps://{your-domain}/e/{your-environment-id}/api/v2/settings/schemas/builtin:alerting.maintenance-window
SaaShttps://{your-environment-id}.live.dynatrace.com/api/v2/settings/schemas/builtin:alerting.maintenance-window
Environment ActiveGatehttps://{your-activegate-domain}/e/{your-environment-id}/api/v2/settings/schemas/builtin:alerting.maintenance-window

Authentication

To execute this request, you need an access token with Read settings (settings.read) scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

Property
Type
Description
Required
Enabled
enabled
boolean

The status of the maintenance window. If false, it is not considered during the maintenance window evaluation.

required
generalProperties
-
required
schedule
-
required
filters
Set<Filter>

Add filters to limit the scope of maintenance to only select matching entities. If no filter is defined, the maintenance window is valid for the whole environment. Each filter is evaluated separately (OR).

required
The GeneralProperties object
Property
Type
Description
Required
Name
name
text
-
required
Description
description
text

A short description of the maintenance purpose.

optional
Maintenance type
maintenanceType
enum

Whether the maintenance is planned or unplanned.

  • PLANNED
  • UNPLANNED
required
Problem detection and alerting
suppression
enum

Defines if alerting or problem generation is disabled.

  • Detect problems and alert: Problems are generated and alerted.
  • Detect problems but don't alert: Problems are generated but no alerts are sent out.
  • Disable problem detection during maintenance: Neither problems are generated nor alerts are sent out.
  • DETECT_PROBLEMS_AND_ALERT
  • DETECT_PROBLEMS_DONT_ALERT
  • DONT_DETECT_PROBLEMS
required
Disable synthetic monitor execution
disableSyntheticMonitorExecution
boolean

Disables the execution of the synthetic monitors that are within the scope of this maintenance window.

required
The Schedule object
Property
Type
Description
Required
Recurrence
scheduleType
enum

Defines the recurrence type of the maintenance window.

  • Once: One time maintenance window with start and end date time.
  • Daily: Maintenance window occurs every day during the configured time window.
  • Weekly: Maintenance window occurs each week on one day during the configured time window.
  • Monthly: Maintenance window occurs each month on one day during the configured time window.
  • ONCE
  • DAILY
  • WEEKLY
  • MONTHLY
required
onceRecurrence
-
required
dailyRecurrence
-
required
weeklyRecurrence
-
required
monthlyRecurrence
-
required
The Filter object
Property
Type
Description
Required
Entity type
entityType
text

Type of entities this maintenance window should match.

If no entity type is selected all entities regardless of the type will match.

optional
Entity
entityId
text

A specific entity that should match this maintenance window.

Note: If an entity type filter value is set, it must be equal to the type of the selected entity. Otherwise this maintenance window will not match.

optional
Entity tags
entityTags
set

Entities which contain all of the configured tags will match this maintenance window. It is recommended to use manual tags.

Note: Automatically applied tags may experience delays or inconsistencies due to rule complexity and attribute variability. Entities may not be immediately tagged, impacting filter effectiveness.

It is recommended to use manual tags instead.

For more information, visit our best practices for tagging documentation page.

required
Management zones
managementZones
set

Entities which are part of all the configured management zones will match this maintenance window. It is recommended to use manual tags instead.

Note: Management zones may experience delays or inconsistencies due to rule complexity and attribute variability. Entities may not be immediately assigned to management zones, impacting filter effectiveness.

It is recommended to use manual tags instead.

For more information, visit our best practices for management zones documentation page.

required
The OnceRecurrence object
Property
Type
Description
Required
Start time
startTime
local_date_time
-
required
End time
endTime
local_date_time
-
required
Timezone
timeZone
time_zone
-
required
The DailyRecurrence object
Property
Type
Description
Required
Time window
timeWindow
-
required
Recurrence range
recurrenceRange
-
required
The WeeklyRecurrence object
Property
Type
Description
Required
Day of week
dayOfWeek
enum
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY
required
Time window
timeWindow
-
required
Recurrence range
recurrenceRange
-
required
The MonthlyRecurrence object
Property
Type
Description
Required
Day of month
dayOfMonth
integer

If the selected day does not fall within the month, the maintenance window will be active on the last day of the month.

required
Time window
timeWindow
-
required
Recurrence range
recurrenceRange
-
required
The TimeWindow object
Property
Type
Description
Required
Start time
startTime
local_time
-
required
End time
endTime
local_time
-
required
Timezone
timeZone
time_zone
-
required
The RecurrenceRange object
Property
Type
Description
Required
Start date
scheduleStartDate
local_date
-
required
End date
scheduleEndDate
local_date
-
required