27 Nov

Gathering Event Data from vCloud Director 10

Facebooktwitterredditlinkedinmail

Service Providers have long used the vCloud Director notification system to receive events from the system. These can be used to perform actions or to build an integration with a back-office billing system. The events are published on a RabbitMQ instance and can be consumed in any language that can bind with the message bus. One of the main issues with using this method for integration with the billing system is how to recover from missed notifications.

A new API was created in vCloud Director 10.0 to allow access to the events stream without needing to integrate with RabbitMQ and to allow for looking back at the event stream in the case of missing an event notification. The new API, auditTrail, lives in the vCloud Director cloudapi space. The documentation can be found here or by accessing the API Explorer within vCloud Director:

Direct Link: https://{VCD_URL}/api-explorer/provider#/auditTrail/queryAuditTrail

To access the data, do a GET call to: https://{{vcdAddress}}/cloudapi/1.0.0/auditTrail?page=1&pageSize=25

Headers:

  • accept: application/json;version=33.0
  • Authorization: Bearer {YOUR_TOKEN}

Note that page and pageSize are required to limit the returned data size.

The return will be in the format of:

{
"resultTotal": 1000,
"pageCount": 50,
"page": 1,
"pageSize": 25,
"associations": null,
"values": [{},]
}

You can then use the resultTotal and pageCount to walk through / process the entire data set.

In order to select a specific data set, the option parameters of filter, sortAsc and sortDesc can be added to the query.

The filter parameter accepts a FIQL format. Currently our timestamp filter is very strict and has to include all parts:

{date}T{time}{timezone-offset}

Example: 2019-10-01T06:23:00.836+00:00

Remember to URL encode the + to %2b

To retrieve all the events that happened in October 2019 I would use the filter:

filter=(timestamp=gt=2019-10-01T00:00:00.000%2b00:00;timestamp=lt=2019-11-01T00:00:00.000%2b00:00)

Full API call would look like:
https://{{vcdAddress}}/cloudapi/1.0.0/auditTrail?page=1&pageSize=25&sortAsc=timestamp&filter=(timestamp=gt=2019-10-01T00:00:00.000%2b00:00;timestamp=lt=2019-11-01T00:00:00.000%2b00:00)

Examples of Operators accepted:

Basic Operator Description
== Equal To
!= Not Equal To
=gt= Greater Than
=ge= Greater Or Equal To
=lt= Less Than
=le= Less Or Equal To

Besides timestamp you can also filter on a few other aspects of the data:

To filter out the completed events, I could add:

eventType!=com/vmware/vcloud/event/task/complete

The operatingOrg, user, and eventEntity are complex data types, but can be filtered based on the nested ID, but not Name.

"operatingOrg": {
"name": "acme",
"id": "urn:vcloud:org:742c7a82-d217-4b57-a316-49128c5c08a8"
},
"user": {
"name": "jdwyer",
"id": "urn:vcloud:user:dee585c6-8553-4913-bcd7-4555b678de65"
},
"eventEntity": {
"name": "attguy",
"id": "urn:vcloud:user:839a3af1-d23f-4371-842a-e8f5fbe9b7e4"
},

To filter based on only events for the “acme” organization I could do:

operatingOrg.id==urn:vcloud:org:742c7a82-d217-4b57-a316-49128c5c08a8

To filter out all the events by user “jdwyer”:

user.id!=urn:vcloud:user:dee585c6-8553-4913-bcd7-4555b678de65

Facebooktwitterredditlinkedinmail