5.230 Events

This section describes the URLs, request bodies, and responses delivered to and from Moab Web Services for handling events.

The Event API is new with API version 3. The supported methods table below requires each resource to be accessed with a URL parameter of api-version=3 in order to behave as documented.

For more information, see Requesting Specific API Versions.

The Fields: Events reference contains the type and description of all fields in the Event object. It also contains details regarding which fields are valid during POST actions.

Important changes

The following fields have been renamed in API version 3:

Name in version 1 & 2	Name in version 3
eventTime	eventDate
sourceComponent	origin
errorMessage.message	message
relatedObjects	associatedObjects

The following fields have been removed in API version 3.

MWS will no longer report these fields, even if there are existing events in the database with these fields.

eventCategory
status
facility
initiatedBy
primaryObject (Primary objects are now reported in associatedObjects.)
errorMessage.originator
errorMessage.errorCode
details

The following fields are new in API version 3 (see Fields: Events):
- arguments
- code

Supported methods

Resource	GET	PUT	POST	DELETE
/rest/events	Get All Events	--	Create Event	--
/rest/events/<id>	Get Single Event	--	--	--

This topic contains these sections:

Getting Events
- Get All Events
- Get Single Event
Creating Events
- Create Event

5.230.1 Getting Events

The HTTP GET method is used to retrieve Event information. Queries for all objects and a single object are available.

Quick reference

GET http://localhost:8080/mws/rest/events?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost:8080/mws/rest/events/<id>?api-version=3

5.230.1.A Get All Events

URLs and parameters

GET http://localhost:8080/mws/rest/events?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Type	Valid values	Example
query	No	JSON	Query for specific results. It is possible to query events by one or more fields based on MongoDB query syntax.	query={"severity":"ERROR"}
sort	No	JSON	Sort the results. Use 1 for ascending and -1 for descending.	sort={"id":-1}

Parameter

Required

Type

Valid values

Example

query

JSON

Query for specific results.

It is possible to query events by one or more fields based on MongoDB query syntax.

query={"severity":"ERROR"}

sort

JSON

Sort the results. Use 1 for ascending and -1 for descending.

sort={"id":-1}

See Global URL Parameters for available URL parameters.

Sample response

GET http://localhost:8080/mws/rest/events?api-version=3
------------------------------------

{
   "totalCount":2,
   "resultCount":2,
   "results":[
      {
         "arguments":[

         ],
         "associatedObjects":[
            {
               "type":"VM",
               "id":"vm1"
            }
         ],
         "tenant":
            {
               "id":"1234567890abcdef12345678",
               "name":"Research"
            },
         "code":234881023,
         "eventDate":"2013-06-10 17:13:31 UTC",
         "eventType":"VM Provision",
         "message":null,
         "origin":"CSA Plugin",
         "severity":"INFO",
         "id":"51b6093bc4aa708a5bebb6ae"
      },
      {
         "arguments":[
            "51b608ddc4aa708a5bebb684"
         ],
         "associatedObjects":[
            {
               "type":"Service",
               "id":"51b608ddc4aa708a5bebb684"
            }
         ],
         "tenant":
            {
               "id":"1234567890abcdef12345678",
               "name":"Research"
            },
         "code":33554944,
         "eventDate":"2013-06-10 17:11:59 UTC",
         "eventType":"Service Create",
         "message":"The service '51b608ddc4aa708a5bebb684' was created",
         "origin":"MWS/ServiceEvents/CREATE_1ID",
         "severity":"INFO",
         "id":"51b608dfc4aa708a5bebb686"
      }
   ]
}

Querying events

It is possible to query events by one or more fields based on MongoDB query syntax. The following contains examples of simple and complex event queries and event queries by date.

Simple queries:

To see only events that are of type "Service Create":

http://localhost:8080/mws/rest/events?api-version=3&query={"eventType":"Service Create"}

To see only events of type "Service Create" with the severity of "INFO":

http://localhost:8080/mws/rest/events?api-version=3&query={"eventType":"Service Create","severity":"INFO"}

To see only events with a code of 33554946

http://localhost:8080/mws/rest/events?api-version=3&query={code:33554946}

More complex queries:

You can query on embedded JSON objects within the event JSON. For example, to see events associated with service 51b608ddc4aa708a5bebb684:

http://localhost:8080/mws/rest/events?api-version=3&query={"associatedObjects.id":"51b608ddc4aa708a5bebb684"}

To see only events that are NOT associated with service 51b608ddc4aa708a5bebb684:

http://localhost:8080/mws/rest/events?api-version=3&query={"associatedObjects.id":{"$ne":"51b608ddc4aa708a5bebb684"}}

When the field values of the desired events are a finite set, you can use the $in operator. For example, to see events that have a severity of either WARN or ERROR:

http://localhost:8080/mws/rest/events?api-version=3&query={"severity":{"$in":["ERROR","WARN"]}}

Querying events by date

To see events created before January 27, 2012 at 12:08 a.m. UTC:

http://localhost:8080/mws/rest/events?api-version=3&query={"eventDate":{"$lt":"2012-01-27 12:08:00 UTC"}}

To see events created before or on January 27, 2012 at 12:08 a.m. UTC:

http://localhost:8080/mws/rest/events?api-version=3&query={"eventDate":{"$lte":"2012-01-27 12:08:00 UTC"}}

To see all events created after January 27, 2012 at 12:04 a.m. UTC:

http://localhost:8080/mws/rest/events?api-version=3&query={"eventDate":{"$gt":"2012-01-27 12:04:00 UTC"}}

To see all events created after or on January 27, 2012 at 12:04 a.m. UTC:

http://localhost:8080/mws/rest/events?api-version=3&query={"eventDate":{"$gte":"2012-01-27 12:04:00 UTC"}}

To see events created between 12:04 a.m. and 12:08 a.m. UTC inclusive:

http://localhost:8080/mws/rest/events?api-version=3&query={"eventDate":{"$gte":"2012-01-27 12:04:00 UTC","$lte":"2012-01-27 12:08:00 UTC"}}

To see events created between 12:04 a.m. and 12:08 a.m. UTC inclusive that have a severity of ERROR:

http://localhost:8080/mws/rest/events?api-version=3&query={"severity":"ERROR","eventDate":{"$gte":"2012-01-27 12:04:00 UTC","$lte":"2012-01-27 12:08:00 UTC"}}

Sorting

See the sorting section of Global URL Parameters.

Limiting the number of results

If you want to limit the number of results of events, you can use the max parameter. For example, to see only 10 "VM Provision" events:

http://localhost:8080/mws/rest/events?api-version=3&query={"eventType":"VM Provision"}&sort={"eventDate":1}&max=10

To see "VM Provision" events 51-60 when sorted by eventDate in descending order, you can combine max with offset, as follows:

http://localhost:8080/mws/rest/events?api-version=3&query={"eventType":"VM Provision"}&sort={"eventDate":-1}&max=10&offset=50

5.230.1.B Get Single Event

URLs and parameters

GET http://localhost:8080/mws/rest/events/<id>?api-version=3

Parameter	Required	Type	Valid values	Description
id	Yes	String	--	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample response

GET http://localhost:8080/mws/rest/events/51b608dfc4aa708a5bebb686?api-version=3
------------------------------------

{
  "arguments": ["51b608ddc4aa708a5bebb684"],
  "associatedObjects": [  {
    "type": "Service",
    "id": "51b608ddc4aa708a5bebb684"
  }],
  "tenant":
    {
      "id":"1234567890abcdef12345678",
      "name":"Research"
    },
  "code": 33554944,
  "eventDate": "2013-06-10 17:11:59 UTC",
  "eventType": "Service Create",
  "message": "The service '51b608ddc4aa708a5bebb684' was created",
  "origin": "MWS/ServiceEvents/CREATE_1ID",
  "severity": "INFO",
  "id": "51b608dfc4aa708a5bebb686"
}

5.230.2 Creating Events

The HTTP POST method is used to create an Event.

Quick reference

POST http://localhost:8080/mws/rest/events?api-version=3

5.230.2.A Create Event

URLs and parameters

POST http://localhost:8080/mws/rest/events?api-version=3

Request body

POST http://localhost:8080/mws/rest/events?api-version=3 Content-Type:application/json
------------------------------------

{
      "arguments": ["vm1"],
      "associatedObjects": [      {
        "type": "VM",
        "id": "vm1"
      }],
      "code": 234881023,
      "eventDate": "2013-06-10 17:13:31 UTC",
      "eventType": "VM Provision",
      "message": "The virtual machine \"vm1\" was provisioned",
      "origin": "CSA Plugin",
      "severity": "INFO"
    }

An event's tenant is automatically inherited from the associatedObjects.

Sample response

If the request was successful, the response will be an object with an id property containing the ID of the newly created events. On failure, the response is an error message.

JSON response
------------------------------------

{"arguments":["vm1"],"associatedObjects":[{"_id":"vm1","id":"vm1","type":"VM","version":0}],"code":234881023,"eventDate":"2013-06-10 17:13:31 UTC","eventType":"VM Provision","id":"51b62046c4aa708a5bebc018","message":"The virtual machine vm1 was provisioned","origin":"CSA Plugin","severity":"INFO","version":0}

Below is an example of events.log output for a successful event request:

2013-06-10T11:13:31.000-06:00 severity="INFO" code="0x0dffffff" type="VM Provision" origin="CSA Plugin" associatedObject.0.type="VM" associatedObject.0.id="vm1" arguments=["vm1"] message="The virtual machine \"vm1\" was provisioned"

Note that " (double quote) characters in the input have been replaced by \" characters in the output. (For other character restrictions, see Restrictions.)

Restrictions

Special characters—such as newline, carriage return, and " (double quote) characters—are encoded in the output of events.log to make events.log easy to parse with scripts and third party tools. For example, if the input XML contains:

<ErrorMessage>RM says, "Cannot provision vm21"</ErrorMessage>

Then the following will be output to events.log:

error.message="RM says, \"Cannot provision vm21\""

(Notice that " has been replaced with \".)

This table contains the most common encodings. (For more information, see escape sequences for Java Strings.)

Character	Escape sequence
" (double quote)	\"
\ (backslash)	\\
newline	\n
carriage return	\r
tab	\t

Other restrictions include:

origin, eventType, associatedObject.id, and associatedObject.type cannot contain single quotes (') or double quotes (").