Bind-to-Domain

Purposes

To function properly, many application services need to bind to domains. For example, a web site is usually available in the Internet through its domain name. A 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 (do not confuse these service subscriptions with event subscriptions):

• One contains the main service (parent)

• The other provides a registered domain (child)

The parent service cannot be activated until the bound child service is active. After 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 that event. If the parent service is subscribed to this event it receives the event notification and starts the provisioning process.

An application service can subscribe to the “bind-to-domain” event type, which then allows it to receive an event notification of this type containing the domain name that the service will be bound to.

Event Source

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

• The parent subscription or main subscription provides certain services that need one or more domains.

• Child subscriptions provide the domain registration service. Each child subscription registers a domain in a certain top level domain (TLD) such as .com, .org, co.uk, and so on.

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

Subscribing to Events

The subscribing process is described in the General Events section. When subscribing to an event of the considered type, the 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 (APS ID “46b05c6e-bfa9-43c2-8b40-c3112998dde5”) to the event triggered by the subscription (APS ID “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 properties declared in 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 (APS ID “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

A typical definition of an event handler when using 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 belonging 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 this 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 and helps you create an application package similar to the sample package.

← General Events

Resource Limit Change →