Resource Limit Change

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

Since application resource limits are set in platform subscriptions, the platform is the publisher of events triggered by changes in resource limits. An application can 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. The platform is the publisher of the custom event type http://parallels.com/aps/events/pa/subscription/limits/changed. An event source can only be subscriptions represented by the PASubscription APS type.

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

   • Case number one: the application subscribes to events on all platform 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> is the APS ID of the application resource - for example, 426ac89c-0db8-4503-84a5-4c086f63ee97 - you want to subscribe 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 is the considered event type.

     • source.type is the subscription APS type ID.

     • handler is a custom method that the subscriber (APS resource) uses to process events of the specified type.

   • Case number two: the application subscribes to only those events that are triggered in a certain subscription 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 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 the platform, the APS controller will send an event notification to the subscriber (whose ID in our example is 426ac89c-0db8-4503-84a5-4c086f63ee97):

   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 is the application endpoint path

   • events is the service processing event notifications addressed to the subscriber

   • onLimitChange is the method processing on limit change events

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

   • event as the considered event type

   • time as the date and time when the event was recorded

   • serial as the serial number of the event (monotonic growing)

   • subscription as the APS ID of the event subscription

   • source.id as the APS ID of the subscription whose resource limits changed

   • source.type as the APS type ID of 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 process the event accordingly.

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. This must be a subscription APS ID or subscription APS type ID.

   • 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 a typical case that illustrates how the subscription service APS resource (linked with the subscription APS resource) 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

By following this demo, you will learn how to subscribe a service with its event handler to the “limit change” event triggered by the subscription the service is provisioned through. 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 must modify as shown here.

1. Subscribe to the event when the provision method creates the resource of type context. If this method was not defined in your initial package, add the provision() function that subscribes the new resource to the required subscription as explained earlier:

   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 the 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));
   }
   

   The 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
   

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

Subscription Renewal →