5.0 Event APIs

h4. 5.0 Event APIs {anchor:Event APIs}

h5. 5.1 Query Events

Retrieve events by query

h6. 5.1.1 Method: GET

{color:#4a86e8}GET /api/events?query=(query criteria see below){color}

h6. 5.1.2 Method: GET with event ids

{color:#4a86e8}GET /api/events/101,204,307{color}

h6. 5.1.3 HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | yes*\* |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| eventIds | Path | comma separated list of 1..n event ids | yes*\* |
Note: _\**Query and eventIds are mutually exclusive. Both cannot be provided, but one or the other is required._

h6. 5.1.4 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.1.5 Query Fields

|| Field || Description || Alias ||
| id | Event id | logMessageId |
| appType | Application Type | applicationType |
| category | The category name | category.name |
| component | The component name |   |
| device | The device identification | deviceName |
| host | The name of the host | hostName |
| hostGroup | The name of a host group | |
| monitor | The monitor status | monitorStatus |
| msgCount | The message count for this event | count |
| operation | The operation status | operationStatus |
| priority | The priority of the event | |
| service | The service status description | serviceDescription \\
serviceStatus |
| serviceGroup | The service group (category) for this event | category |
| severity | The severity of the event |   |
| applicationSeverity | The application severity | appSeverity |
| statisticsType | | |
| textMessage | The event message string | message |
| typeRule | The type rule for the event | |
| | | |
| lastInsertDate | Last time this event was updated | |
| firstInsertDate | First time this event was updated | |
| reportDate | The date this event was reported | |
| | | |
| properties | one or more valid dynamic property names | |
_Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine._

h6. 5.1.6 Example Queries

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

# _query on two fields, and sort by report date_
{color:#4a86e8}GET /api/events?query=(appType='NAGIOS' and service=’http_alive’ and reportDate > '2013-06-01') order by reportDate{color}
# _query on two attributes and order by none-queried field_
{color:#4a86e8}GET /api/events?query=device = '172.28.113.156' and severity = 'CRITICAL' order by operationStatus{color}
# _Paging parameters first and count ..._
{color:#4a86e8}GET /api/events?query=service='http_alive'&first=20&count=10{color}
# _query on all text messages starting with a prefix using LIKE operator_
{color:#4a86e8}GET /api/events?query=message like 'TCP OK%'{color}
# _query on a property and field using LIKE operator_
{color:#4a86e8}GET /api/events?query=(property.SubComponent like 'localhost%' and property.ErrorType = 'SERVICE ALERT'){color}
# _query on the messsage Count greater than 2 messages_
{color:#4a86e8}GET /api/events?query=count > 2{color}
# _query on a not null field_
{color:#4a86e8}GET /api/events?query=appType is not null{color}
# _Query using appType and last insert date between a date range_
{color:#4a86e8}GET /api/events?query=(appType='NAGIOS' and service='http_alive'{color}
{color:#4a86e8}and lastInsertDate between '2013-02-01' and '2013-04-01'){color}
# _Query with a property greater than a threshold, and use a between range query on report date_
{color:#4a86e8}GET /api/events?query=(property.ExecutionTime > 800{color}
{color:#4a86e8}and (reportDate between '2013-02-01' and '2013-04-01')){color}
# _Query with a property greater than a threshold, and use a between range query on report date_
{color:#4a86e8}GET /api/events?query=(property.ExecutionTime > 800){color}
# _Range query using IN operator_
{color:#4a86e8}GET /api/events?query=host in ('qa-load-xp-1','qa-sles-11-64','do-win7-1'){color}
# _Query on hostgroup using IN operator_
{color:#4a86e8}GET /api/events?query=hostgroup in ('IT','HG1'){color}
# _Query by category_
{color:#4a86e8}GET /api/events?query=category = 'SG1'{color}
# _Query on service group using IN operator_
{color:#4a86e8}GET /api/events?query=(serviceGroup in ('web-svr','SG1')){color}
# _Query on service group and host group using IN operator_
{color:#4a86e8}GET /api/events?query=(serviceGroup in ('web-svr','SG1') and hostgroup in ('IT','HG1')){color}
# _Retrieve a single event by event id_
{color:#4a86e8}GET /api/events?104{color}
# _Retrieve a list of comma-separated events by id_
{color:#4a86e8}GET /api/events?104,207,306,494,507{color}

*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.
{code}<?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>{code}

See [Appendix A|DOC71:1.0 Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC71:2.0 Appendix B XML Example Data] and [Appendix C|DOC71:3.0 Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp;Shallow Distinct Response Data - [XML|DOC71:2.0 Appendix B XML Example Data#Events Query - Response Data - XML] \- [JSON|DOC71:3.0 Appendix C JSON Example Data#Events Query - Response Data - JSON]

h5. 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.

h6. 5.2.1 Method: POST

{color:#4a86e8}POST /api/events{color}

h6. 5.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.2.3 Required Post Data Attributes

|| Field || Description || Required ||
| host | The name of the host (Alias: hostName) | True \\ |
| monitorServer | The monitor server to store | True |
| appType | The application type (must be a valid application type) | True |
| textMessage | The event message | True |
| monitorStatus | The monitor status | True |
| severity | The severity of the event | True |
| consolidation \\
Name | The consolidation name to be used to build the consolidation criteria to minimize event logging | Recommended |
| device | The name of the device for this host (will be created if it does not already exist) | True |
| reportDate | The date this event was reported | True \\ |

h6. 5.2.4 Optional Post Data Attributes

|| Field || Description || Alias ||
| id | Event id | logMessageId |
| category | The category name | category.name |
| component | The component name | &nbsp; |
| hostGroup | The name of a host group | |
| msgCount | The message count for this event | count |
| operation | The operation status | operationStatus |
| priority | The priority of the event | &nbsp; |
| service | The service status description | serviceDescription \\
serviceStatus |
| serviceGroup | The service group (category) for this event | category |
| applicationSeverity | The application severity | appSeverity |
| statisticsType | &nbsp; | &nbsp; |
| typeRule | The type rule for the event | |
| lastInsertDate | Last time this event was updated | |
| firstInsertDate | First time this event was updated | |
| properties | one or more valid dynamic property names | |

h6. 5.2.5 HTTP Status Codes

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

h6. 5.2.6 Example Response
{code}<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>{code}

h6. 5.2.7 Example Post Data

The post data should be formatted like in either XML or JSON:
{code}{ "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"
}
}
]
}{code}

More Post Data Examples: [XML|DOC71:2.0 Appendix B XML Example Data#Events Post - Post Data XML] \- [JSON|DOC71:3.0 Appendix C JSON Example Data#Events Post - Post Data JSON]




h5. 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).

h6. 5.3.1 Method: POST

{color:#4a86e8}POST /api/events/ack{color}

h6. 5.3.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.3.3 Required Post Data Attributes

|| Field || Description || Required ||
| appType | The application type for this event. | True |
| hostName | The host name to be matched for updating of events | True |
| serviceDescription | The name of the service to update events for | False |
| acknowledgedBy | The name of the program or user acknowledging | False |
| acknowledgeComment | Additional comments | False |

h6. 5.3.4 HTTP Status Codes

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

h6. 5.3.5 Example Post Data

The post data should be formatted in XML or JSON:
{code}<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"
}
]
}{code}

h6. 5.3.6 Example Response
{code}{
"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
}{code}

h5. 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).

h6. 5.4.1 Method: POST

{color:#4a86e8}POST /api/events/unack{color}

h6. 5.4.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.4.3 Required Post Data Attributes

|| Field || Description || Required ||
| appType | The application type for this event. | True |
| hostName | The host name to be matched for updating of events | True |
| serviceDescription | The name of the service to update events for | False |

h6. 5.4.4 HTTP Status Codes

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

h6. 5.4.5 Example Post Data

The post data should be formatted in XML or JSON:
{code}<unacks>
<unack
appType="VEMA"
hostName="STOR-datastore1"
serviceDescription="summary.freeSpace"
/>
</unacks>

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

h6. 5.4.6 Example Response
{code}{
"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
}{code}

h5. 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.

h6. 5.5.1 Method: PUT

{color:#4a86e8}PUT /api/events{color}

h6. 5.5.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

See [Appendix A|DOC71:1.0 Appendix A Curl Examples] for examples of usage with Curl
&nbsp;&nbsp; Post Data Example: [XML|DOC71:2.0 Appendix B XML Example Data#Events Properties Update - Put Data XML] \- [JSON|DOC71:3.0 Appendix C JSON Example Data#Events Properties Update - Put Data JSON]




h6. 5.5.3 Required PUT Data

|| Field || Description || Required ||
| id | The id for this event. | True |
| properties | The set of properties to be updated on this event | True |

h6. 5.5.4 XML PUT Data Example

{color:#4a86e8}PUT /api/events/{color}

h6. 5.5.5 HTTP Status Codes

200 - Events were created or updated successfully
500 - An internal server error occurred
{code}<?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>{code}

{code}{ "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"
}
}
]
}{code}

h6. 5.5.6 Example Response
{code}<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>{code}

h5. 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.

h6. 5.6.1 Method: DELETE

{color:#4a86e8}DELETE /api/events/1,2,3{color}

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

h6. 5.6.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.6.3 XML DELETE Data Example

# Delete 3 events
{color:#4a86e8}DELETE /api/events/50,51,52{color}

h6. 5.6.4 HTTP Status Codes

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

h6. 5.6.5 Example Response
{code}<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' />

h6. 5.6.1 Method: PUT

{color:#4a86e8}PUT /api/events/1,2,3?opStatus=NOTIFIED{color}

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

h6. 5.6.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.6.3 Query Parameters on PUT

|| Field || Description || Required ||
| opStatus | The operational Status to update | &nbsp; |
| updatedBy | The username who updated | True |
| comments | Comments for this event | &nbsp; |

h6. 5.7.4 XML PUT Data Example

# PUT a new operation status for three events
{color:#4a86e8}PUT /api/events/50,51,52?opStatus=NOTIFIED&updatedBy=admin&comments=testing+123{color}

h6. 5.7.5 HTTP Status Codes

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

h6. 5.7.6 Example Response
{code}<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>{code}

More Post Data Examples: [XML|DOC71:2.0 Appendix B XML Example Data#Events Post - Post Data XML] \- [JSON|DOC71:3.0 Appendix C JSON Example Data#Events Post - Post Data JSON]