Resource Limit Change

A customer can increase limits on resources in a subscription through the resource upsell or sdk_commerce_addon. Some applications need to be notified when this concerns subscriptions containing the application resources.

Since application resource limits are set in Operations Automation subscriptions, Operations Automation is the publisher of events triggered by changes in Operations Automation resource limits. An application is able to subscribe to such events happening in subscriptions that contain the application resources.

Event Processing

The event processing mechanism is the same as described in the introduction.

1. Operations Automation is the publisher of the custom event type “http://parallels.com/aps/events/pa/subscription/limits/changed”. An event source can be only Operations Automation subscriptions whose APS type is “http://parallels.com/aps/types/pa/subscription/1.0”.

2. An application can subscribe to events of this type that may happen in hosting platform. There are two cases that we should consider.

   • The application subscribes to events on all Operations Automation subscriptions by sending the following REST request to the APS controller:

     POST /aps/2/resources/<subscriberID>/aps/subscriptions
     
     {
         "event": "http://parallels.com/aps/events/pa/subscription/limits/changed",
         "source": {"type":"http://parallels.com/aps/types/pa/subscription/1.0"},
         "handler": "onLimitChange"
     }
     

     In the above code:

     • <subscriberID> - APS ID of the application resource, for example, 426ac89c-0db8-4503-84a5-4c086f63ee97, that must be subscribed to the event type. The service of this resource must be able to receive and process event notifications by means of its declared handler.
     • event - the considered event type.
     • source.type - subscription type ID.
     • handler - a custom method that the subscriber (application service) uses to process events of the specified type.

   • The application subscribes to the events triggered only in a subscription with a certain APS ID by sending the following REST request to the APS controller:

     POST /aps/2/resources/<subscriberID>/aps/subscriptions
     
     {
         "event": "http://parallels.com/aps/events/pa/subscription/limits/changed",
         "source": {"id":"7868ed9c-969c-4a4b-aadd-db9198c711e9"},
         "handler": "onLimitChange"
     }
     

     In this example, source.id is the APS ID of the Operations Automation subscription whose resource limits must be tracked.

3. Once the application is subscribed to events of this type, every time a resource limit in a tracked subscription is changed in Operations Automation, the APS controller will send an event notification to the subscriber whose ID in the above example is 426ac89c-0db8-4503-84a5-4c086f63ee97, e.g:

   POST /vpscloud/events/426ac89c-0db8-4503-84a5-4c086f63ee97/onLimitChange
   
   {
      "event": "http://parallels.com/aps/events/pa/subscription/limits/changed",
      "time": "2014-07-21T14:15:22Z",
      "serial": 11,
      "subscription": "5ee0fe9d-c812-4af8-a969-5ca28077b032",
      "source": {
         "id": "7868ed9c-969c-4a4b-aadd-db9198c711e9",
         "type": "http://parallels.com/aps/types/pa/subscription/1.0"
      }
   }
   

   In the above POST URL string, the following parts are used:

   • vpscloud - the application endpoint path
   • events - the service processing event notifications addressed to the subscriber
   • onLimitChange - the method processing on limit change events

   The HTTP body in the example contains the following JSON attributes of the event:

   • event - the considered event type
   • time - date and time when the event was recorded
   • serial - serial number of the event (monotonic growing)
   • subscription - APS ID of the event subscription
   • source.id - APS ID of the Operations Automation subscription whose resource limits changed
   • source.type - APS type ID of Operations Automation subscriptions

Note

Event notification carries only a reference to the subscription where one or more resource limits have changed. The application itself can go through further steps to figure out which resource limits changed and respectively process the event.

Implementation in APS PHP Runtime

If your APS application endpoint runs in the APS PHP runtime environment, follow these steps to subscribe a resource to an event of this type:

1. Create a subscription object based on the \APS\ EventSubscription class:

   $limitChange = new \APS\EventSubscription(\APS\EventSubscription::SubscriptionLimitChanged,
                     "onLimitChange");
   

   In this example, the event handler is the onLimitChange method.

2. Specify the event source, which must be a subscription ID or subscription type.

   • If the service is linked with the subscription through the subscription link, and the event source must be this particular subscription, then:

     $limitChange->source = new stdClass();
     $limitChange->source->id=$this->subscription->aps->id;
     

     Note

     This is the usual case, when the subscription service linked with the subscription subscribes to this event type and then processes changes in the subscription resource limits.

   • If the service must subscribe to limit change events in all subscriptions containing resources of this application, then:

     $limitChange->source = new stdClass();
     $limitChange->source->type="http://aps-standard.org/types/core/subscription/1.0";
     

3. Register the subscription in the APS controller:

   $apsc = \APS\Request::getController();
   $apsc->subscribe($this, $limitChange);
   

4. Define the event handler, for example, onLimitChange.

Demo

Develop Package

Following this demo, you will subscribe a service to the “limit change” event triggered by the local subscription and define the event handler. For this purpose, use the sample package or a package developed by you in the Generic Services demo project.

The application contains APS type context linked with the subscription through the subscription link. The type and respective service are defined in the scripts/contexts.php file that you should modify as follows.

1. Subscribe to the event when the provision method creates the resource of type context. In the input package, this method was not defined. Add the provision() function and add the code that subscribes the new resource to the required subscription as explained in the implementation section:

   public function provision() {
   
      $apsc = \APS\Request::getController();
      if ($apsc == null) {
         \APS\LoggerRegistry::get()->info("apsc is null");
      }
      $limitChange = new \APS\EventSubscription(\APS\EventSubscription::SubscriptionLimitChanged,
                        "onLimitChange");
      $limitChange->source = new stdClass();
      $limitChange->source->id=$this->subscription->aps->id;
      $apsc->subscribe($this, $limitChange);
   }
   

2. Define a simplest event handler declared in the event subscription:

   /**
    * @verb(POST)
    * @path("/onLimitChange")
    * @param("http://aps-standard.org/types/core/resource/1.0#Notification",body)
    */
   public function onLimitChange($notification) {
      \APS\LoggerRegistry::get()->info("Limit changed: ".json_format($notification));
   }
   

   Event handler onLimitChange records the received event notifications in the PHP log, which by default is /var/log/httpd/error_log.

Verify Application

1. Deploy and provision the application on your sandbox. You do not have to create any VPS.

2. In the provider control panel, open the created subscription and change the limit on the number of VPSes:

   

3. Get access to the endpoint host via SSH connection and ensure the last call of the event handler is recorded in the /var/log/httpd/ssl_access_log file. The record must be similar to the following:

   "POST /limits/contexts/ba26ea02-a4ae-4181-948d-48900ca39014/onLimitChange HTTP/1.1" 200 -
   

4. On the endpoint host, ensure the /var/log/httpd/error_log file contains the message created by the event handler, for example:

   [2015/09/25 10:09:41.000000] INFO Limit changed: {
       "event": "http://parallels.com/aps/events/pa/subscription/limits/changed",
       "time": "2015-09-25T10:09:41Z",
       "serial": 3,
       "subscription": "ac7d24ab-36da-46ee-ac9c-f1cf329548d4",
       "source": {
           "id": "e6653ec2-e43f-473f-9fe2-9fc326d95872",
           "type": "http://parallels.com/aps/types/pa/subscription/1.0"
       }
   }
   

← Bind-to-Domain

Mail Notifications →