stoney cloud: Notification Architecture
Contents
Overview
The pages describes the basic notification architecture and framework.
Its main goal is to provide a script (class) which implements all generic methods used by the different Self-Service Modules to inform the user and/or the reseller. When instantiating the notification object, you only need to provide three parameters:
- The product/service UID (e.g. 4000004)
- The service name (e.g. "backup")
- The problem name (e.g. "quota")
According to these three parameters the notification script
- Connects to the LDAP directory
- Gets the reseller according to the product/service UID from the LDAP directory
- Gets the user and reseller template files (template path and file-ending) from the LDAP directory and according to the reseller
- Uses this template-file to instantiate a perl-template object
- Creates an empty replace-hash
- This empty hash must be set by the Self-Service Module script, using the
setReplaceHash
method.
- This empty hash must be set by the Self-Service Module script, using the
- Checks if the user should be informed about the given problem (according to the LDAP directory)
- If the user should be informed:
- Gets the E-Mail address which should be used to inform the user (according to the LDAP directory)
- Fills in the user template using the replace-hash
- Sends the mail (in future it will be possible to use SMS instead) to the given address
- If the user should be informed:
- Checks if the reseller wants to be informed (according to the LDAP)
- If the reseller should be informed:
- Gets the E-Mail address which should be used to inform the reseller (according to the LDAP directory)
- Fills in the reseller template using the replace-hash
- Sends the mail (in future it will be possible to use SMS instead) to the given address
- If the reseller should be informed:
See also Graphical Workflow
Currently the following Self-Service Modules depend on this notification framework:
Requirements
OpenLDAP directory
Each service needs a notification entry in the form of:
dn: ou=notifications,uid=<RESELLER>,ou=reseller,ou=configuration,ou=<SERVICE>,ou=services,dc=stoney-cloud,dc=org
A settings entry in the form of:
dn: ou=settings,uid=<RESELLER>,ou=reseller,ou=configuration,ou=<SERVICE>,ou=services,dc=stoney-cloud,dc=org
One or more template entries in the form of:
dn: ou=<PROBLEM>,ou=templates,uid=<RESELLER>,ou=reseller,ou=configuration,ou=<SERVICE>,ou=services,dc=stoney-cloud,dc=org
Notifications
The following example shows the backup service notification entry for the reseller with the uid 4000000:
dn: ou=notifications,uid=4000000,ou=reseller,ou=configuration,ou=backup,ou=services,dc=stoney-cloud,dc=org objectclass: top objectclass: organizationalUnit objectclass: sstNotificationObjectClass ou: notifications description: The sub tree stores the notification information for the (online) backup service for the reseller Reseller Ltd. with the uid 4000000. This information is used independently of the notification settings of the users. sstMailTo: Support stepping stone GmbH <support@stepping-stone.ch> sstNotificationWarning: quota sstNotificationWarning: schedule sstNotificationWarning: unsuccessful
Where
- sstMailTo is the e-mail address to which the reseller notifications are sent
- sstNotificationWarning indicates which notifications should be sent to the specified address (sstMailTo), in this the, the reseller would receive notifications concerning:
- backup quota
- backup schedule
- backup unseccessful
Settings
The following example shows the backup service settings entry for the reseller with the uid 4000000:
dn: ou=settings,uid=4000000,ou=reseller,ou=configuration,ou=backup,ou=services,o=stepping-stone,c=ch description: This sub tree stores the information about what can be modified in which scope. objectClass: top objectClass: organizationalUnit objectClass: sstServiceSettingsObjectClass ou: settings preferredLanguage: de-CH sstMailFrom: Support stepping stone GmbH <support@stepping-stone.ch> ...
Where
- sstMailFrom is the e-mail address where the notification mail comes from
- preferredLanguage the language in which the mail will be sent to the reseller
Templates
The following example shows the backup service quota template entry for the reseller with the uid 4000000:.
dn: ou=quota,ou=templates,uid=4000000,ou=reseller,ou=configuration,ou=backup,ou=services,o=stepping-stone,c=ch description: This leaf contains the quota templates for the (online) backup service. objectClass: top objectClass: organizationalUnit objectClass: sstTemplateSetup ou: quota sstMailFrom: Support stepping stone GmbH <support@stepping-stone.ch> sstMailTemplate: file:///var/www/selfcare/htdocs/themes/selfcare.stepping-stone.ch/templates/services/backup/quota/quota_mail sstMailTemplateFormatSource: txt sstMailTemplateFormatTarget: txt sstMailTemplateReseller: file:///var/www/selfcare/htdocs/themes/selfcare.stepping-stone.ch/templates/services/backup/quota/quota_mail_reseller sstMailTemplateResellerFormatSource: txt sstMailTemplateResellerFormatTarget: txt
Where
- sstMailFrom is the e-mail address where the notification mail comes from
- sstMailTemplate is the path to the notification mail (the one which is sent to the user) template
- sstMailTemplateFormatSource is the format (file ending) of the notification mail (the one which is sent to the user) template
- sstMailTemplateFormatTarget is the format (file ending) of the notification mail (the one which is sent to the user) text (all placeholders from the template are now replaced)
- sstMailTemplateReseller is the path to the notification mail (the one which is sent to the reseller) template
- sstMailTemplateResellerFormatSource is the format (file ending) of the notification mail (the one which is sent to the reseller) template
- sstMailTemplateResellerFormatTarget is the format (file ending) of the notification mail (the one which is sent to the reseller) text (all placeholders from the template are now replaced)
File System
In addition to the above explained LDAP Directory entries, the templates specified in sstMailTemplate and sstMailTemplateReseller must be present on the local file system. The notification script would throw an warning if they do not exist (or have wrong permission), but for the notification to work they must be present.
Graphical Workflow
You can modify/update these interactions by editing File:Notification-workflow.xmi (you may need Umbrello UML Modeller diagram programme for KDE to display the content properly).
How to use the Notification.pm module
Given the set up described in section requirements:
Suppose you have the <Service>
"notification" and the <Problem>
"test". The template referenced in the LDAP (ou=test,ou=templates,uid=<RESELLER>,ou=reseller,ou=configuration,ou=notification,ou=services,dc=stoney-cloud,dc=org
) looks like:
Hello {name} This is a notification test from {hostname} Cheers {writer}
You can now write a very simple perl script which will inform the user and the reseller for the service "notification" and the problem "test". All you need to do is:
- Use the notification.pm module
- Create a new instance of the notification class with the following parameters
- service: "notification"
- problem: "test"
- product_uid: <UID>
my $notification = Notification->new( service => "notification", problem => "test", product_uid => $uid, );
- Tell the notification module to connect to the LDAP backend
$notification->connectToBackend( $ldap_server, $ldap_port, $ldap_bind_dn, $ldap_bind_pw, );
- Create the replacement hash
- As you know the template you can easily fill in the replacement hash
my $replace_hash = { name => "World", hostname => $hostname, writer => "Sysadm", };
- Finally set the create replacement hash in our notification object and call the notification method
# Set the replace hash for the notification object $notification->setReplaceHash( $replace_hash ); # And notify user and/or reseller $notification->notify();
As you can see, it is pretty easy to use the notification module if you followed the set up as described in the requirements section.
Error handling
After each method of the notification object, you might want to check whether or not there was an error by calling the error
method (for example after connecting to the backend):
$notification->connectToBackend( $ldap_server, $ldap_port, $ldap_bind_dn, $ldap_bind_pw, ); # Check if the backup connection could be established if ( $notification->error() ) { # Log what went wrong if ( $debug ) { print "Debug: Cannot connect to LDAP server $ldap_server: " .$notification->error()."\n"; } syslog('err',"Cannot connect to LDAP server $ldap_server: " .$notification->error() ); }
$notification->error()
returns the error message if there was an error. If no error occurred, $notification->error()
returns a false value. There is also a method $notification->errorCode()
which returns the error code (numeric value).
Source Code
The source code is located in our GitHub Repository: