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.dexp.ae/api/config/v1/maintenanceWindows

Authentication

To execute this request, you need the Write configuration permission assigned to your API token. See the Authentication page to learn how to obtain and use it.

Parameters

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

Parameter	Type	Description	In	Required
body	MaintenanceWindow	The JSON body of the request. Contains parameters of the new maintenance window.	body	optional

Request parameters JSON model

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 DESK 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 DESK 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 DESK entities (for example, hosts or services) to be included in the scope. Allowed values are DESK entity IDs.	required
matches	MonitoredEntityFilter[]	A list of matching rules for dynamic scope formation. If several rules are set, the OR logic applies.	required

Element

Type

Description

Required

entities

string[]

A list of DESK entities (for example, hosts or services) to be included in the scope.

Allowed values are DESK 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 DESK entities.

Element	Type	Description	Required
type	string	The type of the DESK 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 DESK entity.

Element Type Description Required

context

string

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 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	DESK server version.	optional

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request. See the Example expandable section for working sample request.

      
  {
  "metadata": {
    "configurationVersions": [
      4,
      2
    ],
    "clusterVersion": {
      "major": 0,
      "minor": 0,
      "revision": 0,
      "sourceRevision": "",
      "timestamp": ""
    }
  },
  "name": "Example Window",
  "description": "An example Maintenance window\n",
  "type": "UNPLANNED",
  "suppression": "DETECT_PROBLEMS_AND_ALERT",
  "scope": {
    "entities": [
      "HOST-0000000000123456"
    ],
    "matches": [
      {
        "type": "HOST",
        "managementZoneId": 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"
  }
}

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:

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_CREDENTIALS
AZURE_EVENT_HUB
AZURE_EVENT_HUB_NAMESPACE
AZURE_FUNCTION_APP
AZURE_IOT_HUB
AZURE_LOAD_BALANCER
AZURE_MGMT_GROUP
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_TENANT
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

Response parameters JSON model

The EntityShortRepresentation object

The short representation of a DESK entity.

Element	Type	Description
id	string	The ID of the DESK entity.
name	string	The name of the DESK entity.
description	string	A short description of the DESK 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.dexp.ae/api/config/v1/maintenanceWindows/validator

Authentication

To execute this request, you need the Write configuration permission assigned to your API token. See the Authentication page to learn how to obtain and use it.

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.dexp.ae/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.dexp.ae/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