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
#** Sends the mail (in future it will be possible to use SMS instead) to the given address
The See also [[stoney cloud: Notification Architecture#Graphical Workflow | Graphical Workflow]] Currently the following [[:Category:Self-Service Modules|Self-Service Modules]] depend on this notification framework:
* [[stoney backup: Notification Overview]]
= 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 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
and one 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
** backup unseccessful
=== Settings ===
The following example shows the backup service settings entry for the reseller with the uid 4000000:
<pre>
* '''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:.
<pre>
== 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.
= Configuration =
The notification needs the following configuration:
* Notification
** Backend_service_base: The base object in the backend (LDAP) which contains all services
** People_base: The base object in the backend (LDAP) which contains all people
** Resller_base: The base object in the backend (LDAP) which contains all reseller
** Default_mail_to: If something goes terribly wrong and no-one can be informed write a mail to this address
* Mail
** Host: The mail host to use to send the notification messages
** Port: The corresponding port
** Username: The username to authenticate on the mail host
** Password: The corresponding password
For example:
<pre>
[Notification]
Backend_service_base = ou=services,dc=stoney-cloud,dc=org
People_base = ou=people,dc=stoney-cloud,dc=org
Reseller_base = ou=reseller,dc=stoney-cloud,dc=org
Default_mail_to = support@stoney-cloud.org
[Mail]
Host = mail.tombstone.org
Port = 587
Username = <Sender-Email-Adderss>
Password = verysecret
</pre>
= Graphical Workflow =
[[File:Notification-workflow.jpeg|800px|thumbnail|none|Figure 1: Workflow for the general notification process]]
You can modify/update these interactions by editing [[File:Notification-workflow.xmi]] (you may need [http://uml.sourceforge.net/ 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 | requirements]]: <br/>
Suppose you have the <code><Service></code> "notification" and the <code><Problem></code> "test". The template referenced in the LDAP (<code>ou=test,ou=templates,uid=<RESELLER>,ou=reseller,ou=configuration,ou=notification,ou=services,dc=stoney-cloud,dc=org</code>) looks like (the notification module uses the perl module [http://search.cpan.org/~mjd/Text-Template-1.46/lib/Text/Template.pm Text::Template]):
<pre>
Hello {$name}
This is a notification test from {$hostname}
Cheers
{$writer}
</pre>
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>
<source lang="perl">
my $notification = Notification->new( service => "notification",
problem => "test",
product_uid => $uid,
);
</source>
* Tell the notification module to connect to the LDAP backend
<source lang="perl">
$notification->connectToBackend( $ldap_server,
$ldap_port,
$ldap_bind_dn,
$ldap_bind_pw,
);
</source>
* Create the replacement hash
** As you know the template you can easily fill in the replacement hash
<source lang="perl">
my $replace_hash = {
name => "World",
hostname => $hostname,
writer => "Sysadm",
};
</source>
* Finally set the create replacement hash in our notification object and call the notification method
<source lang="perl">
# Set the replace hash for the notification object
$notification->setReplaceHash( $replace_hash );
# And notify user and/or reseller
$notification->notify();
</source>
As you can see, it is pretty easy to use the notification module if you followed the set up as described in the [[#Requirements | 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 <code>error</code> method (for example after connecting to the backend):
<source lang="perl">
$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() );
}
</source>
<code>$notification->error()</code> returns the error message if there was an error. If no error occurred, <code>$notification->error()</code> returns a false value. There is also a method <code>$notification->errorCode()</code> which returns the error code (numeric value).
= Source Code =