Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
documentation:2.1:notifications [2019/08/29 10:39]
cmaudoux [Notification format]
documentation:2.1:notifications [2020/04/14 22:19] (current)
cmaudoux [Storage]
Line 1: Line 1:
 ====== Notifications system ====== ====== Notifications system ======
  
-LemonLDAP::​NG can notify some messages to users: if a user has got messages, they will be displayed when he access to the portal. If a message contains some check boxes, the user has to check all of them else he can not access to the portal and retrieves his session cookie.+LemonLDAP::​NG can be used to notify some messages to users. If a user has got some messages, they will be displayed when he access to the portal. If a message contains some check boxes, the user has to check all of them else he can not access to the portal and retrieves his session cookie.
  
 A notification explorer is available in Manager, and notifications can be set for all users, with possibility to use display conditions. When the user accept the notification,​ notification reference is stored in his persistent session. A notification explorer is available in Manager, and notifications can be set for all users, with possibility to use display conditions. When the user accept the notification,​ notification reference is stored in his persistent session.
  
 ===== Installation ===== ===== Installation =====
- 
 ==== Activation ==== ==== Activation ====
  
-You just have to activate Notifications in the Manager (General Parameters > Advanced Parameters > Notifications > Activation) or in ''​lemonldap-ng.ini''​ [portal] section:+You just have to activate Notifications in the Manager (General Parameters > Advanced Parameters > Notifications > Activation) 
 + 
 +or in ''​lemonldap-ng.ini''​ [portal] section:
 <file ini> <file ini>
 [portal] [portal]
Line 15: Line 16:
 </​file>​ </​file>​
  
-==== Storage ​====+==== Explorer ​==== 
 +Notifications explorer allows users to see and display theirs accepted notifications. Disable by default, you just have to activate it in the Manager (General Parameters > Advanced Parameters > Notifications > Explorer)
  
 +or in ''​lemonldap-ng.ini''​ [portal] section:
 +<file ini>
 +[portal]
 +notificationsExplorer = 1
 +</​file>​
 +
 +By default, just the three last notifications are displayed. You can modify this by editing ''​lemonldap-ng.ini''​ [portal] section:
 +<file ini>
 +[portal]
 +notificationsMaxRetrieve = 3
 +</​file>​
 +
 +=== Usage ===
 +When enabled, ''/​mynotifications''​ URL path is handled by this plugin.
 +
 +=== Known issue ===
 +An XML document can contain several notifications messages. Just the first one can be searched and displayed!
 +
 +<note important>​
 +Listed notifications are extracted from users persistent session (notification reference and accepted date).
 +ONLY the notifications explorer can found in notifications backend are available to be displayed.
 +Notifications content (title, subtitle and so on...) is not stored into persistent session.
 +</​note>​
 +==== Storage ====
 By default, notifications will be stored in the same database as configuration:​ 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 "​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 "​CDBI"​ or "​RDBI"​ system, the notifications will be stored in the same database as configuration and in a table called ​"​notifications"​. +  * if you use "​CDBI"​ or "​RDBI"​ system, the notifications will be stored in the same database as configuration and in a table named "​notifications"​. 
-  *  if you use "​LDAP"​ system, the notifications will be stored in the same directory as configuration and in a branch ​called ​"​notifications"​.+  * if you use "​LDAP"​ system, the notifications will be stored in the same directory as configuration and in a branch ​named "​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. 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.
Line 78: Line 104:
   * **ldapConfBase**:​ Notifications branch DN.   * **ldapConfBase**:​ Notifications branch DN.
  
 +<​note>​DBI configuration example:
 +<​code>​
 +notificationStorage = DBI
 +notificationStorageOptions={ ​ \
 +    '​dbiChain' ​   => '​DBI:​Pg:​dbname=llng;​host=mabdd;​port=5432',​ \
 +    '​dbiTable' ​   => '​notifications',​ \
 +    '​dbiUser' ​    => '​user',​ \
 +    '​dbiPassword'​ => '​qwerty',​ \
 +    '​type' ​       => '​CDBI',​ \
 +}
 +</​code>​
 +</​note>​
 ==== Wildcard ==== ==== Wildcard ====
  
Line 95: Line 133:
   * <​notification>​ element(s) :   * <​notification>​ element(s) :
     * Required attributes:     * Required attributes:
-      * date: creation date (format YYYY-MM-DD) +      * date: creation date (format YYYY-MM-DD ​WITHOUT time!
-      * ref: a reference that can be used later to know what has been notified and when+      * ref: a reference that can be used later to know what has been notified and when (Avoid ''​_''​ character)
       * 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.       * 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:     * Optional attributes:
Line 108: Line 146:
 <note important>​All other elements will be removed including HTML elements like <​b>​.</​note>​ <note important>​All other elements will be removed including HTML elements like <​b>​.</​note>​
  
-<note tip>One notification XML document can contain several notifications messages.</​note>​+<note tip> 
 +One notification XML document can contain several notifications messages. 
 + 
 +Several notifications can be inserted with a single request by using an array of JSON (Tested with an array of 10,000 elements) 
 +</​note>​
  
 === Examples === === Examples ===
Line 115: Line 157:
  
 <file javascript>​ <file javascript>​
-+[
-"​uid":​ "foo.bar",+"​uid":​ "​foo",​
 "​date":​ "​2009-01-27",​ "​date":​ "​2009-01-27",​
 "​reference":​ "​ABC",​ "​reference":​ "​ABC",​
Line 122: Line 164:
 "​subtitle":​ "​Application 1", "​subtitle":​ "​Application 1",
 "​text":​ "You have been granted to access to appli-1",​ "​text":​ "You have been granted to access to appli-1",​
 +# An array is required to set multi checkboxes
 "​check":​ [ "​check":​ [
   "I agree",​   "I agree",​
   "Yes, I'm sure"   "Yes, I'm sure"
 ] ]
-}+}
 +
 +"​uid":​ "​bar",​ 
 +"​date":​ "​2009-01-27",​ 
 +"​reference":​ "​ABC",​ 
 +"​title":​ "You have new authorizations",​ 
 +"​subtitle":​ "​Application 1", 
 +"​text":​ "You have been granted to access to appli-1",​ 
 +"​check":​ "I agree"​ 
 +}] # No comma at the end
 </​file>​ </​file>​
 +
 +<note tip>JSON format notifications are displayed sorted by date and reference</​note>​
  
 == XML == == XML ==
Line 151: Line 205:
 </​root>​ </​root>​
 </​file>​ </​file>​
- 
-<note tip>JSON format notifications are displayed sorted by date and reference</​note>​ 
 ==== Create new notifications with notifications explorer ==== ==== Create new notifications with notifications explorer ====
  
Line 168: Line 220:
 If enabled, the server URL is https://​auth.your.domain/​notifications. If enabled, the server URL is https://​auth.your.domain/​notifications.
  
-<note important>​If notification server is enabled, you have to protect this URL using the webserver ​because there is no authentication required to use it.</​note>​+Notification server provides three API to insert (POST), delete (DELETE) or list (GET) notification(s). 
 + 
 +Available options: 
 +  * **Server**: Enable/​Disable notification server 
 +  * **Default condition**:​ Condition appended to ALL notifications inserted by notification server 
 +  * **Notification parameters to send**: Notifications parameters returned by ''​GET''​ method 
 +  * **HTTP methods**: Enable/​Disable HTTP methods 
 + 
 +<note important>​If notification server is enabled, you have to protect this URL by using the web server ​because there is no authentication required to use it.</​note>​
  
 Example: Example:
Line 185: Line 245:
 </​file>​ </​file>​
  
-=== XML notifications ​trough ​SOAP ===+=== XML notifications ​through ​SOAP ===
  
 If you use old XML format, new notifications can be inserted or deleted by using SOAP request, once SOAP is activated: If you use old XML format, new notifications can be inserted or deleted by using SOAP request, once SOAP is activated:
Line 248: Line 308:
 </​code>​ </​code>​
  
- +=== JSON notifications ​through ​REST ===
-=== JSON notifications ​trough ​REST === +
- +
-REST server provides three API to insert (POST), delete (DELETE) or list (GET) notification(s). +
-HTTP methods can enabled/​disabled in Manager: ''​General Parameters''​ » ''​Plugins''​ » ''​Notifications''​ » ''​Server''​ » ''​HTTP methods''​. +
- +
-Notifications parameters returned by ''​GET''​ method can be specfied in Manager, ''​General Parameters''​ » ''​Plugins''​ » ''​Notifications''​ » ''​Server''​ » ''​Notifications parameters to send''​. By default: 'uid reference date title subtitle text check'+
  
 == * Insertion example with REST API == == * Insertion example with REST API ==
Line 267: Line 321:
  
 == * Deletion example with REST API == == * Deletion example with REST API ==
 +DELETE API is available with LLNG ≥ 2.0.6
  
 For example with curl: For example with curl:
Line 274: Line 329:
  
 == * List example with REST API == == * List example with REST API ==
 +GET API is available with LLNG ≥ 2.0.6
  
 For example with curl: For example with curl:
 <​code>​ <​code>​
 +# Retrieve '​wildcard'​ notifications
 curl -X GET -H "​Content-Type:​ application/​json"​ -H "​Accept:​ application/​json"​ http://​auth.example.com/​notifications curl -X GET -H "​Content-Type:​ application/​json"​ -H "​Accept:​ application/​json"​ http://​auth.example.com/​notifications
  
 +# Retrieve all pending notifications
 +curl -X GET -H "​Content-Type:​ application/​json"​ -H "​Accept:​ application/​json"​ http://​auth.example.com/​notifications/​_allPending_
 +
 +# Retrieve all existing notifications
 +curl -X GET -H "​Content-Type:​ application/​json"​ -H "​Accept:​ application/​json"​ http://​auth.example.com/​notifications/​_allExisting_
 +
 +# Retrieve all <​uid>'​s notifications ​
 curl -X GET -H "​Content-Type:​ application/​json"​ -H "​Accept:​ application/​json"​ http://​auth.example.com/​notifications/<​uid>​ curl -X GET -H "​Content-Type:​ application/​json"​ -H "​Accept:​ application/​json"​ http://​auth.example.com/​notifications/<​uid>​
  
 +# Retrieve <​uid>/<​reference>​ notification parameters
 curl -X GET -H "​Content-Type:​ application/​json"​ -H "​Accept:​ application/​json"​ http://​auth.example.com/​notifications/<​uid>/<​reference>​ curl -X GET -H "​Content-Type:​ application/​json"​ -H "​Accept:​ application/​json"​ http://​auth.example.com/​notifications/<​uid>/<​reference>​
 </​code>​ </​code>​
- 
 ==== Test notification ==== ==== Test notification ====