Application Packaging Standard

Last updated 18-Mar-2019

Mail Notifications¶

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

In this document:

EMail Templates and Message Types
Typical Procedure
Registration
Sending Notifications

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 presents a registered message type and a set of sections presenting the locales activated in the platform. A message type must define the notification subject and body at least for the English locale. The providers can modify on their own some of the fields as well as they can 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 at the moment 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 should be interpreted as a plain text or parsed as an HTML code. In a case of 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. So, a typical procedure for an application consists of the following steps.

Register message types. A message type may contain variables whose values the application defines when sending a message. To register a message type, an application calls the addMessageType method of the MessengerManager object and sends to it a message type with the following content:
- name is an arbitrary name of a message type, but it must be globally unique.
  
  Note
  
  The platform differentiates message types and respectively email templates by names. It means, if an application registers two or more message types, the latest registration overrides all previous 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 the notification 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 presents a locale and contains the following strings:
  - locale specifies a locale, for example, “en_US”.
  - from is the email From header.
  - subject is the translated subject of the email notification.
  - 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.
Send notification by calling the sendMessage method of the MessengerManager. When calling the method, the application must supply an input argument as a Message structure containing:
- msgTypeId is the ID of the registered message type.
- accountId or userId is respectively the APS ID of an account or a user and it specifies the addressee whom to send the notification. In the former case, the notification is sent to all account staff members, in the latter case to the specified user.
- params is a named list of variables with the 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¶

An application must notify the customer staff about a new subscription providing 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.

The scripts/clouds.php file contains the following additional definitions for the clouds service.

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

The following private function creates and registers a message type in the 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;
}

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 can notice the new email template:

The same way, an application can register message types for other occasions, such as provisioning of resources or changing 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 - the same as 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 - ID of a message type registered earlier.
- userId or accountId - one of them must be specified to send the notification respectively to a particular user or to all staff members of the specified account.
- params - a named list that assigns values to the variables declared in the registered message types.
sendMessage - the method defined in the MessengerManager class that sends the prepared Message structure through the APS controller.

Example¶

To proceed 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 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();
   }
}

Keynotes:

The management context resource has a relationship with its application instance cloud. The latter allows the script to get the ID of the registered message type using the link

$this->cloud->newSubscriptionNotificationId.
The private function gets connected to the APS controller. Then it 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 send notifications on various other occasions using the proper provisioning scripts.

← Resource Limit Change

Internationalization and Localization →

Table Of Contents

Previous topic

Next topic

Application Packaging Standard

Mail Notifications¶

EMail Templates and Message Types ¶

Typical Procedure ¶

Registration ¶

APS PHP Runtime Tools¶

Example¶

Sending Notifications ¶

APS PHP Runtime Tools¶

Example¶

Table Of Contents

Previous topic

Next topic

Application Packaging Standard

Mail Notifications¶

EMail Templates and Message Types¶

Typical Procedure¶

Registration¶

APS PHP Runtime Tools¶

Example¶

Sending Notifications¶

APS PHP Runtime Tools¶

Example¶

EMail Templates and Message Types ¶

Typical Procedure ¶

Registration ¶

Sending Notifications ¶