Outages API - V2

If you have When you schedule an outage or create a maintenance window or a scheduled outage for a device then you will likely want to suspend alerting , you can suspend event alerts for that device during that such outage period.NMIS has supported this for a long time, please refer to  NMIS enables you to easily manage the scheduled outages and maintenance windows on the NMIS portal; see the NMIS Outages documentation for further more information. 

Now, it is also possible to You can also manage Outages within the Administration console or the API.

The v2 api API has added support for "ELEMENT OUTAGES", for example the Elements of the nodes (interface or other), such as, defining an outage on just a single interface on a node.  See ALL ABOUT ELEMENT OUTAGES; see also Element Outages.

Public API for Outages 

You can view Outages

...

at http[s]://server/en/omk/admin/api/v2/outages

...

using the endpoints given below.

API Routes

We can view Outages below using these endpoints - http[s]://server/en/omk/admin/api/v2/outages

API Routes

...

Authentication

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 (for example, eg /v2/outages.json as URI), then It will look for matching Outages and return returns their properties in the form of a JSON object, an that is, an array of Outages.

Successful Response

Unsuccessful Response

GET http://server/en/omk/admin/api/v2/outages

Returns a list of outages.

Response:

[  
    {
        "change_id": "ticket #1234005",
        "current": "current",
        "description": "Emergency outage005",
        "elementelements": [
            {
                "element_name": "Vlan2lo",
                "node_name": "Switch-1A.TEST"
            },
            {
                "element_name": "regex:^Vlan.*?$Vlan1",
                "node_name": "Switch-21"
            }
        ],
        "end": 16841568631685541600,
        "frequency": "once",
        "id": "0ea7644e7a2011c7-b6fa2880-4fa240ab-9b33aa17-a86b79db21a412a110cc1c23",
        "nodes": {
    [],
        "nameoptions": [{
            "nostats": 0
    "Switch-2",
    },
        "start": 1685455200
    "Switch-1"
},
    {
         ]
"change_id": "001",
        "current": }null,
        "optionsdescription": {}"001",
        "startelements": 1683811263[
        },
    {
        "change_id        "element_name": "Outage_123_AT_OPTESTSVlan1",
                "currentnode_name": null,
"Switch-2"
          "description": "Emergency outage",}
        "end": 1683825925],
        "frequencyend": "once12:12",
        "idfrequency": "ea7a3a94-f056-432f-91c5-9f39eee7c706daily",
        "id": "1f7ea042-0aaa-46a7-b34b-f9314952ee6f",   
		"nodes": {[
            "namethor": [
        ],
           "asgard", "options": {
            "nostats": 0
   "apc-ups"
            ]
        },
        "optionsstart": {},
        "start": 164691846311:11"
    }
 ]

GET of /v2/outages/<id> for Read

If your GET call provides an accept header, indicating application/json or , 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.

Successful Response

Unsuccessful Response

GET http://server/en/omk/admin/api/v2/outages/#ID

Ex. http://server/en/omk/admin/api/v2/outages/e17b6efa1f7ea042-a3da0aaa-428146a7-919cb34b-bef26b96ff80f9314952ee6f

Returns an outage.

Response:

{
        "change_id": "001",
        "current": "current"null,
        "description": "testing outage 1001",
        "elements": [
            {
                "element_name": "Vlan11Vlan1",
                "node_name": "AsgardSwitch-2"
            }
        ],
        "end": 1684763940"12:12",
        "frequency": "oncedaily",
        "id": "e17b6efa1f7ea042-a3da0aaa-428146a7-919cb34b-bef26b96ff80f9314952ee6f",
        "nodes": [],
        "Asgardoptions"
    ],
 : {
   "options": {
        "nostats": 0
        },
        "start": 1684072800"11:11"
}

POST of /v2/outages/ for Create

Create an Outage by sending a pay-load JSON object and this , which will create an Outage on your system and send an appropriate response.

Successful Response

Unsuccessful Response

Create Outage

POST  http://server/en/omk/admin/api/v2/outages

Payload example:

FromBefore opCharts 4.5.7 onwards8, ELEMENTonly OUTAGESNode outages are supported

{
    "change_id": "ticket #1234001",
    "descriptioncurrent": "Emergency outagecurrent",
    "description"elements: "testing :outage [1",
      "frequency": "once",
  {  "node_namenodes": ["Switch1","Switch-1111"],
    "options": {
        "element_namenostats" : "Vlan2"
    0
    },
    "start": "11-May-2023 23:21:03",
  {  "node_nameend": "Switch-2",
           "element_name" : "regex:^Vlan.*?$"15-May-2023 23:21:03" 
} 

############################################################################

From opCharts 4.5.8 onwards, Node Outages and Element Outages are supported

{
    "change_id": "ticket #1234",
    "description": "Emergency outage",
  }
  "elements" : ],[
    "start": "11-May-2023 23:21:03",
  {  "endnode_name": "15-May-2023 23:21:03"
}


----------------------------------------------------

{
    "change_id": "ticket #1234",
    "description": "Emergency outage",
	"nodes":["Switch3"], 
    "elements" : [
        {  "node_name": "Switch-1Switch-1",
           "element_name" : "Vlan2"
        },
        {  "node_name": "Switch-2",
           "element_name" : "regex:^Vlan.*?$"
        }
    ],
    "start": "11-May-2023 23:21:03",
    "end":       "element_name" : "Vlan2"
        },
        {  "node_name": "Switch-2",
           "element_name" : "regex:^Vlan.*?$"
        }
    ],
    "start": "11-May-2023 23:21:03",
    "end": "15-May-2023 23:21:03"
}







###############################################

Before opCharts 4.5.7 only Node outages are supported

{
    "change_id": "001",
    "current": "current",
    "description": "testing outage 1",
 "15-May-2023 23:21:03"
}

Return

Returns 200 if the outage was successfully created.

{
    "id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
    "success": 1
}

PUT of /v2/outages/ for Update

Update an Outage by sending a pay-load JSON object, which will update the Outage on your system and receive an appropriate response.

Successful Response

Unsuccessful Response

Update Outage

PUT http://server/en/omk/admin/api/v2/outages/

Returns 200 if the outage was successfully updated.

Payload example:

{
	"id" : XXXXXXXXXXXXXXXXXXXXXX,
    "change_id": "ticket #1234   "end": 1684763940,
    "frequency": "once",
    "nodesdescription":["Switch1","Switch-111"] "Emergency outage",
    "optionselements" : [
        {  "node_name": "Switch-1",
           "nostatselement_name" : 0
"Vlan222"
        },
        {  "startnode_name": 1684072800
}

Return

Returns 200 if the outage was successfully created.

{
    "id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
    "success": 1
}

PUT of /v2/outages/ for Update

Create an Outage by sending a pay-load JSON object and this will create an Outage on your system and receive an appropriate response.

Successful Response

...

HTTP Status

...

Body

...

"Switch-2",
           "element_name" : "regex:^Vlan.*?$"
        }
    ],
    "start": "11-May-2023 23:21:03",
    "end": "15-May-2023 23:21:03"
}

Return 

{
    "id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
    "success": 1
}

DELETE of /v2/outages/<id> for Delete

Delete an Outage by sending a request with the Outage on your system and receive an appropriate response.

Successful Response

Unsuccessful

...

Response

...

Delete Outage

PUT DELETE http://server/en/omk/admin/api/v2/outages/#ID0ea7644e-b6fa-4fa2-9b33-a86b79db21a4

Returns 200 if the outage was successfully updatedremoved.

Payload example:

{
	"id" : XXXXXXXXXXXXXXXXXXXXXX,
    "change_id": "ticket #1234",
    "description": "Emergency outage",
    "elements" : [
        {  "node_name": "Switch-1",
           "element_name" : "Vlan222"
        },
        {  "node_name": "Switch-2",
           "element_name" : "regex:^Vlan.*?$"
        }
    ],
    "start": "11-May-2023 23:21:03",
    "end": "15-May-2023 23:21:03"
}

Return 

{
    "id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
    "success": 1
}

DELETE of /v2/outages/<id> for Delete

Delete an Outage by sending a request with the Outage on your system and receive an appropriate response.

Successful Response

...

HTTP Status

...

Body

...

Unsuccessful Response

...

HTTP Status

...

Body

...

Description

...

Anchor
properties properties

Outages Properties

The following table lists theproperties of an Outage.

[ {
   "element_name": "Vlan2", 
   "node_name": "Switch-1" 
  }, 
  {
   "element_name": "iregex:^Vlan.*?$", 
   "node_name": "Switch-2" 
  } 
]

[ {
   "node_name": "Switch-1" 
  },
  {
   "element_name": "regex:^Vlan.*?$", 
   "node_name": "Switch-2" 
  } 
]

Limitations

API Endpoint

All requests are made under the following base URL:

  http[s]://server/omk/admin/v2/outages

Anchor
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 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. However, it 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 , and GigabitEthernet1/13.
  
  

  Code Block

  { "change_id": "ticket #1234", "description": "Planned 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" }

Delete Outage

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

...

id

...

A globally unique Outage ID

...

Insert any reference number if required in the change id field

...

date and time of outage start. See XYZ for description of allowed values.

...

List of elements from nodes for which Outages are defined.

IS THIS MANDATORY?

DOCUMENT REGEX OR SEE LINK

CAN I DO NODE REGEX?

HOW DO WE HANDLE OTHER TYPES OF ELEMENTS

 [ {

  "element_name": "Vlan2",
  "node_name": "Switch-1"
}, {

   "element_name": "regex:^Vlan.*?$",
   "node_name": "Switch-2"
} ]

 [ {

  "node_name": "Switch-1"
}, {

   "element_name": "regex:^Vlan.*?$",
   "node_name": "Switch-2"
} ]

...

optional key=values to adjust NMIS behaviour during an outage 

DOCUMENT THE KEYS AND VALUES

...

Limitations

API Endpoint

All requests are made under the following base URL:

...