Maintenance Windows resources

The Maintenance Windows API allows you to manage maintenance window configurations for entities in Virtana Service Observability. Use this service to create, list, search or delete maintenance windows based on entity queries.

Resource list

• Create Maintenance Windows (POST /v1/modelcontext/maintwindows)
• List Maintenance Windows (POST /v1/modelcontext/maintwindows:list)
• Search Maintenance Windows (POST /v1/modelcontext/maintwindows:search)
• Delete Maintenance Windows (POST /v1/modelcontext/maintwindows:deleteBulk)

Authentication

All Virtana Service Observability API endpoints require HTTPS, expect JSON in the request body when a body is required, and return a JSON response. You must have an authentication key to send requests to a Virtana Service Observability API endpoint. The key is sent in the zenoss-api-key header of each request. For the maintenance windows APIs you must use a key generated from a User API type API client.

All of the following API examples use curl to send a JSON request from a Bash shell to an endpoint. All examples use YOUR-API-ENDPOINT and YOUR-API-KEY as placeholders for endpoints and authentication keys.

POST /v1/modelcontext/maintwindows

This operation creates maintenance window configurations for devices. Devices can be specified either by their unique entity ID (entityid) or by using an entity query. A typical entity query specifies criteria such as the device's type, for example, Base.Device schema ID, the Control Zone (CZ) it belongs to, and a meaningful field for identification, such as coreProperties.name, coreProperties.device, or an organizer like coreProperties._zorgs_device_class or coreProperties._zorgs_groups.

Request template

This is an abstract preview of a JSON request used to create a maintenance window (MW).

You can specify the following parameters:

• name: A unique identifier for the MW.
• maintenanceState: The state entities will be put into during the MW.
• exitState: The state entities will be put into after the MW finishes. This only applies if overrideExitState is set to true; otherwise, entities return to their state prior to the MW start.
• runMode: Can be AUTO (0) or Manual (1).
• state: Can be enabled (0) or disabled (1).
• schedule: Defines the timing of the MW:
  • start: When the MW execution should begin (in milliseconds).
  • duration: How long the MW should be active (in milliseconds).
  • recurrence: The timeout between each MW execution (in milliseconds). Set to null for no recurrence.
• description: A free-text description of the MW.
• owner: The owner of the MW.
• notification params: Parameters used for the Actions framework.
• tags: Optional tags.

To specify the entities to which the MW will apply, you can use either the withIds list (entity IDs) or a query.

The request returns the unique ID of the created MW.

{
  "specification": {
    "schedule": {
      "start": <Timestamp in milliseconds>,
      "duration": <duration in milliseconds>,
      "recurrence": null
    },
    "maintenanceState": <300>,
    "exitState": <1000>,
    "runMode": 0,
    "status": 0,
    "name": "<name>",
    "overrideExitState": false,
    "force": true,
    "description": "<description>",
    "doNotPropagateToChildren": false,
    "withIds": {
      "ids": [
        "<entityID1>"
      ]
    }
  }
}

OR

{
  "specification": {
    "schedule": {
      "start": <Timestamp in milliseconds>,
      "duration": <Duration in milliseconds>,
      "recurrence": null
    },
    "maintenanceState": <300>,
    "exitState": <1000>,
    "runMode": 0,
    "status": 0,
    "name": "<unique name>",
    "overrideExitState": false,
    "force": true,
    "description": "<optional description>",
    "doNotPropagateToChildren": false,
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "coreProperties.name",
                "value": "<name>",
                "operation": 1
              }
            },
            {
              "in": {
                "field": "schemaIds",
                "values": [
                  "Base.Device"
                ]
              }
            }
          ]
        }
      }
    }
  }
}

Request fields

specification (object, required)

Specification of the Maintenance Window (MW) configuration to be created.

schedule (object, required)

The schedule that determines when the MW will run.

start (number, required)

Determines when to start running the current MW (start) in milliseconds.

duration (number, required)

Determines how long the MW will run in milliseconds.

recurrence (object, required)

This setting is for advanced users. See the example workflow in Create a maintenance window, or use null for no recurrence.

maintenanceState (number, required)

Determines the production state that entities are set to during MW.

runMode (number, optional, default=0)

AUTO(0) or Manual(1).

status (number, optional, default=0)

enabled(0) or disabled(1).

exitState (number, optional)

Determines the production state that entities are set to after the MW ends. This is used with overrideExitState.

with_ids (object, optional)

Specify entities by ID list.

ids (array, required)

Array of entity IDs.

query (object, optional)

Specify entities using search criteria. Use instead of with_ids if you do not know the entity ids.

name (string, required)

Name of the MW configuration. This value must be unique.

description (string, optional)

Description of the MW configuration.

owner (string, optional)

Owner of the MW configuration.

overrideExitState (boolean, optional, default=false)

When provided as true with exitState, exiting MW with set productionState of specified entities with value exitState.

force (boolean, optional, default=false)

Advanced use. When specified as true, overrides checks on creating MWs with same entities on same schedule.

doNotPropagateToChildren (boolean, optional, default=false)

Advanced use. When specified as true, child entities of specified device entities will not have productionState set to maintenanceState during the MW instance run.

tags (array, optional)

Array of strings or tags.

notification (object, optional)

Notification with string message and array of string rules. See Setting up maintenance window rules and triggers.

Response fields

id

Maintenance Window ID which was just created.

Status codes

• 200 (created)
• 400 (invalid request - for example, MW name was repeated)
• 500 (internal server error)

Example

RequestResponse

curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/maintwindows: \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
    "specification": {
    "schedule": {
      "start": <start in milliseconds>,
      "duration": <duration in milliseconds>,
      "recurrence": null
    },
    "maintenanceState": 300,
    "name": "<unique mw name>",
    "description": "<mw description>",
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "coreProperties.name",
                "value": "<device name>",
                "operation": 1
              }
            },
            {
              "in": {
                "field": "schemaIds",
                "values": [
                  "Base.Device"
                ]
              }
            }
          ]
        }
      }
    }
  }        
}'

{
  "id": "mw_id"
}

POST /v1/modelcontext/maintwindows:list

Returns a list of Maintenance Window (MW) specifications configured for your tenant. This endpoint supports a paging mechanism, allowing you to specify the number of MWs to display per page and navigate through subsequent pages using cursors.

Request template

This sections shows a simplified representation of the JSON request used to retrieve a limited number of MWs within a single page.

{
  "page_input": {
    "limit": 10
  }
}

OR

{
  "page_input": {
    "limit": 10,
    "cursor": "<endcursor from previous page result>"
  }
}

Request fields

page_input (object, required)

Page selection criteria.

limit (number, optional)

Limit of MWs.

cursor (string, optional)

EndCursor from previous page results.

Response fields

maintWindows

Array of MW configuration objects that were created for that tenant, and each object includes the specification as described before as well as some extra housekeeping fields, like createdBy, updatedBy or deleted.

pageInfo

Object with startCursor and endCursor fields among others. EndCursor can be used to get remaining MWs.

Status codes

• 200 (successful)
• 500 (internal server error)

Example

RequestResponse

curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/maintwindows:list \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
  "page_input": {
    "limit": 10
  },
}'

{
  "maintWindows": [
    {
      "id": "<mw id>",
      "tenant": "<tenant name>",
      "query": {
        "type": "RESULT_TYPE_ENTITY",
        "timeRange": null,
        "clause": {
          "and": {
            "clauses": [
              {
                "filter": {
                  "field": "schemaIds",
                  "operation": "OP_CONTAINS",
                  "value": "Base.Device",
                  "options": []
                }
              },
              {
                "filter": {
                  "field": "name",
                  "operation": "OP_EQUALS",
                  "value": "pfg-windows-mssql",
                  "options": []
                }
              }
            ]
          }
        }
      },
      "runMode": "MANUAL",
      "schedule": {
        "start": "0",
        "duration": "600000",
        "skipNext": "0",
        "recurrence": null
      },
      "maintenanceState": "300",
      "exitState": "1000",
      "status": "ENABLED",
      "createTime": "1775526877007",
      "updateTime": "1775526877007",
      "deleted": false,
      "createdBy": "aparna.sundar@virtana.com",
      "updatedBy": "aparna.sundar@virtana.com",
      "name": "testInClause",
      "description": "",
      "owner": "",
      "notification": {
        "message": "",
        "rules": []
      },
      "tags": [],
      "doNotPropagateToChildren": false,
      "overrideExitState": false,
      "force": false
    }
  ],
  "pageInfo": {
    "startCursor": "",
    "endCursor": "fNybM12dj1zRmkLdQq8Ovw==",
    "count": "1",
    "totalCount": "1466",
    "hasNext": true,
    "hasPrev": false,
    "pending": "PENDING_FALSE"
  }
}

POST /v1/modelcontext/maintwindows:search

This endpoint allows you to search for specific Maintenance Windows (MWs) using defined filters. It requires a more advanced understanding of the query v2 syntax, for example, searching for all MWs with run_mode: manual.

Request template

This section provides an abstract preview of the JSON request used to search for specific MWs, such as one with a unique name.

{
  "search_input": {
    "page_input": {
      "limit": 10
    },
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "name",
                "value": "testMwById",
                "operation": 1
              }
            }
          ]
        }
      }
    }
  }
}

Request fields

search_input (object, required)

Search criteria in query format. See Trigger queries for more details.

query (object, required)

Query defining which MWs this search applies to.

page_input (object, optional)

Pagination input for the request.

limit (number, required)

Limit of MWs.

Response fields

maintWindows

Array of MW configuration objects that match the search criteria specified for that tenant. Each object includes the specification as described before as well as some extra housekeeping fields like createdBy, updatedBy or deleted.

pageInfo

Object with startCursor and endCursor fields among others. EndCursor can be used to get remaining MWs.

Status codes

• 200 (successful)
• 400 (invalid request - for example, search input was empty)
• 500 (internal server error)

Example

RequestResponse

curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/maintwindows:search \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
    "search_input": {
    "page_input": {
      "limit": 1
    },
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "name",
                "value": "testMwByQuery",
                "operation": 1
              }
            }
          ]
        }
      }
    }
  } 
}'

{
  "maintWindows": [
    {
      "id": "99fa4d8b-3223-11f1-8920-625b6e77d030",
      "tenant": "<tenant>",
      "query": {
        "type": "RESULT_TYPE_ENTITY",
        "timeRange": null,
        "clause": {
          "and": {
            "clauses": [
              {
                "filter": {
                  "field": "coreProperties.name",
                  "operation": "OP_EQUALS",
                  "value": "pfg-windows-mssql",
                  "options": []
                }
              },
              {
                "in": {
                  "field": "schemaIds",
                  "values": [
                    "Base.Device"
                  ],
                  "options": []
                }
              }
            ]
          }
        }
      },
      "runMode": "AUTO",
      "schedule": {
        "start": "1780775331000",
        "duration": "600000",
        "skipNext": "0",
        "recurrence": null
      },
      "maintenanceState": "300",
      "exitState": "0",
      "status": "ENABLED",
      "createTime": "1775526391375",
      "updateTime": "1775526391375",
      "deleted": false,
      "createdBy": "asundar@zenoss.com",
      "updatedBy": "asundar@zenoss.com",
      "name": "testMwByQuery",
      "description": "test mw by entity id",
      "owner": "",
      "notification": null,
      "tags": [],
      "doNotPropagateToChildren": false,
      "overrideExitState": false,
      "force": false
    }
  ],
  "pageInfo": {
    "startCursor": "",
    "endCursor": "pZqj4W2bXosHRgE-UszbIw==",
    "count": "1",
    "totalCount": "7",
    "hasNext": true,
    "hasPrev": false,
    "pending": "PENDING_FALSE"
  }
}

POST /v1/modelcontext/maintwindows:deleteBulk

This endpoint deletes the Maintenance Windows (MWs) corresponding to the provided list of identifiers (IDs).

Request template

This sections shows a sample JSON structure illustrating the request body used to delete specific Maintenance Windows by their ID.

{
  "ids": [
    "<mw id>"
  ]
}

Request fields

ids (array of strings, required)

Array of MW IDs that need to be deleted. These are the same IDs you get on creation as response.

Status codes

• 200 (successful)
• 400 (invalid request - for example, no IDs provided)
• 404 (not found - for example, no MW by provided ID)
• 500 (internal server error)

Example

RequestResponse

curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/maintwindows:deleteBulk \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
    "ids": [
        "<mw id>"
      ]
}'

{}