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
GET	read list	/`server/omk/admin/v2/outages`	n	To view a list of outages
GET	read one	`/server/omk/admin/v2/outages/id`	y	To view the details of the specified Outage
POST	create one	/`server/omk/admin/v2/outages`	n	To create an outage for the given node or element
PUT	update one	/`server/omk/admin/v2/outages/`	y	To edit an existing outage data
DELETE	delete one	/`server/omk/admin/v2/outages/id`	y	To 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
200	Possibly empty JSON array of objects	Each 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 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.

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
200	JSON object with all known Outage properties.

Unsuccessful Response

HTTP Status	Body	Description
400 Bad Request	JSON object with an `error` property
401 Unauthorized	JSON object with an `error` property	You are not authenticated.
404 Not Found	JSON object with an `error` property	You are authenticated but not authorised to view this Outage.
404 Not Found	JSON 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 OK	JSON object with `success` and `id` properties	The 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 Request	JSON object with an `error` property	The `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 Unauthorized	JSON object with an `error` property	You are not authenticated.
404 Not Found	JSON object with an `error` property	You 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
200	JSON object with `success` and `id` properties	The 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 Request	JSON object with an `error` property	The `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 Unauthorized	JSON object with an `error` property	You are not authenticated.
404 Not Found	JSON object with an `error` property	You 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
200	JSON object with `success`

opCommon

Admin Outages API V2

Public API for Outages

Authentication

`GET` of `/v2/outages` for List

Successful Response

Unsuccessful Response

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

Successful Response

Unsuccessful Response

`POST` of `/v2/outages/` for Create

Successful Response

Unsuccessful Response

Create Outage

`PUT` of `/v2/outages/` for Update

Successful Response

Unsuccessful Response

Update Outage

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

Successful Response

Admin Outages API V2

Public API for Outages

Authentication

GET of /v2/outages for List

Successful Response

Unsuccessful Response

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

Successful Response

Unsuccessful Response

POST of /v2/outages/ for Create

Successful Response

Unsuccessful Response

Create Outage

PUT of /v2/outages/ for Update

Successful Response

Unsuccessful Response

Update Outage

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

Successful Response

`GET` of `/v2/outages` for List

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

`POST` of `/v2/outages/` for Create

`PUT` of `/v2/outages/` for Update

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