Subscription Renewal

Some cloud applications stop providing their services for customers on completion of the respective subscription periods. To continue providing the services in a subscription, the platform generates a renewal order for the next subscription period. Depending on the service plan configuration, this can happen automatically or the subscribers start the renewal process themselves in their user panel.

Event Source and Type

To integrate applications with the renewal process, the platform allows APS connectors to subscribe to the “subscription renewed” event in order to notify the respective cloud applications about the subscription renewal.

The event subscription parameters specific for this case are:

• "event":"http://parallels.com/aps/events/pa/subscription/renewed"

• "source":{"type":"http://parallels.com/aps/types/pa/subscription/1.0"}

Event Processing

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

1. The platform is the publisher of the custom event type "http://parallels.com/aps/events/pa/subscription/renewed". An event source can be only subscriptions represented by APS resources of the PASubscription APS type.

2. An application can subscribe any of its APS resources to events of this type that are triggered periodically in the platform. The recommended event subscriber (also known as event-target) is the resource that implements the subscription service APS type. Only a single resource of that APS type is created in a subscription and therefore it can represent the subscription for the integrated cloud application.

   The easiest way to subscribe every APS resource of a certain type is to declare an event handler subscribed to the subscription renewed event type. In an APS type, a handler declaration may look as shown below:

   "onSubscriptionRenew": {
      "verb": "POST",
      "path": "/onSubscriptionRenew",
      "eventSubscription": {
          "event" : "http://parallels.com/aps/events/pa/subscription/renewed",
          "source": {
              "type" : "http://parallels.com/aps/types/pa/subscription/1.0"
          }
       },
      "parameters": {
          "notification": {
              "type": "http://aps-standard.org/types/core/resource/1.0#Notification",
              "required": true,
              "kind": "body"
          }
      }
   }
   

3. Once the application is subscribed to events of this type, every time the subscription renewal is processed in the platform, the APS controller will send an event notification to the subscribed APS resources, for example:

   POST /vpscloud/events/426ac89c-0db8-4503-84a5-4c086f63ee97/onSubscriptionRenew
   
   {
      "event": "http://parallels.com/aps/events/pa/subscription/renewed",
      "serial": "5",
      "time": "2019-01-30T13:08:16Z",
      "subscription": "c6888c42-ef88-4d5c-a853-d0a233565eb0",
      "source": {
         "id": "127db8b0-f5bf-4799-a645-6b8f89365318",
         "type": "http://parallels.com/aps/types/pa/subscription/1.0"
      },
      "parameters": {
         "startDate" : "2019-01-01T00:00:00Z",
         "expirationDate" : "2019-02-01T00:00:00Z",
         "currentPeriod" : {
            "period" : 1,
            "periodType" : "month"
         },
         "newPeriod" : {
            "period" : 2,
            "periodType" : "month"
         }
      }
   }
   

   In the above POST URL string:

   • vpscloud is the application endpoint path

   • events is the service that receives event notifications addressed to the subscriber

   • onSubscriptionRenew is the handler of the event service that processes on subscription renewed events

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

   • event as the event type ID

   • serial as the serial number of the event (incrementing integer)

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

   • subscription as the APS ID of the event subscription

   • source.id as the APS ID of the APS resource representing the subscription that is being renewed

   • source.type as the APS ID of the PASubscription APS type

   • parameters as the event type specific parameters:

     • startDate as the date and time when the current subscription period starts (or started)

     • expirationDate as the date and time when the current subscription period ends

     • currentPeriod as the length of the current subscription period

     • newPeriod as the length of the new subscription period

In addition to the above mandatory parameters, the parameters section can also contain the following parameters. They are used when the renewed subscription is shutdown or even terminated before the renewal event is triggered:

• shutdownDate - date and time when the subscription was shutdown - typically, at the end of the grace period

• terminateDate - date and time when the subscription was terminated - typically, at the end of the hold period

An event can be generated at different periods of a subscription lifecycle, as illustrated in the following diagram:

← Resource Limit Change

Mail Notifications →