Upgrade maintenance windows

• Latest Dynatrace
• How-to guide
• 7-min read
• Updated on Oct 01, 2026

What changes

Classic maintenance windows are not migrated automatically. Every Classic maintenance window that affects a Synthetic monitor or a Synthetic location must be recreated in latest Dynatrace.

Maintenance windows in latest Dynatrace work as follows:

For the general procedure that applies to all maintenance windows, see Upgrade from Classic maintenance windows to Latest maintenance windows. This page covers the Synthetic-specific steps.

Step 1: Identify affected maintenance windows

List all Classic maintenance windows:

dtctl get settings --schema builtin:alerting.maintenance-window -o json --plain \
  | jq '.[] | select(
      .value.generalProperties.disableSyntheticMonitorExecution == true
      or (.value.filters | length) == 0
      or any(.value.filters[]?;
        (.entityType // "" | IN("SYNTHETIC_TEST", "HTTP_CHECK", "MULTIPROTOCOL_MONITOR", "SYNTHETIC_LOCATION"))
        or (.entityId // "" | test("^(SYNTHETIC_TEST|HTTP_CHECK|MULTIPROTOCOL_MONITOR|SYNTHETIC_LOCATION)-")))
    ) | {objectId, name: .value.generalProperties.name, filters: .value.filters}'

A window affects Synthetic monitors if any of the following applies:

You don't need to recreate expired one-time windows or recurring windows with no future occurrence.

Step 2: Translate the scope filter

Maintenance windows in latest Dynatrace use a single filter field with a DQL matcher expression. Translate Classic Synthetic entity types as follows:

Classic entityTags use AND semantics: all listed tags must match. Translate multiple tags as multiple matchesValue conditions combined with AND. Classic management zones map to segments in latest Dynatrace; resolve the segment first and use the corresponding filter.

For windows scoped to a specific entity ID, resolve the Classic ID to its Smartscape ID before writing the replacement filter:

smartscapeNodes "*"
| filter in(id_classic, {"SYNTHETIC_TEST-7EEF2AA5318E2F39"})
| fields id, id_classic, name, type

If a window covers more monitors than fit in the filter, use one of these options:

Step 3: Create replacement windows

Create each window in the latest Dynatrace format. Don't adapt the Classic payload.

To create windows with the Settings API instead, see Create a maintenance window via API.

Step 4: Configure handling during maintenance

Decide for each affected monitor how availability, alerts, and monitor execution should be handled during maintenance.

Availability: to exclude maintenance periods from availability, go to Settings > Analyze and alert > Synthetic Monitoring and turn on Exclude periods with maintenance windows from availability calculation. You can also filter on maintenance.is_under_maintenance in your DQL queries. See Exclude maintenance period executions from metrics calculations.

Alerts: to stop notifications during maintenance, add the following condition to the problem trigger of every notification workflow that should not fire during maintenance:

maintenance.is_under_maintenance != true

Classic problem notifications can't use this condition. Migrate them to workflows first. See Upgrade from Classic problem notification to simple workflows.

Monitor execution: if monitors must not run against a system under maintenance, create a separate workflow in Workflows that disables the affected monitors when the maintenance period starts and re-enables them when it ends.

Verify the upgrade

For every replacement window, confirm that:

After the replacement windows work as expected, disable the Classic windows. Don't delete them, so you can still refer to the original configuration. Keep a Classic window enabled while any Classic problem notification still depends on it.