5.0 Event APIs

5.0 Event APIs

5.1 Query Events

Retrieve events by query

5.1.1 Method: GET

GET /api/events?query=(query criteria see below)

5.1.2 Method: GET with event ids

GET /api/events/101,204,307

5.1.3 HTTP Query and Path Parameters

Note: **Query and eventIds are mutually exclusive. Both cannot be provided, but one or the other is required.

5.1.4 HTTP Headers

5.1.5 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

5.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query on two fields, and sort by report date
   GET /api/events?query=(appType='NAGIOS' and service=’http_alive’ and reportDate > '2013-06-01') order by reportDate
2. query on two attributes and order by none-queried field
   GET /api/events?query=device = '172.28.113.156' and severity = 'CRITICAL' order by operationStatus
3. Paging parameters first and count ...
   GET /api/events?query=service='http_alive'&first=20&count=10
4. query on all text messages starting with a prefix using LIKE operator
   GET /api/events?query=message like 'TCP OK%'
5. query on a property and field using LIKE operator
   GET /api/events?query=(property.SubComponent like 'localhost%' and property.ErrorType = 'SERVICE ALERT')
6. query on the messsage Count greater than 2 messages
   GET /api/events?query=count > 2
7. query on a not null field
   GET /api/events?query=appType is not null
8. Query using appType and last insert date between a date range
   GET /api/events?query=(appType='NAGIOS' and service='http_alive'
   and lastInsertDate between '2013-02-01' and '2013-04-01')
9. Query with a property greater than a threshold, and use a between range query on report date
   GET /api/events?query=(property.ExecutionTime > 800
   and (reportDate between '2013-02-01' and '2013-04-01'))
10. Query with a property greater than a threshold, and use a between range query on report date
    GET /api/events?query=(property.ExecutionTime > 800)
11. Range query using IN operator
    GET /api/events?query=host in ('qa-load-xp-1','qa-sles-11-64','do-win7-1')
12. Query on hostgroup using IN operator
    GET /api/events?query=hostgroup in ('IT','HG1')
13. Query by category
    GET /api/events?query=category = 'SG1'
14. Query on service group using IN operator
    GET /api/events?query=(serviceGroup in ('web-svr','SG1'))
15. Query on service group and host group using IN operator
    GET /api/events?query=(serviceGroup in ('web-svr','SG1') and hostgroup in ('IT','HG1'))
16. Retrieve a single event by event id
    GET /api/events?104
17. Retrieve a list of comma-separated events by id
    GET /api/events?104,207,306,494,507

Example Query Results in XML

Events are always wrapped in an <events> collection element. Here is an example of the result of a query finding two events. Properties are always wrapped in a <properties> collection element.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<events>
  <event id="5" device="127.0.0.1" host="localhost" service="local_cpu_perl"
    operationStatus="ACCEPTED"
    monitorStatus="OK" severity="OK" applicationSeverity="OK"
    component="OK"
    priority="Lowest Priority in a scale from 1 -10" typeRule="UNDEFINED"
    textMessage="OK - total %CPU for process perl : 4.1"
    firstInsertDate="2013-05-17T07:46:12-07:00"
    lastInsertDate="2013-05-17T07:46:12-07:00"
    reportDate="2013-05-17T07:46:34.057-07:00"
    msgCount="1" appType="NAGIOS">
    <properties>
      <property name="ErrorType" value="SERVICE ALERT"/>
      <property name="SubComponent" value="localhost:local_cpu_perl"/>
    </properties>
  </event>
</events>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Shallow Distinct Response Data - XML - JSON

5.2 Create or Update Events

Creates a batch (1..n) of new events in foundation database. Events can be posted with or without a consolidation name. It is recommended to use consolidation names when events are often repeated for a device.

If one or more Event creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Event creation/update operation is returned back in the resultset described below with a status of success or failure.

5.2.1 Method: POST

POST /api/events

5.2.2 HTTP Headers

5.2.3 Required Post Data Attributes

5.2.4 Optional Post Data Attributes

5.2.5 HTTP Status Codes

200 - Events were created or updated successfully
500 - An internal server error occurred

5.2.6 Example Response

<results count='3' success='2' failure='1'>
  <result status='failure' message='Bad consolidation name provideds' entity='234' />
  <result status='success' entity='939'
    location='http://localhost/monitor/api/events/939' />
  <result status='success' entity='1024'
    location='http://localhost/monitor/api/hosts/1024' />
</results>

5.2.7 Example Post Data

The post data should be formatted like in either XML or JSON:

{ "events": [
    {
        "host": "localhost",
        "monitorServer": "localhost",
        "service": "local_load",
        "appType": "NAGIOS",
        "textMessage": "This is a serious Nagios Message on Device 127.0.0.1",
        "monitorStatus": "UP",
        "severity": "SERIOUS",
        "consolidationName": "NAGIOSEVENT",
        "device": "127.0.0.1",
        "reportDate": "2013-06-02T10:55:32.943",
        "properties": {
            "Comments": "Additional comments",
            "Latency": "125.0"
        }
    }
]
}

More Post Data Examples: XML - JSON

5.3 Acknowledging Events

Acknowledge an event or set of events for either a given host, or for a host and service combination. Optionally, the ackowedgedBy and acknowledgeComment can be set on all events matching the host or host + service criteria. Additionally, the operationStatus for the updated events will be set to ACKNOWLEDGED. This API receives its post data in batch (always 1..n objects).

5.3.1 Method: POST

POST /api/events/ack

5.3.2 HTTP Headers

5.3.3 Required Post Data Attributes

5.3.4 HTTP Status Codes

200 - Events were acknowledged successfully
500 - An internal server error occurred

5.3.5 Example Post Data

The post data should be formatted in XML or JSON:

<acks>
  <ack
       appType="VEMA"
       hostName="STOR-datastore1"
       serviceDescription="summary.freeSpace"
       acknowledgedBy="cloudHub"
       acknowledgeComment="acknowledged ok service by cloudhub"
     />
/acks>

{ "acks" : [
       {
	"appType": "VEMA",
	"hostName": "STOR-datastore1",
	"serviceDescription": "summary.freeSpace",
	"acknowledgedBy": "cloudHub",
	"acknowledgeComment" : "acknowledged ok service by cloudhub"
       }
   ]
}

5.3.6 Example Response

{
  "successful" : 1,
  "failed" : 0,
  "entityType" : "Ack",
  "operation" : "Update",
  "warning" : 0,
  "results" : [ {
    "entity" : "STOR-datastore1 - summary.freeSpace",
    "status" : "success",
    "message" : "ack ' STOR-datastore1 - summary.freeSpace"
  } ],
  "count" : 1
}

5.4 UnAcknowledging Events

UnAcknowledge an event or set of events for either a given host, or for a host and service combination. Additionally, the operationStatus for the updated events will be reset to OPEN. This API receives its post data in batch (always 1..n objects).

5.4.1 Method: POST

POST /api/events/unack

5.4.2 HTTP Headers

5.4.3 Required Post Data Attributes

5.4.4 HTTP Status Codes

200 - Events were unacknowledged successfully
500 - An internal server error occurred

5.4.5 Example Post Data

The post data should be formatted in XML or JSON:

<unacks>
  <unack
       appType="VEMA"
       hostName="STOR-datastore1"
       serviceDescription="summary.freeSpace"
   />
</unacks>

{ "unacks" : [
     {
	"appType": "VEMA",
	"hostName": "STOR-datastore1",
	"serviceDescription": "summary.freeSpace"
     }
   ]
}

5.4.6 Example Response

{
  "successful" : 1,
  "failed" : 0,
  "entityType" : "UnAck",
  "operation" : "Update",
  "warning" : 0,
  "results" : [ {
    "entity" : "STOR-datastore1 - summary.freeSpace",
    "status" : "success",
    "message" : "unack ' STOR-datastore1 - summary.freeSpace"
  } ],
  "count" : 1
}

5.5 Update Event Property

Updates a batch (1..n) of existing events by primary key (ID) in foundation database with dynamic properties. Note this API only supports updating dynamic properties, not first-class field attributes.

5.5.1 Method: PUT

PUT /api/events

5.5.2 HTTP Headers

See Appendix A for examples of usage with Curl
   Post Data Example: XML - JSON

5.5.3 Required PUT Data

5.5.4 XML PUT Data Example

PUT /api/events/

5.5.5 HTTP Status Codes

200 - Events were created or updated successfully
500 - An internal server error occurred

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<events>
  <event id="5">
    <properties>
      <property name="AcknowledgeComment" value="Received and acknowledged sir"></property>
      <property name="AcknowledgedBy" value="admin"></property>
    </properties>
  </event>
  <event id="6">
    <properties>
      <property name="AcknowledgeComment" value="Im good"></property>
      <property name="AcknowledgedBy" value="cloudhub"></property>
    </properties>
  </event>
</events>

{ "events":
 [
    {
      "id": "5",
      "properties":
        {
      	  "AcknowledgeComment": "Received and acknowledged sir",
      	  "LastPluginOutput": "output and more output"
        }
    },
    {
      "id": "6",
      "properties":
        {
      	  "AcknowledgeComment": "Im good",
      	  "LastPluginOutput": "output more output agaIN"
        }
    }
 ]
}

5.5.6 Example Response

<results count='3' success='2' failure='1'>
  <result status='failure' message='Bad consolidation name provided' />
  <result status='success' entity='939'
    location='http://localhost/monitor/api/events/939' />
  <result status='success' entity='1024'
    location='http://localhost/monitor/api/hosts/1024' />
</results>

5.6 Delete Event

Deletes an event or events from foundation. This method does not take post parameters. It works solely off of the URL path.

5.6.1 Method: DELETE

DELETE /api/events/1,2,3

where 1,2,3 is a list of event ids to be deleted

5.6.2 HTTP Headers

5.6.3 XML DELETE Data Example

1. Delete 3 events
   DELETE /api/events/50,51,52

5.6.4 HTTP Status Codes

200 - Events were deleted successfully
500 - An internal server error occurred

5.6.5 Example Response

<results count='3' success='2' failure='1'>
  <result status='failure' message='Event not found: 37’/>
  <result status='success' entity='939'
    location='http://localhost/monitor/api/events/939' />
  <result status='success' entity='1024'
    location='http://localhost/monitor/api/hosts/1024' />
</results>

5.6 Update Events

Updates a batch (1..n) of existing events in foundation database with a new operation status and optional parameters. This method does not take post parameters. It works solely off of the URL path and request parameters.

5.6.1 Method: PUT

PUT /api/events/1,2,3?opStatus=NOTIFIED

where 1,2,3 is a list of event ids to be updated and opStatus is a valid operationStatus

5.6.2 HTTP Headers

5.6.3 Query Parameters on PUT

5.7.4 XML PUT Data Example

1. PUT a new operation status for three events
   PUT /api/events/50,51,52?opStatus=NOTIFIED&updatedBy=admin&comments=testing+123

5.7.5 HTTP Status Codes

200 - Events were created or updated successfully
500 - An internal server error occurred

5.7.6 Example Response

<results count='3' success='2' failure='1'>
  <result status='failure' message='Bad consolidation name provided' />
  <result status='success' entity='939'
    location='http://localhost/monitor/api/events/939' />
  <result status='success' entity='1024'
    location='http://localhost/monitor/api/hosts/1024' />
</results>

More Post Data Examples: XML - JSON