Events

Events are records that HPE GreenLake creates when a resource has changed (known as an occurrence). The records contain metadata (context attributes) and data (event data) about the change in the resource, and the events are sent by HPE GreenLake to the event destination (webhook URL) in the form of a message.

Events follow the CloudEvents standard adopted by the Cloud Native Computing Foundation. This standard describes common formats for event data that provide interoperability across services, platforms, and systems. View the CloudEvents standard.

Events terminology

• Event —Events are factual records that HPE GreenLake creates when a resource has changed.
• Event data —Information about the occurrence or details about the data that was changed.
• Event types —Distinguishes between different events. Event types include created, updated, or deleted.
• Message —Events are sent to their destination in the form of a message.
• Occurrence —An occurrence is a factual capture of software system activity. For example, an occurrence might happen because of a state change in the software like a server is about to reboot.
• Context attributes —This is metadata included in an event that is used to identify the relationship of events to aspects of the system or to other events.

Event types and event data

Event data is domain-specific information about the occurrence. The information contained within data is encoded as specified in datacontenttype. HPE GreenLake supports three categories of event type.

• Resource created, updated, and deleted events
• Resource custom events
• Non-resource events

Resource create, update, and delete events

These event types represent state changes to individual resources. When a resource is created:

• type— com.hpe.greenlake.<api-group>.<version>.<resource-collection>.created
• datacontenttype— application/json
• time—The same as the createdAt and updatedAt property of the resource.
• data—A full representation of the updated resource.

When a resource is updated:

• type— com.hpe.greenlake.<api-group>.<version>.<resource-collection>.updated
• datacontenttype— application/json
• time—The same as the updatedAt property of the resource.
• data—A full representation of the updated resource.

When a resource is deleted:

• type— com.hpe.greenlake.<api-group>.<version>.<resource-collection>.deleted
• datacontenttype— application/json
• time—The time the resource was deleted
• data—A partial representation of the deleted resource including the type and id properties.

Resource custom events

Resource custom events represent a transition related to an individual resource that is not a state change. For example, the completion of a system start.

The resource custom event has:

• type— hpe.greenlake.<api-group>.<version>.<resource-group>.<event>
• datacontenttype— application/json
• time—The time the custom event occurred.
• data—Custom data.

Non-resource event

These events represent a transition within the system not related to an individual resource. The non-resource event has:

• type— hpe.greenlake.<api-group>.<version>.<event>
• datacontenttype— application/json
• time—The time the custom event occurred.
• data—Custom data.

Event context attributes

Event context attributes are metadata that describe the event occurrence. HPE GreenLake events include the mandatory context attribute properties defined in the CloudEvents standard, and may include several of the optional properties.

Mandatory properties of an event

Optional properties

The optional properties that an event might include.

Event filtering

With HPE GreenLake events, you can use filters to receive event notifications only when a specified subset of an event type occurs. For example, when the event type occurs for a particular user, status type, or when a value is greater or lower than a threshold.

Use the HPE GreenLake UI to subscribe to an event and specify a filter, see Subscribe to an event.

This section explains the elements of event filtering generically helping you construct your own filters prior to specify your filter in the UI.

Consult the event type documentation to learn the specifics of what a particular event type supports. The documentation for an event type specifies:

• The properties you can filter on.
• The literals that apply to each property.
• The comparison operations allowed.
• The logical operators allowed.

The event type documentation provides examples of event filters that will assist you in building your own.

Example filters:

• status eq 'active' —The event is sent when the status is active.
• cpu gt 4 —The event is sent when the CPU is greater than 4.
• startswith(name, 'abc') —The event is sent when the name begins with the letters a, b, and c.

Building a simple filter

The basic syntax of a filter is <property> <comparison operation> <literal>. For example, name eq 'John'. By applying this filter, HPE GreenLake only sends event messages to the webhook when the name (propertyName) is equal (comparison operation) to John (literal).

Property

A property is a filterable resource or attribute. The property name is typically to the left of the comparison operation. Event filters only apply to the properties in the data field, see event types and event data.

In the following JSON example of an event type payload, properties include app_slug, or customer_id. The example JSON also includes nested properties, such as audit_info/username or audit_info/category. The / separator specifies nested properties.

  "data": {
    "app_slug": "string",
    "customer_id": "string",
    "username": "string",
    "app_instance_id": "string",
    "application_customer_id": "string",
    "audit_details": {},
    "enable_streaming": "string",
    "audit_info": {
      "username": "string",
      "category": "string",
      "customer_name": "string",
      "account_type": "string",
      "msp_id": "string",
      "audit_created_at": "string",
      "additional_info": {},
      "has_details": true
    },
    "created_at": "string"
  }
}

Literal

Event filters might support the following literals:

A filter query must evaluate the correct literal type.

For example, if the filter aims to evaluate the property name, which is a string, the filter name eq John will fail. A string literal must begin and end with single quotes. Similarly, if the filter aims to evaluate the property age, which is an integer, the filter age eq '60' will fail.

Comparison operation

A comparison operation compares a property to a literal to produce a logical value (true or false). Event messages are only sent when the comparison evaluates to true.

The comparisons an event type might support are the following:

Combining filters using logical operators

Logical operators allow you to join multiple simple filters. The basic syntax of a combined filter is <simple filter> <logical operator> <simple filter>. For example, name eq 'John' and name eq 'Aya'. With this example filter applied, you will receive event messages when the event type applies to John and Aya.

You can group filter queries using a parenthesis (). For example, (count eq 5 or name eq 'fred') and color eq 'RED'. The filter expression in the parenthesis gets evaluated first and then used in the outer filter expression. The order of precedence among the logical operators is first not, then and, and then or. The evaluation order is changed when grouping using parentheses.

Invalid filters

If you supply an invalid filter in the HPE GreenLake UI, you’ll get a 400 Bad Request and an error message explaining which token failed to parse.

Versioning

HPE GreenLake events are versioned to ensure they are adaptable over time, facilitating updates without disrupting existing functionalities.

Each event type includes a version string to indicate the version of the event. This version string aligns with the API versioning.

Examples:

• com.hpe.greenlake.devices. v2alpha2. devices.updated
• com.hpe.greenlake.workspaces. v1beta1. tenants.deleted
• com.hpe.greenlake.data-services. v1. volumes.created

Event versions pass through stages of increasing maturity, from alpha to beta to stable (v1).

See HPE GreenLake Versioning for more on the versioning stages.

Deprecation policy and sunsetting

During the deprecation period, the event is still supported but is no longer recommended for use. Consumers are encouraged to migrate to the newer version. After deprecation, the event version is no longer supported in the sunset phase and may be removed.

Event deprecation is similar to and aligned with API deprecation. To attain this alignment, HPE GreenLake events use the CloudEvents deprecation attributes. These attributes inform event consumers about upcoming changes or removals, facilitating smoother transitions and adjustments. The attributes used are:

• deprecated
• deprecationfrom
• deprecationsunset
• deprecationmigration

See Optional properties.

Version history and changelog

A changelog is provided and released in the event documentation when a version change is made. The concepts are based on: https://keepachangelog.com/en/1.1.0/

One change is that we will not use semver.

Types of changes:

• Added for new features
• Changed for changes in existing functionality
• Deprecated for soon-to-be removed features
• Removed for removed features
• Fixed for any bug fixes
• Security in case of security and vulnerability changes