Incidents API

OmniCenter’s API system must be enabled to use this API. See, How to Enable OmniCenter API Access.

Calls to this API are made using HTTP/HTTPS and are sent as key/value pairs in a GET or POST request.

Security

Netreo recommends always using POST for API calls if possible. If security is a concern we recommend the use of HTTPS and POST requests.

Resource

The resource accessed by this API is the list of currently “active” incidents in OmniCenter.

This resource offers the following endpoints:

  • Active Incident List

Resource URL

{your.omnicenter.ip.or.name}/api

Endpoints

Active Incident List

GET or POST
/incident_api.php
Retrieves the list of active incidents and their related data.

Parameters

The parameters for this endpoint can be included as query string parameters in a GET request, or as request body parameters in a POST request.

pwd
String/Required if authentication is enabled.
The API key set in OmniCenter’s API Administration. Case-sensitive.

method_request
String/Required

  • getincidents retrieves a list of all currently active incidents (i.e. incidents that are not closed).
  • getincidentdetail retrieves complete detailed information about a specific incident along with detailed information on the device that the primary alarm in the incident is related to, if any.

incident_id
String/Required if using getincidentdetail
The unique ID of the incident for which you wish to retrieve details. Only used when using getincidentdetail for the method request above.

Request Examples

Retrieving all active incidents using GET with API authentication enabled

http://38.2.11.62/api/incident_api.php?method_request=getincidents&pwd=PassWord1234

Retrieving detailed information on a specific incident using GET with API authentication enabled

http://38.2.11.62/api/incident_api.php?method_request=getincidentdetail&incident_id=CustomerCorp-1325&pwd=PassWord1234

Response

A successful or unsuccessful call to this API will return a standard JSON object.

Response Examples

Note: The output will be returned as standard JSON without indentation or line breaks. It is formatted here to make the examples easier to read.

Active Incident List

{
    "result":"completed",
    "active_incidents":
     [
        {
            "title":"Application Service for Support",
            "incident_state":"OPEN",
            "incident_id":"sw_omni_9_1-1156",
            "open_time":"2016-07-20T14:55:32"
        },
        {
            "title":"Service EIGRP on Router1",
            "incident_state":"OPEN",
            "incident_id":"CustomerCorp-1325",
            "open_time":"2016-07-22T09:26:33",
            "name":"Router1",
            "device_category":"Core Routers",
            "device_site":"netreo_hq",
            "device_note":"This is an arbitrary note for router1."
        },
        {
            "title":"Service for Device Polling Status on Lync2013_netreo-test_info",
            "incident_state":"OPEN",
            "incident_id":"CustomerCorp-2232",
            "open_time":"2016-08-01T12:16:23",
            "name":"Lync2013_netreo-test_info",
            "device_category":"Windows Servers",
            "device_site":"netreo_hq",
            "device_note":""
        }
     ]
}

Single Incident

 {
    "result":"completed",
    "incident":
     {
        "title":"Service EIGRP on Router1",
        "incident_state":"OPEN",
        "incident_id":"sw_omni_9_1-1325",
        "name":"Router1",
        "device_category":"Core Routers",
        "device_site":"netreo1",
        "related_strategic_groups":
            [
                "Infrastructure"
            ],
        "device_note":"This is an arbitrary note for router1.",
        "device_documentation":
            [
              "documentation":
                [
                     {
                        "name":"Router",
                        "value":"1"
                     },
                     {
                        "name":"Where",
                        "value":"Backroom"
                     },
                 ],
              "reference_contact":
                 [
                      {
                         "Contact Address":"8717 Research Dr",
                         "Contact City":"Irvine",
                         "Contact Country":"US",
                         "Contact Email":"[email protected]",
                         "Contact Name":"Info",
                         "Contact Number":"949-769-5700",
                         "Contact State":"CA",
                         "Contact Zip":"92708"
                     },
                     {
                         "Contact Address":"8717 Research Dr",
                         "Contact City":"Irvine",
                         "Contact Country":"United States",
                         "Contact Email":"[email protected]",
                         "Contact Name":"Engineering",
                         "Contact Number":"9497695700",
                         "Contact State":"CA",
                         "Contact Zip":"92708"
                    }
                 ],
            ],
        "primary_alarm_state":"OPEN",
        "incident_open_time":"2016-07-22T09:26:33",
        "acknowledged":0,
        "ack_time":"",
        "ack_user":"",
        "ack_comment":"",
        "alert_type":"Service",
        "detail":
            {
                "primary_alarm_log":
                    [
                        {
                            "state":"UNKNOWN",
                            "type":"Service",
                            "name":"Router1",
                            "output":"EIGRP Neighbors not available",
                            "time":"2016-07-22T09:26:23"
                        }
                    ],
                "relatedalarms":
                    [],
                "incident_log":
                    [
                        {
                            "state":"OPEN",
                            "time":"2016-07-22T09:26:33",
                            "username":"system",
                            "comment":"Initialized state to OPEN"
                         }
                    ]
            }
    }
 }

Response Schema

Active Incident List

Output Type Description
result string Returns "completed" if the call was successfully received by OmniCenter.
Returns "error" if the call encountered an error. A description pair indicating the issue will follow.
active_incidents array[object] Array of active incidents.
title string The title of an incident as it appears in OmniCenter.
incident_state string The above incident’s current “incident state.”
incident_id string The unique ID assigned to the above incident.
open_time string The date and time the respective incident was opened.
name string The name of the managed device associated with the primary alarm for the above incident.
device_category string The category (device group) the above device belongs to.
device_site string The site (device group) the above device belongs to.
device_note string The contents of the “Device Note” field from the “Main” device administration page, if any, for the above device.

Single Incident

Output Type Description
result string Returns "completed" if the call was successfully received by OmniCenter.
Returns "error" if the call encountered an error. A description pair indicating the issue will follow.
incident object Object containing all data for this incident.
title string The title of this incident as it appears in OmniCenter.
incident_state string The “incident state” of this incident, at the time of retrieval.
incident_id string The unique ID assigned to this incident by OmniCenter.
name string The name of the managed device associated with the primary alarm for this incident.
device_category string The category (device group) this device belongs to.
device_site string The site (device group) this device belongs to.
related_strategic_groups array[string] The strategic groups (device group) this device belongs to, if any.
device_note string The contents of the “Device Note” field from the “Main” device administration page, if any, for this device.
device_documentation array[object] Array containing user-created device attributes and reference contacts, if any, for this device.
documentation array[object] Array containing data, if any, representing the “Device Attributes” section of the Documentation device administration page for this device.
name string The user created name for this device attribute.
value string The user assigned value for this device attribute.
reference_contact array[object] Array containing data, if any, representing the “Reference Contacts” section of the Documentation device administration page for this device.
Contact Address string The respective user entered value for this contact.
Contact City string The respective user entered value for this contact.
Contact Country string The respective user entered value for this contact.
Contact Email string The respective user entered value for this contact.
Contact Name string The respective user entered value for this contact.
Contact Number string The respective user entered value for this contact.
Contact State string The respective user entered value for this contact.
Contact Zip string The respective user entered value for this contact.
primary_alarm_state string The state of the primary alarm of this incident at the time of retrieval.
incident_open_time string The date and time this incident was opened.
acknowledged number Code indicating if this incident has been acknowledged. 0 indicates incident has not been acknowledged, 1 indicates incident has been acknowledged.
ack_time string The date and time this incident was acknowledged.
ack_user string The OmniCenter user who acknowledged this incident.
ack_comment string The user-entered comment associated with incident acknowledgement.
alert_type string The type of alarm that caused this incident, as listed in Alert Template Administration.
detail string Additional data associated with this incident.
primary_alarm_log array[object] Array of data representing logged state changes for the primary alarm.
state string The state of the check that caused this alarm at time (see below).
type string The type of OmniCenter check that caused this alarm.
name string The name of the managed device the above check is associated with.
output string The response code or other output returned by the check at time (see below).
time string The date and time that this alarm changed to this state.
relatedalarms array[object] Array of data representing logged state changes for related alarms (same as primary alarm, above).
incident_log array[object] Array of data representing OmniCenter incident log entries for this incident.
state string The incident state of the incident at time (see below).
time string The date and time of this log entry.
username string The OmniCenter username associated with this log entry.
comment string The comment associated with this log entry.
Updated on July 1, 2019

Was this article helpful?

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support

Leave a Reply