com.sapportals.wcm.service.notificator

Interface Summary
Interface	Description
IAttachmentNotification
ICustomNotification	This interface extends INotification send by a `INotificatorService`.
INotification	This interface defines the notification s send by a notificator .
INotificatorService	Interface to the notification service.

Class Summary
Class	Description
AbstractNotification	Base class for Notifications used to notify a recipient.
MimeUtils	MimeUtils for using mime messages with the notificator.
NotificatorServiceFactory	Service factory for the `INotificatorService`.

Package com.sapportals.wcm.service.notificator Description

Provides a service for sending notifications.

Changes between major releases 7.0 and 7.X
Added classes:
ICustomNotification

Package Specification

Purpose
Interfaces_and_Classes
Code_Samples
Configuration
Implementation_Notes
Related_Documentation

Purpose

The notificator service offers applications and KM components a mechanism for sending notifications to recipients via configured channels like SMS or email. It also provides support for compiling the contents and layout of notifications.

Interfaces and Classes

The notificator service is responsible for performing a number of basic tasks related to sending a notification. It obtains the text and layout for a message and stores them in a notification object. It then sends the notification with the defined layout and text to one or more recipients via a specified channel.

The following introduces the interfaces and classes that are available to access the functions of the service and illustrates their interrelationships with a sequence diagram.

Obtaining the Contents of the Notification

A notification usually consists of standard text and a number of personal details that differ in each notification. In addition, it usually has a specific layout that is suited for a particular communication channel. For example, if a notification is to be sent via SMS then it has a layout that is suited for output on a mobile phone.

At the technical level, a notification is represented by an object that implements the INotification interface. This object stores the contents of the notification and also provides the methods that are necessary to assemble the contents. An application that wants to use notifications must implement the INotification interface or alternatively extend the corresponding abstract class AbstractNotification. Extending AbstractNotification is easier than implementing the interface from scratch as it already supplies a basic implementation for a number of central methods. The following focuses on the AbstractNotification class.

To create the contents of a notification, an application can use the getContent method that is implemented by the AbstractNotification class :
getContent(IRecipient recipient, IChannel channel, java.util.Properties properties)
This method performs a number of steps to assemble the contents of the notification and to prepare its layout. In summary it:

Gets an XML template using an XML producer. The XML template contains the standard text for the notification and placeholders for the variable elements of the text.
Gets an XSL template using an XSL producer. The XSL template contains instructions that are applied to the XML to produce the content of the notification with a layout that is appropriate for the communication channel specified. It ensures that the pipeline can substitute placeholders in the XML with individual text elements appropriate for a specific recipient. To do this, it defines parameter names for each placeholder and explicitly maps these to each other. The values for the parameters (the individual text elements) are supplied by the java.util.Properties object that is passed as an argument to the getContentmethod.
Finally, the pipeline service is called. This applies the XSL template to the XML file and replaces placeholders with their values.

When the pipeline service has completed its work the INotification object is ready to be sent. It contains the content which consists of a standard text supplemented with individual text elements and has a layout that is appropriate for the specified channel.

In the process described above, the XML and XSL producer access an XML and an XSL template. It is the task of the application to supply the appropriate templates and to ensure that these are available in a directory that is specified in the notificator configuration file. For an example of an XML and XSL file, see Code Samples.

The diagram illustrates the process executed by the getContent method.

Sending a Notification

Once the notification object has been prepared, the application can send it to the recipient with the help of the notification service. The INotifcationService interface offers a method for this purpose:
send(IRecipient recipient, IChannel channel, INotification notification)

When the application uses this method, it must specify a recipient, a channel and provide the notification object that stores the content for the message.

The diagram gives an overview of the sequence of actions necessary to send a notification:

Code Samples

The following gives an example a very simple XML and XSL file that an application must provide when it uses the getContent method implemented in the AbstractNotification class as described earlier.

In the example, the parts of the notification text that are always the same are referred to as standard text. The parts that must be replaced by individual text elements (like the name of the recipient) are referred to as placeholder. Note that the values of the parameters in the XSL are provided by the java.util.Properties parameter of the getContent method.

Further examples of XML and XSL files are available in the /etc/notifications folder after the KM installation.

XML File

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE notification [

<!ELEMENT notification (message) >

<!ELEMENT message (#PCDATA)>

<message>standard text:<placeholder/></message>

</notification>

XSL File

<?xml version="1.0" encoding="UTF-8"?>

<?xml-format type="plain"?>

<?wcm-format type="plain"?>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:x="DAV:" xmlns:y="SAP:">

<xsl:output method="text"/>

<xsl:param name="recipient"/>

<xsl:apply-templates select="/notification/message" />

<xsl:template match="placeholder">

<xsl:value of select= "$recipient"/ >

<xsl:template>

</xsl:stylesheet>

Configuration

The notificator service can be configured with the parameters shown in the table.
The parameters can be set with the help of the user interface of the Content Management configuration framework.
For more information, see the documentation Administering Content Management.

The parameters in the table that are not required have default values that are used if no value is specified.

Property	Required	Description
`class`	yes	The class that implements the INotificatorService interface and is be used for this system. Usually com.sapportals.wcm.service.notificator.wcm.NotificatorService
`templates`	no	The repository path with the stored notification templates. Default: /etc/notifications.
`channels`	yes	The channels available for the notificator (IDs which have to be defined by the channel factory). If no channels are configured, no notifications can be sent.
`inbox`	no	The ID of the special inbox-channel (an ID which has to be defined by the channel factory). If an inbox is specified, notifications are sent via the specified channel and additionally posted to this inbox channel.
`originators`	no	A list of channel originators. The channel originators enable the assignment of a sender to a notification so that recipients can see who sent the notifications. If this field is not set, the recipients will not see, who or what sent the notification. It is advisable, to use an administrative account to keep track off wrong email addresses or delivery failures. Channel originators are defined with the help of the channel originator utility.

The following is a sample configuration entry:

service.notificator.class = com.sapportals.wcm.service.notificator.wcm.NotificatorService
service.notificator.templates = /etc/notifications
service.notificator.channels = EMAIL,SMS
service.notificator.inbox = INBOX
service.notificator.EMAIL.originators = notificator.EMAIL, notificator.EMAIL

Implementation Notes

To be able to operate, the notificator service needs a correctly configured channels, scheduler service and XML pipeline. For details on the configuration see the manual the documentation Administering Content Management.

Package com.sapportals.wcm.service.notificator