Skip to main content
Matrix42 Self-Service Help Center

Rest API – Maintenance Windows

How to create, update, query and delete maintenance windows using the FireScope REST API.

Overview

The REST API allows you to work with Maintenance Windows in FireScope SPM using a REST client in lieu of the SPM user interface.

  • Retrieve
  • Schema
  • Create or Update
  • Delete

Retrieve

To retrieve the current information about a Maintenance Window in SPM, send unique query parameters in a GET request to the following URL:

http://localhost:38050/web_services/maintenance_window?account=firescope&name=Weekly upgrade

Note: Don’t forget to change the domain name (localhost) and query parameter values (account, edge_device, ci, and name) to match your environment and data.

A JSON response will be returned similar in structure to the payload for creation.

Query Parameter Descriptions

Parameter Description Type Required
account Name of the SPM Account. String Yes
name Name of the Maintenance Window. String Yes

Schema

To retrieve the full SPM schema for a Maintenance Window, send the Account name with the schema parameter set to true in a GET request to the following URL:

http://[SPM IP address]:38050/web_services/maintenance_window?account=[Account name]&schema=true

Create or Update

To create or update an Maintenance Window, POST a JSON document with the specific Maintenance Window information to the following URL:

http://[SPM IP address]:38050/web_services/maintenance_window

You can use the following example as a guide, but note that it does not include all optional properties.

{
 "account_id": "firescope",
  "name": "Weekly Upgrade",
  "description": "Maintenance Window for weekly upgrade of application servers",
  "first_end_date": 1434399000,
  "first_start_date": 1434398300,
  "ci": [{ "edge_device": "Edge 1", "ci": "10.0.12.134" }],
  "logicalgroup": [ "Application Servers" ],
  "eventdef": [{ "edge_device": "Edge 1", "eventdef": "Response time < 50ms" }],
  "ical": {
    "frequency": "WEEKLY",
    "interval": 1,
    "occurrences": 3
  }
}

Property Descriptions

The following table provides information about all required and optional properties available for a Maintenance Window.

Property Description Type Default Value Required
account_id Name of the SPM Account. String   Yes
name Name of the Maintenance Window. String   Yes
ci A list of CI’s that need to be a part of this maintenance window. Any eventdefs associated to these CI’s are disregarded until the maintenance time ends. At least one of ci, eventdef, or logicalgroup fields has to be populated. Object[]   No
description A description for the purpose of this Maintenance Window String   Yes
eventdef A list of eventdefs that need to be a part of this maintenance window. At least one of ci, eventdef, or logicalgroup fields has to be populated. Object[]   No
final_end_date The timestamp in seconds from the epoch when this maintenance window should run for the last time. Leave null to have it run indefinitely. The value must be on or after the first end date. This corresponds to the UNTIL in the iCalendar specification. Number 2147385600 No
first_end_date The timestamp in seconds from the epoch when this maintenance window should end its initial run. The end date must be at least 10 minutes greater than the start date. The end date must be set to a date in the past for retroactive maintenance windows. This corresponds to the DTEND in the iCalendar specifiction. Number   Yes
first_start_date The timestamp in seconds from the epoch when this maintenance window should start its initial run. The start date must be at least 5 minutes greater than the current time. This in conjunction with the first_end_date are used to define the ongoing period when the maintenance window should run. This corresponds to the DTSTART in the iCalendar specifiction. Number   Yes
ical These fields determine how often the period defined by the first and end dates are repeated:
PropertyDescriptionTypeDefault ValueRequireddaysA list of days of the month (1-31) that this maintenance window should run. Used to limit the days to run for DAILY or to expand the days to run for MONTHLY.Number[] Nodays_of_weekA list of days of the week that this maintenance window should run. Used to limit when it should run for DAILY or to expand the days to run for WEEKLY and MONTHLY.Sun Mon Tue Wed Thu Fri SatString[] NofrequencyIndicates how frequent this maintenance window should repeat.DAILY – Repeats every day.WEEKLY – Repeats every week.MONTHLY – Repeats every month.onetime – Does not repeatretro – Retroactive maintenance window to adjust past events. Start and end times must be in the past.StringonetimeYesintervalHow often this maintenance should repeat relative to its frequency. For example, an interval of 2 with a frequency of DAILY would repeat every other day, but with a frequency of WEEKLY it would be every other week.Number0YesoccurrencesHow many times this maintenance window should repeat until it should end. Leave empty or set to 0 to repeat indefinitely. This can be superseded using the final_end_date, however.Number0Yes
Object   Yes
logicalgroup A list of logical groups that need to be a part of this maintenance window. At least one of ci, eventdef, or logicalgroup fields has to be populated. String[]   No
maintenance_window_instance A read-only list of instances that represent previous runs of this maintenance windows.
PropertyDescriptionTypeDefault ValueRequiredciA list of CIs this maintenance window was applied to.Object[] NoeventdefA list of eventdefs this maintenance window was applied to.Object[] Noend_dateWhen this maintenance window instance finished.Number YesicalSee ical section above for previous definition.Object YeslogicalgroupA list of logical groups this maintenance window instance was applied to.String[] NonameThe name of this instance at the time of execution.String Yesstart_dateWhen this maintenance window instance started.Number Yes
Object[]   No
next_end_date The read-only timestamp of the next time the maintenance window should end. Number   No
next_start_date The read-only timestamp of the next time the maintenance window should start. Number   No

Delete

To delete an Maintenance Window send an HTTP DELETE request with the same query parameters as the GET request.

See the Retrieve for the URL format and query parameter descriptions.

  • Was this article helpful?