Table Of Contents

Previous topic

Subscription Renewal

Next topic

Internationalization and Localization

Mail Notifications

The platform built-in Messenger Manager service based on the APS type MessengerManager enables applications to register their own email notification templates and then send email notifications based on those templates to subscribers of that notification.

Email Templates and Message Types

The platform contains a set of predefined email templates used to notify users about some events inside the platform or in the integrated services. A user can be subscribed to notifications based on those templates.

../../../_images/oss-notifications-settings.png

In the platform control panels, an email template represents a registered message type and a set of sections containing the localized message subject and body for the locales activated in the platform. An email template must define the notification subject and body for at least the English locale. The providers can modify some of the fields; they can also translate the subject and message body in the locale sections.

../../../_images/mail-template-domain.png

Note

The English locale is mandatory in an email template. If no other locales are defined in a message type the subject and body of the English locale are copied to all other locales.

A message type contains several fields and provides some variables, for example, ${domain_name}, assigned when a notification based on that message type is sent:

../../../_images/mail-template-editor.png

The Content type informs the system whether the message body is interpreted as a plain text or parsed as an HTML code. When using the text/html content type, there is no need to enclose the message into the HTML <body> tags. However the message body typically contains other markup tags, for example, <h1>, <p>, and <b>.

An application can create its own message types containing the above-mentioned fields and declare its own variables in those types.

Typical Procedure

Typically, an application registers its message types during the installation of an APS application instance and then sends notifications from its scripts implementing the provisioning logic. Therefore, a typical procedure for an application consists of the following steps:

  1. Message types registration. A message type may contain variables whose values the application defines when it sends a message. To register a message type, an application calls the addMessageType method of the MessengerManager service and sends it a message type with the following content:

    • name is an arbitrary (but globally unique) name assigned to the message type.

      Note

      The platform differentiates message types and the respective email templates by names. This means that if an application registers two or more message types, the latest registration overrides all previous message types that use the same name.

    • description is a brief general description of the message type to show it in a platform control panel.

    • subscribeByDefault specifies if by default a new user will be subscribed (true) to notifications of this type or not (false).

    • contentType is an enum variable that can be either “text/html” or “text/plain”.

    • templates is an array of Template structures. Each structure represents a locale and contains the following strings:

      • locale specifies a locale, for example, “en_US”.

      • from is the email From header.

      • subject is the subject of the email notification translated to the corresponding language.

      • body is the translated notification body. This is the actual description of the occasion.

    When registering a message type, the application should store the ID under which the type was registered in the platform. The application will need that ID to send notifications based on the message type.

  2. Sending of the notification. An application sends the notification by calling the sendMessage method of the MessengerManager service. When calling this method, the application must pass an argument as a Message structure with the following content:

    • msgTypeId is the ID of the registered message type.

    • accountId or userId is respectively the APS ID of an account or a user and this way it specifies the addressee to whom the platform will send the notification as explained in the MessengerManager document.

    • params is a named list of variables with assigned values.

Registration

APS PHP Runtime Tools

To help applications register a message type, the APS PHP runtime provides the following components:

  • Class MessengerManager with the full path \com\parallels\www\pa\pa\core\services\messenger\manager\MessengerManager() provides access to the MessengerManager methods.

  • Class Template with the full path \com\parallels\www\pa\pa\core\services\messenger\manager\Template() defines the Template structure as declared in the MessengerManager APS type.

  • Class MessageType with the full path \com\parallels\www\pa\pa\core\services\messenger\manager\MessageType() defines all components of a message type to be registered. It includes an array of the Template structures to present various languages.

Example

For example, an application must notify the customer staff about a new subscription that provides the application services. When provisioning an APS application instance, the application root service called clouds registers a message type in English with the text/plain content type.

In our example, the application’s scripts/clouds.php file contains the following additional definitions for the clouds service:

  1. To save the ID of the registered message types, the class declares an additional property:

    /**
 * @type(string)
 */
public $newSubscriptionNotificationId; # To store the ID of the registered message type

  2. The following private function creates and registers a message type in plain text format for the English locale, as specified in the template structure:

    private function registerMessageType() {

   # Get connection to the Messenger
   $resources = $this->getAPSC()->getResources('implementing(http://www.parallels.com/pa/pa-core-services/messenger-manager/1.0)');
   $messengerManagement = new \com\parallels\www\pa\pa\core\services\messenger\manager\MessengerManager();
   $messengerManagement->aps = $resources[0]->aps;

   # Prepare the message type for the English locale in the plain text format
   $template = new \com\parallels\www\pa\pa\core\services\messenger\manager\Template();
   $template->locale = "en";
   $template->from = '"${vendor_company_name}" <${vendor_tech_email}>';
   $template->subject = "New VPS Demo subscription";
   $template->body = 'The customer ${customerName} subscribed to the VPS Demo application. Subscription APS ID -  ${subscriptionId}';

   # Prepare the full message type to send a Plain Text content
   $textMessage = new \com\parallels\www\pa\pa\core\services\messenger\manager\MessageType();
   $textMessage->name = "New VPS demo subscription";
   $textMessage->description = "New VPS demo subscription is created";
   $textMessage->subscribeByDefault = true;
   $textMessage->contentType = "text/plain";
   $textMessage->templates = array($template);

   # Register the message type
   $textMessage = $messengerManagement->addMessageType($textMessage);
   $this->newSubscriptionNotificationId = $textMessage->id;
}

    Note

    The registered message type declares two variables: customerName and subscriptionId. When sending a notification, the application must specify the values of those variables.

  3. Finally, the standard provision method calls the private function to register the message type:

    public function provision() {
   $this->registerMessageType();
}

In accordance with this example, the application will register its message type during the application deployment on the platform. Once an APS application instance is installed, the provider will see the new email template:

../../../_images/vps-demo-template.png

In the same way, an application can register message types for other occasions, such as provisioning of resources or changing a resource state.

Sending Notifications

Using its registered message type, an application can send notifications to the staff and service users of the customers subscribed to the application services.

APS PHP Runtime Tools

To help applications send an email notification, the APS PHP runtime provides the following components:

  • Class MessengerManager is the same as is used for the registration.

  • Class Message with the full path \com\parallels\www\pa\pa\core\services\messenger\manager\Message() defines the Message structure as declared in the MessengerManager APS type. It must specify the following:

    • msgTypeId is the ID of the message type registered earlier.

    • accountId must be specified to send the notification to all staff members of the specified account.

    • params is a named list that assigns values to the variables declared in the registered message types.

  • sendMessage is the method defined in the MessengerManager class that sends the prepared Message structure through the APS controller.

Example

Continuing with the scenario started in the previous example, the application defines the service for its management context APS type (it is auto-provisioned, that is, started along with the creation of a new subscription) as follows:

class context extends \APS\ResourceBase {
   ## Strong relation (link) to the application instance
   /**
   * @link("http://aps-standard.org/samples/mail/cloud/1.0")
   * @required
   */
   public $cloud;

   ## ... Other properties and methods

   ## Private function to send notifications
   private function sendNotification() {

      $resources = $this->getAPSC()->getResources('implementing(http://www.parallels.com/pa/pa-core-services/messenger-manager/1.0)');
      $messengerManager = new \com\parallels\www\pa\pa\core\services\messenger\manager\MessengerManager();
      $messengerManager->aps = $resources[0]->aps;
      $message = new \com\parallels\www\pa\pa\core\services\messenger\manager\Message();
      $message->msgTypeId = $this->cloud->newSubscriptionNotificationId;
      $message->accountId = $this->account->aps->id;
      $message->params = array(
         'customerName' => $this->account->companyName,
         'subscriptionId' => $this->subscription->aps->id
      );
      $messengerManager->sendMessage($message);
   }

   ## Send a notification when a subscription is created
   public function provision() {
      $this->sendNotification();
   }
}

Key:

  • The management context resource has a relationship with its application instance cloud. The latter enables the script to get the ID of the registered message type using the link
    $this->cloud->newSubscriptionNotificationId.

  • The private function establishes a connection to the APS controller, then assigns values to the required properties including a set of variables (params). Finally, the function sends the prepared message by calling the sendMessage method.

Similarly, an application can register message types and send notifications on various other occasions using the proper provisioning scripts.