Rest API – Maintenance Windows
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.