4.6   Events

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

The Event API was introduced 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 3.4  Requesting Specific API Versions.

The 8.4.4 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 were introduced 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 -- -- --

In this section:

4.6.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 https://localhost:8080/mws/rest/events?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET https://localhost:8080/mws/rest/events/<id>?api-version=3

4.6.1.A  Get All Events

URLs and Parameters

GET https://localhost:8080/mws/rest/events?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
Parameter Required Type Value 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}

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

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

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

         ],
         "associatedObjects":[
            {
               "type":"VM",
               "id":"vm1"
            }
         ],
         "code":234881023,
         "eventDate":"2024-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"
            }
         ],
         "code":33554944,
         "eventDate":"2024-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":
    • https://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":
    • https://localhost:8080/mws/rest/events?api-version=3&query={"eventType":"Service Create","severity":"INFO"}
  • To see only events with a code of 33554946:
    • https://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:
    • https://localhost:8080/mws/rest/events?api-version=3&query={"associatedObjects.id":"51b608ddc4aa708a5bebb684"}
  • To see only events that are NOT associated with service 51b608ddc4aa708a5bebb684:
    • https://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:
    • https://localhost:8080/mws/rest/events?api-version=3&query={"severity":{"$in":["ERROR","WARN"]}}

Querying events by date:

  • To see events created before January 27, 2025 at 12:08 A.M. UTC:
    • https://localhost:8080/mws/rest/events?api-version=3&query={"eventDate":{"$lt":"2025-01-27 12:08:00 UTC"}}
  • To see events created before or on January 27, 2025 at 12:08 A.M. UTC:
    • https://localhost:8080/mws/rest/events?api-version=3&query={"eventDate":{"$lte":"2025-01-27 12:08:00 UTC"}}
  • To see all events created after January 27, 2025 at 12:04 A.M. UTC:
    • https://localhost:8080/mws/rest/events?api-version=3&query={"eventDate":{"$gt":"2025-01-27 12:04:00 UTC"}}
  • To see all events created after or on January 27, 2025 at 12:04 A.M. UTC:
    • https://localhost:8080/mws/rest/events?api-version=3&query={"eventDate":{"$gte":"2025-01-27 12:04:00 UTC"}}
  • To see events created between 12:04 A.M. and 12:08 A.M. UTC inclusive:
    • https://localhost:8080/mws/rest/events?api-version=3&query={"eventDate":{"$gte":"2025-01-27 12:04:00 UTC","$lte":"2025-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:
    • https://localhost:8080/mws/rest/events?api-version=3&query={"severity":"ERROR","eventDate":{"$gte":"2025-01-27 12:04:00 UTC","$lte":"2025-01-27 12:08:00 UTC"}}

Sorting

See the sorting section of 3.3  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:
    • https://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:
    • https://localhost:8080/mws/rest/events?api-version=3&query={"eventType":"VM Provision"}&sort={"eventDate":-1}&max=10&offset=50

4.6.1.B  Get Single Event

URLs and Parameters

GET https://localhost:8080/mws/rest/events/<id>?api-version=3
Parameter Required Type Value Description
id Yes String -- The unique identifier of the object.

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

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

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

4.6.2 Creating Events

The HTTP POST method is used to create an Event.

Quick Reference

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

4.6.2.A  Create Event

URLs and Parameters

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

Request Body

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

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

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":"2024-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:

2024-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 below).

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 (").

Related Topics