Notifications system

Since version 0.9.4, LemonLDAP::NG can be used to notify some messages to users: if a user has a message, the message will be displayed when he will access to the portal. If the message contains check boxes, the user has to check all of them else he can not access to the portal and get his session cookie.

Since 1.1.0, a notification explorer is available in Manager, and notifications can be done for all users, with the possibility to display conditions. When the user accept the notification, the reference is stored in his persistent session.

Installation

Activation

You just have to activate Notifications in the Manager (General Parameters > Advanced Parameters > Notifications > Activation) or in lemonldap-ng.ini:

[portal]
notification = 1

Since the 1.2.2 version, notifications are enable by default.

Storage

By default, notifications will be stored in the same database as configuration:

if you use “File” system and your “dirName” is set to /usr/local/lemonldap-ng/conf/, the notifications will be stored in /usr/local/lemonldap-ng/notifications/
if you use “DBI” system, the notifications will be stored in the same database as configuration and in a table called “notifications”.

You can change default parameters using the “notificationStorage” and “notificationStorageOptions” parameters with the same syntax as configuration storage parameters. To do this in Manager, go in General Parameters > Advanced Parameters > Notifications.

File

Parameters for File backend are the same as File configuration backend.

You need to create yourself the directory and set write access to Apache user. For example:

mkdir /usr/local/lemonldap-ng/notifications/
chown www-data /usr/local/lemonldap-ng/notifications/

The file name default separator is _, this can be a problem if you register notifications for users having _ in their login. You can change the separator with the fileNameSeparator option, and set another value, for example @.

To summary available options:

dirName: directory where notifications are stored.
fileNameSeparator: file name separator.

DBI

Parameters for DBI backend are the same as DBI configuration backend.

You have to create the table by yourself:

CREATE TABLE notifications (
  date datetime NOT NULL,
  uid varchar(255) NOT NULL,
  ref varchar(255) NOT NULL,
  cond varchar(255) DEFAULT NULL,
  xml longblob NOT NULL,
  done datetime DEFAULT NULL,
  PRIMARY KEY (date, uid,ref)
)

To summary available options:

dbiChain: DBI connection.
dbiUser: DBI user.
dbiPassword: DBI password.
table: Notifications table name.

Wildcard

The notifications module uses a wildcard to manage notifications for all users. The default value of this wilcard is allusers, but you can change it if allusers is a known identifier in your system.

To change it, go in General Parameters > Advanced Parameters > Notifications > Wildcard for all users, and set for example alluserscustom.

Then creating a notification for alluserscustom will display the notification for all users.

Custom XSLT file

The transformation between notification XML content and HTML display is done with XSLT. The default XSLT file is in portal/skins/common/notification.xsl. You can create your own XSLT file and store in another place, for example /etc/lemonldap-ng. Then just configure the new XSLT file path in Manager, go in General Parameters > Advanced Parameters > Notifications > Custom XSLT file and set for example /etc/lemonldap-ng/notification.xsl.

Using notification system

Notification format

Notifications are XML files containing:

<notification> element(s) :
- Required attributes:
  - date: creation date (format YYYY-MM-DD)
  - ref: a reference that can be used later to know what has been notified and when
  - uid: the user login (it must correspond to the attribute set in whatToTrace parameter, uid by default), or the wildcard string (by default: allusers) if the notification should be displayed for every user.
- Optional attributes:
  - condition: condition to display the notification, can use all session variables.
- Sub elements:
  - <title>: title to display: will be inserted in HTML page enclosed in <h2 class=“notifText”>…</h2>
  - <subtitle>: subtitle to display: will be inserted in HTML page enclosed in <h2 class=“notifText”>…</h2>
  - <text>: paragraph to display: will be inserted in HTML page enclosed in <p class=“notifText”>…</p>
  - <check>: paragraph to display with a checkbox: will be inserted in HTML page enclosed in <p class=“notifCheck”><input type=“checkbox” />…</p>

All other elements will be removed including HTML elements like <b>.

One notification XML document can contain several notifications messages.

Example :

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<root>
<notification uid="foo.bar" date="2009-01-27" reference="ABC">
<title>You have new authorizations</title>
<subtitle>Application 1</subtitle>
<text>You have been granted to access to appli-1</text>
<subtitle>Application 2</subtitle>
<text>You have been granted to access to appli-2</text>
<subtitle>Acceptation</subtitle>
<check>I know that I can access to appli-1 </check>
<check>I know that I can access to appli-2 </check>
</notification>
<notification uid="allusers" date="2009-01-27" reference="disclaimer" condition="$ipAddr =~ /^192/">
<title>This is your first access on this system</title>
<text>Be a nice user and do not break it please.</text>
<check>Of course I am not evil!</check>
</notification>
</root>

Create new notifications with notifications explorer

In Manager, click on notifications explorer and then on the Create button.

Then fill all inputs to create the notification. Only the condition is not mandatory.

When all is ok, click on Create.

Notifications trough SOAP

New notifications can be insert using SOAP request (described in the WSDL file generated by buildPortalWSDL tool). To activate SOAP on the portal:

Enable SOAP in General parameters » Advanced parameters » SOAP
Enable Notifications SOAP service in Apache configuration:

# SOAP functions for notification insertion (disabled by default)
<Location /index.pl/notification>
    Order deny,allow
    Deny from all
    Allow from 192.168.2.0/24
</Location>

Insertion example in Perl

#!/usr/bin/perl
 
use SOAP::Lite;
use utf8;
 
my $lite = SOAP::Lite
        ->uri('urn:Lemonldap::NG::Common::CGI::SOAPService')
        ->proxy('http://auth.example.com/index.pl/notification');
 
 
$r = $lite->newNotification(
'<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<root>
<notification uid="foo.bar" date="2009-01-27" reference="ABC">
<text> You have been granted to access to appli-1 </text>
<text> You have been granted to access to appli-2 </text>
<check> I know that I can acces to appli-1 </check>
<check> I know that I can acces to appli-2 </check>
</notification>
</root>
');
 
if ( $r->fault ) {
    print STDERR "SOAP Error: " . $r->fault->{faultstring};
}
else {
    my $res = $r->result();
    print "$res notification(s) have been inserted\n";
}

You can also delete some notifications with SOAP, once SOAP is activated:

Deletion example in Perl

#!/usr/bin/perl
 
use SOAP::Lite;
use utf8;
 
my $lite = SOAP::Lite
        ->uri('urn:Lemonldap::NG::Common::CGI::SOAPService')
        ->proxy('http://auth.example.com/index.pl/notification');
 
 
$r = $lite->deleteNotification('foo.bar', 'ABC');
 
if ( $r->fault ) {
    print STDERR "SOAP Error: " . $r->fault->{faultstring};
}
else {
    my $res = $r->result();
    print "$res notification(s) have been deleted\n";
}

Test notification

You've simply to insert a notification and connect to the portal using the same UID. You will be prompted.

Try also to create a global notification (to the uid “allusers”), and connect with any user, the message will be prompted.