Alerting 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 an OmniCenter passive service check. Service checks are used to monitor applications and services running on a managed device.

The OmniCenter Alerting API allows external APIs to retrieve or set the status information on a service check assigned to a device in OmniCenter. This allows an external API to read the status of a service check and take its own actions, or update the status of a service check in OmniCenter. Updating a check’s status will cause OmniCenter to take its own appropriate actions (such as sending an alert notification for a critical state).

If you want OmniCenter to send alerts based on status updates received from an external API, it’s recommended that you add a “Generic Passive Service Check” to the devices in question specifically for this purpose. If you try to make a status update on a check that doesn’t exist, OmniCenter will create a new passive service check on the device for you anyway—but, it’s still better to create the check yourself so that you have more control. (Remember to include a unique description for the service check in its configuration, as you will be referring to it in the API call.) It’s highly recommended that you add this check through the use of device templates. Add the check to a device template and assign it to the device type you want to monitor, or create a new device subtype and assign the template to that.

This resource offers the following endpoints:

  • Service Check Status

Resource URL

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

Endpoints

Service Check Status

GET or POST
/passive_alert_api.php
Either retrieves or sets the status information on a passive service check assigned to a device.

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
String/Required
Must be the first parameter. Two values currently supported:

  • getInfo to read service check status info from an existing passive service check.
  • update to write service check status info to an existing passive service check, or create a new check if it does not already exist. Note: When checks are created in this manner they are always created in an OK state. You will then have to call the API again in order to change the state of the check to any other state.

device_info
String/Required
The NAME, IP_ADDRESS, or DEVICE_INDEX of the device that contains the passive service check to be updated. If this device does not exist in OmniCenter, the OmniCenter API system will return an error.

check_name
String/Required
The value in the description field of the specified passive service check. Should be URL encoded if special characters are defined. Must be unique on this device (i.e., only one service check on each device can have a particular description). If the method is update and the specified service check does not exist, it will be created. (See note in method about creating passive service checks this way.)

state
String/Required for method update
The state to set the passive service check to. Must be one of OK, WARNING, CRITICAL, UNKNOWN.

check_status_info
String/Required for method update
Any notes associated with this status change. These notes will be logged in the alert log and are typically also sent out with the alert notifications. Limited to 256 characters of plain text. Note: Any text after a pipe character ( | ) will be ignored as “debug output.” These notes are returned as detail in the JSON formatted response output.

Request Examples

Read Status Info Using GET with API Authentication Disabled

http://38.2.11.62/api/passive_alert_api.php?method=getInfo&device_info=TEST-PC&check_name=ping

Read Status Info Using GET with API Authentication Enabled

http://38.2.11.62/api/passive_alert_api.php?method=getInfo&device_info=TEST-PC&check_name=ping&pwd=PassWord1

Update Status Info Using GET with API Authentication Disabled

http://38.2.11.62/api/passive_alert_api.php?method=update&device_info=TEST-PC&check_name=ping&state=critical&check_status_info=API%20status%20change%20test

Update Status Info Using GET with API Authentication Enabled

http://38.2.11.62/api/passive_alert_api.php?method=update&device_info=TEST-PC&check_name=ping&state=critical&check_status_info=API%20status%20change%20test&pwd=PassWord1

Response

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

Response Examples

Read

{"result":"completed","device":"TEST-PC","service description":"PING","service status":"OK","detail":"Ping OK: Packet Loss 0% RTA = 0.380 ms"}

Update

{"result":"completed","device":"TEST-PC","service description":"PING","service status":"CRITICAL","detail":"API status change test."}

Response Schema

Output Type Description
result string completed indicates the request was successfully processed by OmniCenter.
error indicates the request encountered an error during processing.
A description pair indicating the issue will follow this pair, in place of the remaining data.
device string The name of the device containing the affected passive service check, as it is listed in OmniCenter.
service description string The value in the description field of the passive service check being read, updated or created.
service status string The state of the passive service check at the time of being read or updated.
detail string Any notes associated with the service status above.
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