Admin Outages API V2

When you schedule an outage or create a maintenance window for a device, you can suspend event alerts for that device during such outage period. NMIS enables you to easily manage the scheduled outages and maintenance windows on the NMIS portal; see the NMIS Outages documentation for more information. 

You can also manage Outages within the Administration console or the API.

The v2 API has added support for the Elements of the nodes (interface or other), such as, defining an outage on a single interface on a node; 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

Each resource has a consistent set of operations


Request Method

Operation

URL Example

ID Required

Notes

GETread list /server/omk/admin/v2/outagesnTo view a list of outages
GETread one /server/omk/admin/v2/outages/idyTo view the details of the specified Outage 
POSTcreate one/server/omk/admin/v2/outagesnTo create an outage for the given node or element
PUTupdate one/server/omk/admin/v2/outages/yTo edit an existing outage data
DELETEdelete one/server/omk/admin/v2/outages/idyTo delete an existing outage

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

Successful Response

HTTP Status

Body

Description

200Possibly empty JSON array of objectsEach array element is a JSON object with the raw properties of the Outages in question, described in known Outage properties.

Unsuccessful Response

HTTP Status

Body

Description

401 UnauthorizedJSON object with an error propertyYou are not authenticated.
403 ForbiddenJSON object with an error propertyYou are not authorized.

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

Returns a list of outages.

Response:

[  
    {
        "change_id": "005",
        "current": "current",
        "description": "005",
        "elements": [
            {
                "element_name": "lo",
                "node_name": "A.TEST"
            },
            {
                "element_name": "Vlan1",
                "node_name": "Switch-1"
            }
        ],
        "end": 1685541600,
        "frequency": "once",
        "id": "7a2011c7-2880-40ab-aa17-12a110cc1c23",
        "nodes": [],
        "options": {
            "nostats": 0
        },
        "start": 1685455200
    },
    {
        "change_id": "001",
        "current": null,
        "description": "001",
        "elements": [
            {
                "element_name": "Vlan1",
                "node_name": "Switch-2"
            }
        ],
        "end": "12:12",
        "frequency": "daily",
        "id": "1f7ea042-0aaa-46a7-b34b-f9314952ee6f",   
		"nodes": [
            "thor"
        ],
        "options": {
            "nostats": 0
        },
        "start": "11:11"
    }
 ]

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

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.

Successful Response

HTTP Status

Body

200JSON object with all known Outage properties.

Unsuccessful Response

HTTP Status

Body

Description

400 Bad RequestJSON object with an error property
401 UnauthorizedJSON object with an error propertyYou are not authenticated.
404 Not FoundJSON object with an error propertyYou are authenticated but not authorised to view this Outage.
404 Not FoundJSON object with an error property

The error property contains an explanation of what went wrong
with your request, e.g. if you request a non-existent Outage.

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:

{
        "change_id": "001",
        "current": null,
        "description": "001",
        "elements": [
            {
                "element_name": "Vlan1",
                "node_name": "Switch-2"
            }
        ],
        "end": "12:12",
        "frequency": "daily",
        "id": "1f7ea042-0aaa-46a7-b34b-f9314952ee6f",
        "nodes": [],
        "options": {
            "nostats": 0
        },
        "start": "11:11"
}

POST of /v2/outages/ for Create

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

Successful Response

HTTP Status

Body

Description
200 OKJSON object with success and id propertiesThe success property is set to 1 and only if the request was successful.
The id property is the new event's ID

Unsuccessful Response

HTTP Status

Body

Description

400 Bad RequestJSON object with an error propertyThe error property contains an explanation of what went wrong
with your request, e.g. if your payload is of wrong format to create an  Outage.
401 UnauthorizedJSON object with an error propertyYou are not authenticated.
404 Not FoundJSON object with an error propertyYou are authenticated but not authorised to create an Outage.



Create Outage

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

Payload example:

Before opCharts 4.5.8, only Node outages are supported

{
    "change_id": "001",
    "current": "current",
    "description": "testing outage 1",
    "frequency": "once",
    "nodes":["Switch1","Switch-111"],
    "options": {
        "nostats": 0
    },
    "start": "11-May-2023 23:21:03",
    "end": "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" : [
        {  "node_name": "Switch-1",
           "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"
}

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

HTTP Status

Body

Description
200JSON object with success and id propertiesThe success property is set to 1 and only if the request was successful.
The id property is the new event's ID

Unsuccessful Response

HTTP Status

Body

Description

400 Bad RequestJSON object with an error propertyThe error property contains an explanation of what went wrong
with your request, e.g. if your payload is of wrong format to edit an  Outage.
401 UnauthorizedJSON object with an error propertyYou are not authenticated.
404 Not FoundJSON object with an error propertyYou are authenticated but not authorised to create an Outage.



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",
    "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

Description
200JSON object with success The success property is set to 1 and only if the request was successful.

Unsuccessful Response

HTTP Status

Body

Description

400 Bad RequestJSON object with an error propertyThe error property contains an explanation of what went wrong
with your request, e.g. if id is missing or wrong format.
404 Not FoundJSON object with an error propertyIf the id does not exist.
401 UnauthorizedJSON object with an error propertyYou are not authenticated.
404 Not FoundJSON object with an error propertyYou are authenticated but not authorised to delete an Outage.

Delete Outage

DELETE http://server/en/omk/admin/api/v2/outages/0ea7644e-b6fa-4fa2-9b33-a86b79db21a4

Returns 200 if the outage was successfully removed.

Outages Properties

The following table lists the properties of an Outage.

Property

Description

Example

id

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
currentIf the outage is current or scheduled/future outage. IS THIS 'current' for scheduled or null for future.current
descriptionLong description of an Outage.This is a test outage
frequencyFrequency may be once, daily, weekly or monthly.once
start

Date and time when the outage shall start.

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 a description of the values allowed.

 2023-10-31T17:00:00+0000
endDate and time when the outage shall 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 a description of the values allowed. 
 31 May 2023 03:30 pm
nodesList of nodes for which Outages are defined. At least one nodes or an elements must be specified.[ 'Switch-1','Switch-2' ]
elements

List of elements of nodes for which Outages are defined. The element must be defined to match the one which may occur in the events.

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",
"node_name": "Switch-1"
},
{
   "element_name": "iregex:^Vlan.*?$",
   "node_name": "Switch-2"
}
]

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

optional key=values to adjust NMIS behaviour during an outage.

DOCUMENT THE KEYS AND VALUES

"Normal"

Limitations

API Endpoint

All requests are made under the following base URL:

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

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.

    {
        "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"
    }