Bind-to-Domain

Purposes

For proper functioning, many application services need to bind to domains. For example, a web site is usually available in the Internet through its domain name. Mail service cannot provide mail boxes without using a domain bound to this service.

That is why, in the platform, it is possible to sell a service plan containing a domain-dependent service and automatically upsell a service plan that registers a domain. Once a customer purchases this product, the system creates two bound subscriptions:

• One containing the main service (parent)
• The other providing a registered domain (child)

The parent service cannot the activated until the bound child service is active. Once the system creates a child domain subscription, it triggers the “bind-to-domain” event and sends the respective event notification to all resources subscribed to the event. If the parent service is subscribed to this event, it catches the event notification and starts the provisioning process.

An application service can subscribe to the “bind-to-domain” event type and thus receive an event notification containing the domain name that the service must be bound with.

Event Source

The up-selling mechanism mentioned earlier involves two types of subscriptions in the platform:

• Parent subscription or main subscription provides any services that need one or more domains.
• Child subscriptions provide domain registration service. Each child subscription registers a domain in a certain top level domain (TLD), for example, “.com”, “.org”, “co.uk”, and so on.

The APS resource representing the parent subscription is the source of the “bind-to-domain” event.

Subscribing to Event

The subscribing process is described in the General Events section. When subscribing to an event of the considered type, the resource-subscriber needs to collect the following data:

• Event ID - http://parallels.com/aps/events/pa/subscription/bindToDomain
• Event source ID - APS ID of the parent subscription
• Event handler - a method defined in the service that manages the resource-subscriber

The following example illustrates a request that subscribes the resource, whose APS ID is “46b05c6e-bfa9-43c2-8b40-c3112998dde5”, to the event triggered by the subscription whose APS ID is “75ef0e91-5b69-4165-b202-adb01972532f”.

POST /aps/2/resources/46b05c6e-bfa9-43c2-8b40-c3112998dde5/aps/subscriptions

{
   "event":"http://parallels.com/aps/events/pa/subscription/bindToDomain",
   "source":{
      "id":"75ef0e91-5b69-4165-b202-adb01972532f"
   },
   "handler":"onBindToDomain"
}

The response indicates that the system has created the requested event subscription and assigned APS ID “9d37af87-b50f-4953-bc2b-21e23083ee7a” to it:

"HTTP/1.1"  "200 OK"

{
   "id": "9d37af87-b50f-4953-bc2b-21e23083ee7a",
   "event": "http://parallels.com/aps/events/pa/subscription/bindToDomain",
   "source":{
      "id": "75ef0e91-5b69-4165-b202-adb01972532f"
   },
   "handler": "onBindToDomain"
}

Notification

In addition to the general event notification schema the “bind-to-domain” event notification schema contains the parameters structure:

{
   "parameters": {
      "type": "object",
      "properties": {
         "id": {
            "type": "string",
            "description": "APS ID of the domain resource"
         },
         "name": {
            "type": "string",
            "format": "domain-name",
            "description": "Domain name"
         }
      }
   }
}

In the following example, the APS controller sends a notification to the contexts service addressing it to the context resource-subscriber, whose ID is “46b05c6e-bfa9-43c2-8b40-c3112998dde5”, and calling the onBindToDomain handler to process the notification:

POST /bind2domain/contexts/46b05c6e-bfa9-43c2-8b40-c3112998dde5/onBindToDomain

{
  "event": "http://parallels.com/aps/events/pa/subscription/bindToDomain",
  "time": "2015-08-05T09:20:01Z",
  "serial": 7,
  "subscription": "9d37af87-b50f-4953-bc2b-21e23083ee7a",
  "source": {
    "id": "75ef0e91-5b69-4165-b202-adb01972532f",
    "type": "http://parallels.com/aps/types/pa/subscription/1.0"
  },
  "parameters": {
    "domain": {
      "id": "86af96b0-793c-4290-805f-0828b77117e6",
      "name": "aps11.test"
    }
  }
}

Using PHP Runtime

Typical definition of an event handler when using the PHP Runtime looks as follows:

/**
 * @verb(POST)
 * @path("/onBindToDomain")
 * @param("http://aps-standard.org/types/core/resource/1.0#Notification",body)
 */
public function onBindToDomain($domainNotification) {
   ## For debugging only - log the input notification
   \APS\LoggerRegistry::get()->info("Domain bound: ".json_format($domainNotification));

   ## Connect to the APS controller
   $apsc2 = \APS\Request::getController();

   ##Impersonate the app to get access to a domain provided by another app - the platform
   $apsc = $apsc2->impersonate($this);

   ## Get APS resource representing the bound domain
   $domain = $apsc->getResource($domainNotification->parameters->domain->id);

   ## Link the *management context* with the domain - add the link to collection paDomains
   $apsc->linkResource($this,'paDomains',$domain);

   ## The rest of the code follows up ....
}

The application needs access to the domain resource belonged to another application - the platform. That is why it works with the APS controller on behalf of the subscriber. This is achieved by calling the impersonate method.

If an application resource needs to subscribe itself to the “bind-to-domain” event, it can do it during its provisioning as in the following example:

public function provision() {

   #### Connect to the APS controller
   $apsc = \APS\Request::getController();
   if ($apsc == null) {
      error_log("apsc is null");
   }

   #### Create a subscription to the "bind-to-domain" event
   $subBindToDomain = new \APS\EventSubscription(
      \APS\EventSubscription::BindServicesToDomain,
      "onBindToDomain"
   );

   #### Create the "event source" object based on the standard class
   $subBindToDomain->source = new stdClass();

   #### Activate the subscription
   $subBindToDomain->source->id=$this->subscription->aps->id;
   $apsc->subscribe($this, $subBindToDomain);

   ## The rest of the code follows up ...
}

In this example, the application uses the EventSubscription::BindServicesToDomain method defined in the APS PHP runtime library.

Demo Project

The Bind-to-Domain Event demo project illustrates the full development and testing process. It helps you create an application package similar to the sample package.

← General Events

Resource Limit Change →