Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
ALF/CommonServices/Notification
Contents
Introduction
The purpose of this service is to provide a common notification mechanism that can be invoked from an ALF service flow. The notification service is actually a set of services, a generalized notification service that uses a backend configuration to construct the addressing and message body information and set of services specific the various available notification technologies. This structure was chosen to minimize the changes to any particular interface as new notifications services are added.
Notification Operations
Notify By Profile
void Notify(notificationEnum notificationType[], string notificationProfile, string subject, string body,) throws ALFError.NoNotificationProfile
This operation allows the selection of one or more notification technologies to which the message will be sent.
notificationEnum enumerates the available notification technologies. Initial targets include Email, Pager, SMS and Voice(VXML).
The addressing information is identified by a named notification profile. This profile is preconfigured and must contain the appropriate addressing information for the various notification technologies. For example, Email requires a “to” email address whereas Pager requires “to” pager number and a “from” phone number.
The message sent is constructed from the subject and body as appropriate to the technology the notification is being sent. For example email takes a subject and a body whereas SMS takes only a body. For SMS the notification service sill append the subject and body to form a single string
If the notificationProfile does not contain at least one profile that matches the notification technology selected then ALFError.NoNotificationProfile is raised
Notify By Profile and Template
void Notify(notificationEnum notificationType[], string notificationProfile, string notificationTemplate, nameValue[] content) throws ALFError ALFError.NoNotificationProfile
This operation works like Notify By Profile but instead of taking the message subject and body directly it uses of a named Notification Template and a set of name-value pairs to define the message body. The message sent is selected by providing a name in notificationTemplate. This name identifies a preconfigured notification Template that is used by the service to construct the message. The template contains a message with named substitution fields. As set of name values pairs may be provided. The values are substituted into the message by matching the names to the substitution fields. The template may contain a number of alternative formats for the various notification technologies.
Notification Admin Operations
The Notification Admin service is a separate service from the Notification service. Its intent is to allow remote management of the Notification facility providing a way to add, delete, retrieve and list the various Notification Profiles and Templates
Add Profile
AddProfile(string name, xml profile)
The notification profile is registered with the ALF notification facility using the given name as an identifier. If the name already exists the error ALFError.DuplicateName is raised
The profile will be an XML structure that describes the profile. The exact format is TBD but it will contain one or more notification address profiles for one or more of the notification types. The structue will be extensible to allow the addition of new notification types.
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:annotation> <xs:documentation>WARNING PRELIMINARY DO NOT USE</xs:documentation> </xs:annotation> <xs:complexType name="EmailAddressType"> <xs:annotation> <xs:documentation>An Email address. Email supports multiple addresses in each addressing field</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="Account" type="xs:string"/> <xs:element name="To" type="xs:string"/> <xs:element name="Cc" type="xs:string"/> <xs:element name="Bcc" type="xs:string"/> <xs:element name="From" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:complexType name="PagerAddressType"> <xs:annotation> <xs:documentation>A Pager address</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="To" type="xs:string"/> <xs:element name="From" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:complexType name="SMSAddressType"> <xs:annotation> <xs:documentation>An SMS address</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="To" type="xs:string"/> <xs:element name="From" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:complexType name="VXMLAddressType"> <xs:annotation> <xs:documentation>An VXML address</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="To" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:complexType name="NotificationProfileType"> <xs:annotation> <xs:documentation>A Notification Profile. A valid profile must contains at least one Address instance</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="ProfileName" type="xs:string"/> <xs:element name="EmailNotifications"> <xs:complexType> <xs:sequence> <xs:element name="EmailAddress" type="EmailAddressType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="PagerNotifications"> <xs:complexType> <xs:sequence> <xs:element name="PagerAddress" type="PagerAddressType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="SMSNotifications"> <xs:complexType> <xs:sequence> <xs:element name="SMSAddress" type="SMSAddressType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="VMXLNotifications"> <xs:complexType> <xs:sequence> <xs:element name="VXMLAddress" type="VXMLAddressType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:any minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:element name="NotificationProfiles"> <xs:annotation> <xs:documentation>The set of Notification Profiles</xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="NotificationProfile" type="NotificationProfileType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Here is an example instance
<?xml version="1.0" encoding="UTF-8"?> <!--Sample XML file generated by XMLSpy v2006 rel. 3 U (http://www.altova.com)--> <NotificationProfiles xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="D:\PUBLIC\ALF\Schemas\ALFNotificationProfile.xsd"> <NotificationProfile> <ProfileName>String</ProfileName> <EmailNotifications> <EmailAddress> <Account>String</Account> <To>String</To> <Cc>String</Cc> <Bcc>String</Bcc> <From>String</From> </EmailAddress> </EmailNotifications> <PagerNotifications> <PagerAddress> <To>String</To> <From>String</From> </PagerAddress> <PagerAddress> <To>String</To> <From>String</From> </PagerAddress> </PagerNotifications> <SMSNotifications> <SMSAddress> <To>String</To> <From>String</From> </SMSAddress> </SMSNotifications> <VMXLNotifications> <VXMLAddress> <To>String</To> </VXMLAddress> </VMXLNotifications> </NotificationProfile> </NotificationProfiles>
Get Profile
String GetProfile(string name)
The notification profile associated with the given name is returned. If the name does not exist the error ALFError.UnknownName is raised
Delete Profile
DeleteProfile(string name)
The notification profile associated with the given name is deleted. If the name does not exist then no action is taken.
List Profiles
profileDesc[] ListProfiles()
An array of profile descriptors in returned.
Add Template
AddTemplate(string name, string template)
The notification template is registered with the ALF notification facility using the given name as an identifier. If the name already exists the error ALFError.DuplicateName is raised
Get Template
String GetTemplate(string name)
The notiification template associated with the given name is returned. If the name does not exist the error ALFError.UnknownName is raised
Delete Template
DeleteTemplate(string name)
The notification template associated with the given name is deleted. If the name does not exist then no action is taken.
List Template
templateDesc[] ListTemplates()
An array of template descriptors in returned.
Notification Technology services
void Email(string account, string to, string cc, string bcc, string from, string subject, string body,) throws ALFError.NotificationServiceFault
This operation sends an email using the given email account name.
Pager
void Pager(string to, string from, string body) throws ALFError.NotificationServiceFault
This operation sends a page using.
Short Message Service (SMS)
void SMS(string to, string from, string body) throws ALFError.NotificationServiceFault
This operation sends an SMS message.
Voice (VXML)
void Voice(string to, string body) throws ALFError.NotificationServiceFault
This operation sends a VXML message.