Outages API - V2
...
NMIS has supported this for a long time, please refer to the NMIS Outages documentation for further information.
Now, it It is also possible to manage Outages within the Administration console or API.
The v2 api has added support for Elements of node (either interface or other) , for example defining an outage on just a single interface on a node. See ALL ABOUT ELEMENT OUTAGES Element Outages.
Public API for Outages "http[s]://server/en/omk/admin/api/v2/outages"
We can view Outages below using these endpoints - http[s]://server/en/omk/admin/api/v2/outages
...
All these methods require authentication.
POST http://server/en/omk/admin/login
Form data:
- username
- password
GET of /v2/outages for List
GET http[s]://server/en/omk/admin/api/v2/outages
If your GET call provides an Accept header indicating JSON, or if you use a .json suffix, eg /v2/outages.json as URI, then It will look for matching Outages and return their properties in the form of a JSON object, an array of Outages.
...
HTTP Status | Body | Description |
|---|---|---|
| 401 Unauthorized | JSON object with an error property | You are not authenticated. |
| 403 Forbidden | JSON object with an error property | You are not authorized. |
GET http://server/en/omk/admin/api/v2/outages
Returns a list of outages.
...
If your GET call provides an accept header indicating application/json or if you use /en/omk/admin/api/v2/outages/<id>.json as URI, then the Outage will be looked up and all properties will be returned in the form of a JSON object.
...
GET http://server/en/omk/admin/api/v2/outages/#ID
Ex. http://server/en/omk/admin/api/v2/outages/1f7ea042-0aaa-46a7-b34b-f9314952ee6f
Returns an outage.
Response:
...
DELETE http://server/en/omk/admin/api/v2/outages/0ea7644e-b6fa-4fa2-9b33-a86b79db21a4
Returns 200 if the outage was successfully removed.
...
Property | Description | Example |
| A globally unique Outage ID | 0ea7644e-b6fa-4fa2-9b33-a86b79db21a4 |
change_id | Insert any reference number if required in the change id field | ticket #12345 |
current | If the outage is current or scheduled/future outage. IS THIS 'current' for scheduled or null for future. | current |
description | Long description of an Outage | This is a test outage |
frequency | one of 'once', 'daily', 'weekly' or 'monthly' | once |
start | date and time of outage start. For Read, this is a Unix timestamp, the number of seconds since 1970-01-01 00:00:00 UTC | 2023-10-31T17:00:00+0000 |
end | date and time of outage end. For Read, this is a Unix timestamp, the number of seconds since 1970-01-01 00:00:00 UTC For Create and Update see Supported Time Formats for description of allowed values | 31 May 2023 03:30 pm |
nodes | List of nodes for which Outages is are defined. At least one of nodes or elements must be specified. | [ 'Switch-1','Switch-2' ] |
element | List of elements from nodes for which Outages are defined. element_name must be either a string or a regex pattern ( regex:pattern or iregex:pattern as shown in examples) element_name can be either interface name or other. | [ { "element_name": "Vlan2", "element_name": "iregex:^Vlan.*?$", [ { "node_name": "Switch-1" "element_name": "regex:^Vlan.*?$", |
options | optional key=values to adjust NMIS behaviour during an outage DOCUMENT THE KEYS AND VALUES | "Normal" |
...
| Code Block |
|---|
http[s]://server/omk/admin/v2/outages |
Anchor elements elements
| elements | |
| elements |
...
Element Outages
When opEvents receives an event which contains a node and an element, it will use the internal NMIS API to check if the combination of node and element has a scheduled outage defined or not, depending . Depending on the result an event property called "planned_outage" is set to "true" or "false".
When a scheduled outage is defined including elements, it will be restricted to a single node but can include multiple elements.
For example Node vmswitch1 has 4 interfaces out of 24 which will be impacted by an outage: GigabitEthernet1/10, GigabitEthernet1/11, GigabitEthernet1/12 , GigabitEthernet1/13.Code Block { "change_id": "ticket #1234", "description": "EmergencyPlanned outage", "elements" : [ { "node_name": "vmswitch1", "element_name" : "GigabitEthernet1/10" }, { "node_name": "vmswitch1", "element_name" : "GigabitEthernet1/11" }, { "node_name": "vmswitch1", "element_name" : "GigabitEthernet1/12" }, { "node_name": "vmswitch1", "element_name" : "GigabitEthernet1/13" } ], "start": "11-May-2023 23:21:03", "end": "15-May-2023 23:21:03" }
...