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:
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:
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.
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:
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.
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.To help applications register a message type, the APS PHP runtime provides the following components:
MessengerManager
with the full path \com\parallels\www\pa\pa\core\services\messenger\manager\MessengerManager()
provides access to the MessengerManager methods.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.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.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.
Using its registered message type, an application can send notifications to the staff and service users of the customers subscribed to the application services.
To help applications send an email notification, the APS PHP runtime provides the following components:
MessengerManager
- the same as used for the registration.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.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:
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.