Event Notification and Processing

When an event is triggered, all the event subscribers will be notified and they can then process the event.

Event Notification

Once a resource of an application service is subscribed to notifications, the service must be ready to handle the corresponding HTTP POST requests coming from the APS controller.

Notification Delivery

Event notifications are processed in accordance with the following rules:

• When an event occurs in the platform, the APS controller selects the list of resources that are subscribed for the event. It then adds the event notification to the notification queue for those targets that meet at least one of the following requirements:

  • The event-source resource is linked to the event-target resource directly, either as a referrer, an admin, or the owner.

  • The event-source owner has a link to the event-target resource.

• The APS controller constantly checks the notification queues and retrieves notification records for delivery. It sends each notification to the corresponding handler specifying the event parameters as illustrated below. If the notification is accepted successfully, the application service must respond with an HTTP code, either HTTP_OK (200) or HTTP_NO_CONTENT (204).

• On successful delivery of a notification to its destination, the APS controller deletes the notification record from the database.

• The APS controller repeats the delivery of a notification if it receives the 202 return code; this may happen an unlimited number of times.

• The APS controller repeats the delivery of a notification up to 10 times if it receives one of the 4xx or 5xx codes in every attempt; on completion of this cycle, the process fails and the notification is removed from the database.

The APS controller sends event notifications to subscribed resources using the following schema:

{
  "id": "http://aps-standard.org/types/core/event/notification/1.0",
  "name": "EventNotification",
  
  "properties": {
      "event": {
         "type": "string",
         "format": "uri",
         "required": true,
         "description": "Type of event (URI)"
      },
      "subscription": {
         "type": "string",
         "description": "Subscription which delivers the event notification"
      },
      "time": {
         "type": "string",
         "format": "date-time",
         "description": "Date-time when event happens"
      },
      "serial": {
         "type": "number",
         "description": "Serial number of event (monotonic growing)"
      },
      "source": {
         "type": "object",
         "properties": {
             "type": {
                 "type": "uri",
                 "description": "APS Type of source resources"
             },
             "id": {
                 "type": "string",
                 "description": "Resource which is source of event"
             }
         }
      }
  }
}

Example of an event notification sent to the subscriber managed by the events service and whose APS ID is 5dff8e79-5516-44a2-897c-244a0fdc8ec9:

POST /sample-app/events/5dff8e79-5516-44a2-897c-244a0fdc8ec9/onVPSchange
...
{
  "event": "http://aps-standard.org/core/events/changed",
  "time": "2013-11-28T13:44:03Z",
  "serial": 12,
  "subscription": "5ee0fe9d-c812-4af8-a969-5ca28077b032",
  "source": {
    "id": "7868ed9c-969c-4a4b-aadd-db9198c711e9",
    "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0"
   }
}

Event Processing

On the receiving end, the Notification structure in the base core resource type defines the schema for received event notifications. The event handler must be declared as an operation in the resource schema and defined in the corresponding service definition.

← Event Subscriptions

General Events →