...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
If you have a maintenance window or a scheduled outage When you schedule an outage or create a maintenance window 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 the 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 below using these endpoints - at http[s]://server/en/omk/admin/api/v2/outages
using the endpoints given below.
API Routes
Note |
---|
Each resource |
...
has a consistent set of operations |
Request Method | Operation | URL Example | id requiredID Required | Notes |
---|---|---|---|---|
GET | read list | /server/omk/admin/v2/outages | n | Returns To view a list of Outages.outages |
GET | read one | /server/omk/admin/v2/outages/id | y | Returns To view the details of one Outage .the specified Outage |
POST | create one | /server/omk/admin/v2/outages | n | Create To create an Outage outage for the given node or element |
PUT | update one | /server/omk/admin/v2/outages/ | y | Edit To edit an already existing outage data |
DELETE | delete one | /server/omk/admin/v2/outages/id | y | Delete 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, 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, 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:
Code Block |
---|
[ { "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", }, "Switch-1start": 1685455200 }, { ] }"change_id": "001", "optionscurrent": {}null, "startdescription": 1683811263"001", }, "elements": [ { "change_id": "Outage_123_AT_OPTESTS", { "current": null, "descriptionelement_name": "Emergency outageVlan1", "end": 1683825925, "frequencynode_name": "onceSwitch-2", "id": "ea7a3a94-f056-432f-91c5-9f39eee7c706", } "nodes": { ], "nameend": ["12:12", "asgard"frequency": "daily", "id": "apc-ups" 1f7ea042-0aaa-46a7-b34b-f9314952ee6f", "nodes": [ ] "thor" }, ], "options": { "nostats": 0 }, "start": 1646918463"11: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
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 |
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:
Code Block |
---|
{ "change_id": "001", "current": "current"null, "description": "001"testing, outage 1", "elements": [ { "element_name": "Vlan11Vlan1", "node_name": "Asgard"Switch-2" } ], "end": 1684763940,"12:12", "frequency": "oncedaily", "id": "e17b6efa1f7ea042-a3da0aaa-428146a7-919cb34b-bef26b96ff80f9314952ee6f", "nodes": [], "Asgardoptions": { ], "optionsnostats": {0 "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
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 wrongwith 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:
Code Block |
---|
Before From opCharts 4.5.78, onwards,only ELEMENTNode OUTAGESoutages 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 }, { "node_namestart": "Switch-211-May-2023 23:21:03", "element_name" "end": "regex:^Vlan.*?$15-May-2023 23:21:03" } ############################################################################ From } ],opCharts 4.5.8 onwards, Node Outages and Element Outages are supported { "startchange_id": "11-May-2023 23:21:03ticket #1234", "enddescription": "15-May-2023 23:21:03" } ---------------------------------------------------- { "change_id": "ticket #1234Emergency outage", "elements" : [ { "node_name": "Switch-1", "description": "Emergency outage", "nodes":["Switch3"], "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" } ############################################### Before opCharts 4.5.7 only Node outages are supported { "change_id": "001", "current": "current", "description": "testing outage 1", "end": 1684763940, "frequency": "once", "nodes":["Switch1","Switch-111"], "options": { "nostats": 0 }, "start": 1684072800 } |
Return
Returns 200 if the outage was successfully created.
Code Block |
---|
{
"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
...
Unsuccessful Response
...
HTTP Status
...
Body
...
Description
...
Update Outage
PUT http://server/en/omk/admin/api/v2/outages/
Returns 200 if the outage was successfully updated.
Payload example:
Code Block |
---|
{
"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
Code Block |
---|
{
"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
...
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:
Code Block |
---|
http[s]://server/omk/admin/v2/outages
|
Return
Returns 200 if the outage was successfully created.
Code Block |
---|
{
"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 wrongwith 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:
Code Block |
---|
{
"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
Code Block |
---|
{
"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 | The success property is set to 1 and only if the request was successful. |
Unsuccessful Response
HTTP Status | Body | Description |
---|---|---|
400 Bad Request | JSON object with an error property | The error property contains an explanation of what went wrongwith your request, e.g. if id is missing or wrong format. |
404 Not Found | JSON object with an error property | If the id does not exist. |
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 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.
Anchor | ||||
---|---|---|---|---|
|
The following table lists theproperties of an Outage.
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 | Frequency 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. | 2023-10-31T17:00:00+0000 |
end | Date 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 |
nodes | List 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.
| [ { |
options |
DOCUMENT THE KEYS AND VALUES | "Normal" |
Limitations
API Endpoint
All requests are made under the following base URL:
Code Block |
---|
http[s]://server/omk/admin/v2/outages
|
Anchor elements elements
Element Outages
elements | |
elements |
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" }