Application Packaging Standard

Last updated 18-Mar-2019

General Events¶

General or system events where an event source can be any APS type or APS resource.

In this document:

List of Types
Event Subscriptions
Event Notification
Event Processing
Event Subscription Example

List of Types ¶

The following event types are available when subscribing to an APS type or resource:

Type	Event ID	Description
Linked	http://aps-standard.org/core/events/linked	Resource is linked with another resource (a link created)
Unlinked	http://aps-standard.org/core/events/unlinked	Resource is unlinked from another resource (a link removed).
Changed	http://aps-standard.org/core/events/changed	Resource configuration is updated.
Removed	http://aps-standard.org/core/events/removed	Resource was removed.
Available	http://aps-standard.org/core/events/available	New resource becomes available.

An application service may subscribe its resources for events than can happen with the related resources or the ones in the current context. Event subscriptions for each subscribed resource are stored in form of a REST collection /aps/2/resources/{ID}/aps/subscriptions, where {ID} represents the identifier of the subscribed resource.

Requests for creating event subscriptions must comply with the following schema:

{
  "id": "http://aps-standard.org/types/core/event/subscription/1.0",
  "name": "EventSubscription",
  
  "properties": {
      "id": {
         "type": "string",
         "description": "Event subscription identifier"
      },
      "event": {
         "type": "string",
         "format": "uri",
         "description": "Event type identifier"
      },
      "source": {
         "type": "object",
         "properties": {
             "type": {
                 "type": "string",
                 "format": "uri",
                 "description": "APS Type of source resources"
             },
             "id": {
                 "type": "string",
                 "description": "Concrete resource to listen events from"
             }
         }
      },
      "relation": {
         "type": "string",
         "description": "Relation id for events link/unlink events"
      },
      
      "handler": {
         "type": "string",
         "description": "Operation name to handle Event, should accept only parameter of type EventNotification" 
      }
   }
}

The schema contains the following properties:

The id property is not included into the request as the APS controller assigns it when creating a subscription.
The event property defines one of event types listed in the List of Types table. For example:
- The subscription of type “http://aps-standard.org/core/events/changed” requires the APS controller to send notifications when any properties or aps.status of an event source is changed. Single Configure a resource or Update a resource operations will generate one Changed event.
- The subscription of type “http://aps-standard.org/core/events/linked” requires the APS controller to notify about adding a link to the event source. In this case, the link operation is tracked. If the relation property is presented, then only the links specified by this relation will be tracked.
The source property defines event sources, either all resources of the specified type (URI format) or a certain resource specified by the id property.
Note
1. For the Available event type, naturally only an APS type can be requested as the event source.
2. When subscribing to an APS type, keep in mind type inheritance. For example, if both type-2 and type-3 implement type-1, then subscribing to type-1, you will effectively subscribe to all resources instantiated from type-1, type-2, and type-3.
The relation property is relevant when subscribing to the Linked and Unlinked events. It specifies the relation of the source that must be tracked.
The handler property declares the operation that must handle the event notifications on the subscriber side.

Note

Controller may consolidate several events of same type with same parameters (except serial and time) together and send only last of them.

Example of a subscription entry, tracking the creation of a domain:

{
   "id": "40009029-27C0-492D-B082-8E383FC28C81",
   "event": "http://aps-standard.org/core/events/available",
   "source": {
      "type": "http://parallels.com/aps/types/pa/dns/zone/1.0"
   },
   "handler": "onDomainAvailable"
}

Example of a subscription entry, tracking establishment of links between vpses and offers:

{
   "id": "E92A9B11-E37F-433B-AAC2-8A73E97A2D96",
   "event": "http://aps-standard.org/core/events/linked",
   "source": {
      "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0"
   },
   "handler": "onVPSofferLink"
}

Subscribing to Events¶

Event subscriptions are created by POST requests. Subscription ID should be not set, because the APS controller will assign it.

For example, a request for subscribing the 7389d901-701a-4ada-bac1-50b5443b3fa5 resource for the linked events in the resources based on the virtual-environment type looks as follows:

POST /aps/2/resources/7389d901-701a-4ada-bac1-50b5443b3fa5/aps/subscriptions
...

{
   "event": "http://aps-standard.org/core/events/linked",
   "source": {
     "type": "http://www.aps-standard.org/infrastructure/virtual-environment/1"
   },
   "relation": "containers",
   "handler": "onContainerLink"
}

In the following response, one can find the event subscription ID:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
...
{
   "id": "8a9cdef0-0348-4d51-9c64-adbbaf8c4540",
   "event": "http://aps-standard.org/core/events/linked",
   "source": {
     "type": "http://www.aps-standard.org/infrastructure/virtual-environment/1"
   },
   "relation": "containers",
   "handler": "onContainerLink"
}

Everyone who has GET access to the event-source resource is able to subscribe to it. However events are delivered to the event-target resource only when at least one of the following conditions is true:

The event-source resource is linked to the event-target resource directly (located in any security contexts)
The event-source is owned by the same security principal as the event-target resource, for example, a resource owned by an account receives events from all resources that belong to the same account

Getting Event Subscriptions¶

By issuing a GET request one may fetch a list of event subscriptions for a particular event subscriber.

The Pagination header indicates the number of returned items.

Request:

GET /aps/2/resources/7389d901-701a-4ada-bac1-50b5443b3fa5/aps/subscriptions

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Range: items 0-99/100
...
{
   "id": "0DB1F249-9287-4087-9334-05539568BD01",
   "event": "http://aps-standard.org/core/events/linked",
   "source": {
      "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0"
   },
   "handler": "onVPSofferLink"
}

{
   "id": "5EE0FE9D-C812-4AF8-A969-5CA28077B032",
   "event": "http://aps-standard.org/core/events/changed",
   "source": {
       "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0"
   },
   "handler": "onVPSchange"
}

Deleting Event Subscriptions¶

Suppose, we have an event subscription that your application identified by the following request:

GET /aps/2/resources/6afef858-b72a-4c24-879a-edb89cdb107d/aps/subscriptions/

Response:

{
    "id": "EFC7BB64-0746-4A37-8E08-88242888E6A6",
    "event": "http://aps-standard.org/core/events/removed",
    "source": {
        "type": "http://parallels.com/aps/types/pa/dns/zone/1.0",
    },
    "handler": "onDomainRemove"
}

To delete the subscription, the following DELETE request must be sent:

DELETE /aps/2/resources/6afef858-b72a-4c24-879a-edb89cdb107d/aps/subscriptions/EFC7BB64-0746-4A37-8E08-88242888E6A6

Response:

HTTP/1.1 204 OK

Note

If one of the two resources in the subscriber-publisher relation is deleted, either the subscribed resource or the tracked resource, the event subscription will be deleted automatically.

Event Notification ¶

Once a resource of an application service is subscribed for notifications, the service must be ready to handle the corresponding HTTP POST requests coming from the APS controller. Event notifications are processed in accordance with the following rules:

For each subscriber in the system, the APS controller creates the notification queue where notification records are registered.
When an event occurs in the system, the APS controller selects the list of resources that are subscribed for the event. Thus, each subscriber gets the corresponding notification record in its own notification queue.
APS controller continuously checks the notification queues and retrieves notification records for delivery. It sends each notification to the corresponding handler specifying the event parameters as illustrated later. In case of successful acceptance of the notification, the application service must respond with 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.
If for some reasons, the attempt to deliver a notification failed, the APS controller retries the delivery attempts many times until it receives the 200/204 return code or the 64th attempt fails (in several hours). It increases exponentially time interval between attempts for each subsequent attempt. On completion of these retries, the APS controller will delete the notification record.

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, which ID is 5dff8e79-5516-44a2-897c-244a0fdc8ec9:

POST /events/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 Subscription Example ¶

The following example, taken from a sample package, demonstrates how to declare event handler, subscribe to an event, and process events. The OwnCloud application is available for users represented as LDAP user APS resources. Each LDAP user relates to a platform user. To keep the two resources synced, the users service must be notified of changes occurred with the platform user.

In the resource type (resource schema), we declare the onUserChange operation (see Operations for details) that is activated on receiving a POST request from the APS controller through the /onUsrChange path.

"operations": {
    ...
    "onUserChange": {
        "verb": "POST",
        "path": "/onUsrChange",
        "parameters": {
            "event": {
                "type": "http://aps-standard.org/types/core/resource/1.0#Notification",
                "required": true,
                "kind": "body"
            }
        }
    }
}

The received JSON object “event” must correspond to the “Notification” structure defined in the base APS type Resource.

Since the application needs to sync each LDAP user with the correspondent platform user, we subscribe the users service to changes in the platform user properties. Therefore, in the users.php script, we use the EventSubscription class defined in the APS PHP runtime. The service subscribes to the event each time, when a new LDAP user is provisioned, as defined inside the provision() function. The subscription process is illustrated by the following excerpts from the provision() function:
- Create a changed event subscription object based on the EventSubscription schema and declare the onUserChange function as the event handler.
```
$sub = new \APS\EventSubscription(\APS\EventSubscription::Changed, "onUserChange");
```
- Specify resources based on the service user type as the event sources.
```
$sub->source->type="http://aps-standard.org/types/core/service-user/1.0";
```
- Request the APS controller to create the event subscription ($sub) for the current resource ($this).
```
$apsc = \APS\Request::getController();
$subscriptionnotifications = $apsc->subscribe($this, $sub);
```

The onUserChange() function specifics are presented by the following excerpts:

public function onUserChange($event) {
    $apsc = \APS\Request::getController();
    $serviceuser = $apsc->getResource($event->source->id);
    // ...
    // Example on tracking the *login* property:
    if($this->owncloudusername != $serviceuser->login) {
    // ... LDAP sync operations must be here ...
    }

    // Now sync the changes with the APS controller:
    $ownclouduser=$apsc->getResource($this->aps->id);
    $ownclouduser->owncloudusername=$serviceuser->login;
    $apsc->updateResource($ownclouduser);
    return;
}

You can practice in development, deployment, and provisioning of a demo package following the Event Processing demo project.

← APS Events

Bind-to-Domain →

Table Of Contents

Previous topic

Next topic

Application Packaging Standard

General Events¶

List of Types ¶

Event Subscriptions ¶

Subscription Structure¶

Subscribing to Events¶

Getting Event Subscriptions¶

Deleting Event Subscriptions¶

Event Notification ¶

Event Processing ¶

Event Subscription Example ¶

Table Of Contents

Previous topic

Next topic

Application Packaging Standard

General Events¶

List of Types¶

Event Subscriptions¶

Subscription Structure¶

Subscribing to Events¶

Getting Event Subscriptions¶

Deleting Event Subscriptions¶

Event Notification¶

Event Processing¶

Event Subscription Example¶

List of Types ¶

Event Subscriptions ¶

Event Notification ¶

Event Processing ¶

Event Subscription Example ¶