Outages API - V3

If you have a maintenance window or a scheduled outage for a device then you will likely want to suspend alerting for that device during that period.

NMIS has supported this for a long time, please refer to the NMIS Outages documentation for further information.

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

Public API for Outages "http[s]://server/en/omk/admin/api/v3/outages"

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

API Routes

Each resource has a consistent set of operations

...

Request Method

...

Operation

...

URL Example

...

id required

...

Notes

...

Authentication

All these methods require authentication.

POST http://server/en/omk/admin/login

Form data:

username
password

Get Outages

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

Returns a list of outages.

Response:

...

Outages API - V3

If you have a maintenance window or a scheduled outage for a device then you will likely want to suspend alerting for that device during that period.

NMIS has supported this for a long time, please refer to the NMIS Outages documentation for further information.

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

Public API for Outages "http[s]://server/en/omk/admin/api/v3/outages"

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

API Routes

Each resource has a consistent set of operations

Request Method	Operation	URL Example	id required	Notes
GET	read list	/`server/omk/admin/v3/outages`	n	Returns a list of Enterprise Services.
GET	read one	`/server/omk/admin/v3/outages/id`	y	Returns the details of one Enterprise Service.
POST	create one	/`server/omk/admin/v3/outages`	n	Create an Outage for given node or element
PUT	update one	/`server/omk/admin/v3/outages/id`	y	Edit an already existing outage data
DELETE	delete one	/`server/omk/admin/v3/outages/id`	y	Delete an existing outage

Authentication

All these methods require authentication.

POST http://server/en/omk/admin/login

Form data:

username
password

Get Outages

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

Returns a list of outages.

Response:

Code Block

[
    {
        "change_id": "ticket #1234",
        "current": "current",
        "description": "Emergency outage",
        "element": [
            {
                "currentelement_name": "currentVlan2",
           "description     "node_name": "Emergency outage","Switch-1"
           "element": [ },
            {
                "element_name": "Vlan2regex:^Vlan.*?$",
                "node_name": "Switch-12"
            },
        ],
   {        "end": 1684156863,
        "element_namefrequency": "regex:^Vlan.*?$once",
        "id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
        "node_namenodes": "Switch-2"{
            }"name": [
       ],         "end": 1684156863Switch-2",
        "frequency": "once",         "id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",Switch-1"
        "nodes": {   ]
        },
"name": [       "options": {},
        "Switch-2start",: 1683811263
    },
    {
        "Switch-1"
change_id": "Outage_123_AT_OPTESTS",
        "current": null,
 ]       "description": "Emergency }outage",
        "optionsend": {}1683825925,
        "startfrequency": 1683811263"once",
    },     {"id": "ea7a3a94-f056-432f-91c5-9f39eee7c706",
        "change_idnodes": "Outage_123_AT_OPTESTS", {
            "currentname": null, [
               "description": "Emergency outageasgard",

       "end": 1683825925,         "frequencyapc-ups":
"once",         "id": "ea7a3a94-f056-432f-91c5-9f39eee7c706",  ]
      "nodes": {    },
        "nameoptions": [{},
                "asgard",
"start": 1646918463
               "apc-ups"
            ]
        },
        "options": {},
        "start": 1646918463
    }
]

GET of /v3/outages for List

GET http[s]://server/en/omk/admin/api/v3/outages

...

}
]

GET of /v3/outages for List

GET http[s]://server/en/omk/admin/api/v3/outages

If your GET call provides an Accept header indicating JSON, or if you use a .json suffix, eg /v3/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.

...

If your GET call provides an accept header indicating application/json or if you use /en/omk/admin/api/v3/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/v3/outages/#ID

Ex. http://server/en/omk/admin/api/v3/outages/0ea7644e-b6fa-4fa2-9b33-a86b79db21a4

Returns an outage.

Response:

Code Block

{
    "change_id": "ticket #1234",
    "current": "current",
    "description": "Emergency outage",
    "element": [
        {
            "element_name": "Vlan2",
            "node_name": "Switch-1"
        },
        {
            "element_name": "regex:^Vlan.*?$",
            "node_name": "Switch-2"
        }
    ],
    "end": 1684156863,
    "frequency": "once",
    "id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
    "nodes": {},
    "options": {},
    "start": 1683811263
}

...

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 and end

...

[ {

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

...

Create Outage
POST http://server/en/omk/admin/api/v3/outages

Returns 201 if the outage was successfully created.

Payload example:

Code Block

{
    "change_id": "ticket #1234",
    "description": "Emergency outage",
    "nodes": ["Switch-2","Switch-1"],
    "elements" : [
        {  "node_name": "Switch-1",
           "element_name" : "Vlan2"
        },
        {  "node_name": "Switch-2",
           "element_name" : "regex:^Vlan.*?$"

...

Limitations

API Endpoint

All requests are made under the following base URL:

Code Block
http[s]://server/omk/admin/v3/outages

...

Code Block


GET HTTP://server/omk/opCharts/v2/enterprise_services/63fdd07e0454aa367e368b0b.json
 
************* OUTPUT ****************  
{
    description: "This is a test Enterprise Service
        }
    ],
    "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 }

Update Outage

PUT http://server/en/omk/admin/api/v3/outages/#ID

Returns 200 if the outage was successfully updated.

Payload example:

Code Block

{
    "change_id": "ticket #1234",
    "description": "Emergency outage",
    frequency"nodes": "30"["Switch-2","Switch-1"],
    id: "63fdd07e0454aa367e368b0belements", : [
   interface_state     {  "node_name": "NormalSwitch-1",
     interface_status: 100,     interface_status_level"element_name" : "NormalVlan222",
       interfaces_reachable: null},
    interfaces_unreachable: 0,   {  last"node_updatedname": 1682489067"Switch-2",
    name: "John Test",     node"element_name" : "john_test_ES",regex:^Vlan.*?$"
      node_state: "Down", }
   node_status: 98.3333333333333 ],
    node_status_level"start": "Minor11-May-2023 23:21:03",
    nodes_degraded: 1,"end": "15-May-2023 23:21:03"
}

Return

Code Block

{
    nodes_down: 1"id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
    nodes_total: 3,
    nodes_up"success": 1,
    overall_status: "Down",
    service_state: "Down",
    service_status: 0,
    service_status_level: "Fatal",
    services_degraded: 0,
    services_reachable: 0,
    services_unreachable: 1
}


################################## List ##################################

GET HTTP://server/omk/opCharts/v2/enterprise_services.json

************* OUTPUT ****************


[ 
  {
    description: "Show core network",
    frequency: "60",
    id: "63f6fda90454aa0265333e61",
    interface_state: "Normal",
    interface_status: 100,
    interface_status_level: "Normal",
    interfaces_reachable: null,
    interfaces_unreachable: 0,
    last_updated: 1682570689,
    name: "Core Network",
    node_name: "core_network_es",
    node_state: "Normal",
    node_status: 96.6666666666667,
    node_status_level: "Minor",
    nodes_degraded: 1,
    nodes_down: 0,
    nodes_total: 1,
    nodes_up: 0,
    overall_status: "Degraded",
    service_state: "Normal",
    service_status: 100,
    service_status_level: "Normal",
    services_degraded: 0,
    services_reachable: 1,
    services_unreachable: 0
  },
  {
    description: "This is a test Enterprise Service",
    frequency: "30",
    id: "63fdd07e0454aa367e368b0b",
    interface_state: "Normal",
    interface_status: 100,
    interface_status_level: "Normal",
    interfaces_reachable: null,
    interfaces_unreachable: 0,
    last_updated: 1682489067,
    name: "John Test",
    node_name: "john_test_ES",
    node_state: "Down",
    node_status: 98.3333333333333,
    node_status_level: "Minor",
    nodes_degraded: 1,
    nodes_down: 1,
    nodes_total: 3,
    nodes_up: 1,
    overall_status: "Down",
    service_state: "Down",
    service_status: 0,
    service_status_level: "Fatal",
    services_degraded: 0,
    services_reachable: 0,
    services_unreachable: 1
  }
]
}

Delete Outage

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

Returns 200 if the outage was successfully removed.

Anchor
properties
properties
Outages Properties

The following tables represents theproperties of an Outage.

Property	Description	Example
`id`	A globally unique Outage ID	"63576103ad794974594a1f11"
`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	"current/null"
`description`	Long description of an Outage	"This is a test outage"
`frequency`		one of 'once', 'daily', 'weekly' or 'monthly'

`start`	date and time of outage start and end	e.g. 2017-10-31T03:04:26+0000
`end`	date and time of outage start and end	e.g. 2017-10-31T03:04:26+0000

`nodes`	List of nodes for which Outages is defined	[ 'Switch-1','Switch-2' ]
`element`	List of elements from nodes for which Outages are defined.	[ { "element_name": "Vlan2", "node_name": "Switch-1" }, { "element_name": "regex:^Vlan.*?$", "node_name": "Switch-2" } ]
`options`	optional key=values to adjust NMIS' behaviour during an outageo	"Normal"

Limitations

API Endpoint

All requests are made under the following base URL:

Code Block
http[s]://server/omk/admin/v3/outages

Versions Compared

Old Version 7

New Version 8

Key

Outages API - V3

Public API for Outages "http[s]://server/en/omk/admin/api/v3/outages"

Authentication

Get Outages

Outages API - V3

Public API for Outages "http[s]://server/en/omk/admin/api/v3/outages"

Authentication

Get Outages

GET of /v3/outages for List

GET of /v3/outages for List

Create Outage
POST http://server/en/omk/admin/api/v3/outages

Limitations

API Endpoint

Update Outage

Return

Delete Outage

Anchor
properties
properties
Outages Properties

Limitations

API Endpoint

Page Comparison

Versions Compared

Old Version 7

New Version 8

Key

Public API for Outages "http[s]://server/en/omk/admin/api/v3/outages"

Authentication

Get Outages

Outages API - V3

Public API for Outages "http[s]://server/en/omk/admin/api/v3/outages"

Authentication

Get Outages

GET of /v3/outages for List

GET of /v3/outages for List

Create OutagePOST http://server/en/omk/admin/api/v3/outages

Limitations

API Endpoint

Update Outage

Return

Delete Outage

AnchorpropertiespropertiesOutages Properties

Limitations

API Endpoint

Create Outage
POST http://server/en/omk/admin/api/v3/outages

Anchor
properties
properties
Outages Properties