System Notifications

This documentation is only relevant for ILIAS 4.4.x and above. This is a work in progress.

The guideline for this can be found at Feature Wiki: System Notification Guideline

ilMailNotification vs. ilSystemNotification

All notifications have to be sent (internally) through ilMailNotification, which provides a technical abstraction and low-level code to handle context-specific settings, e.g. personal workspace permission handling.
ilSystemNotification handles the content structure and should be used whenever possible - the notification will be sent using ilMailNotification. If the guideline rules it supports are too strict for your case you can use ilMailNotification directly (e.g. addBody()), this might be the case for dynamic content as ilSystemNotification only supports lang-ids and has no concept of placeholders.

Basic Usage

The guideline proposes a general structure for system notifications. This structure is supported by ilSystemNotification which should be used for any notification issued automatically (via cron or triggered by an event, e.g. object change notifications).
 
The basic blocks of the structure are:

• Subject
• Introduction
• Object-Information
• Additional Information
• Changed by
• Goto Link
• Task
• Reason

Example 1 (Repository, Module "Exercise")

1
2
3
4
5
6
7
8
9
10
11
12

include_once "./Services/Notification/classes/class.ilSystemNotification.php";
$ntf = new ilSystemNotification();
$ntf->setObjId($ass->getExerciseId());
$ntf->setLangModules(array("exc"));
$ntf->setSubjectLangId("exc_feedback_notification_subject");
$ntf->setIntroductionLangId("exc_feedback_notification_body");
$ntf->addAdditionalInfo("exc_assignment", $ass->getTitle());
$ntf->setGotoLangId("exc_feedback_notification_link");		
$ntf->setReasonLangId("exc_feedback_notification_reason");		
 
include_once "./Modules/Exercise/classes/class.ilExerciseMembers.php";
$ntf->sendMail(ilExerciseMembers::_getMembers($ass->getExerciseId()));

Example 1 Annotations

1. -
2. -
3. The object id to add object title to details and a goto link. It is optional - when missing all object-relevant information is removed from the notification.
4. All relevant language modules are given.
5. Keep in mind to set language ids not parsed strings as they are depending on the recipient language!
6. For custom text blocks you can use setIntroductionDirect() which will be added to the mail without any parsing but you should use this only as a last resort.
7. Additional information is presented either as single line "[caption]: [value]" or multi-line (3rd Parameter)
8. If no specific caption for the goto link is given, the fallback "URL" is used
9. -
10. -
11. -
12. sendMail() has 3 Parameters:

• user_ids
• additional goto suffix, e.g. for sub-"objects" as pages or blog postings
• the permission to check for the goto link (default: "read"), if the check fails the recipient will not get the notification! You can set the permission to null if necessary, e.g. when sending to external email addresses (which should work).

Example 2  (Personal Workspace, "Blog")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

include_once "./Services/Notification/classes/class.ilSystemNotification.php";
$ntf = new ilSystemNotification($a_in_wsp);
$ntf->setLangModules(array("blog"));
$ntf->setRefId($a_blog_node_id);
$ntf->setChangedByUserId($ilUser->getId());
$ntf->setSubjectLangId('blog_change_notification_subject');
$ntf->setIntroductionLangId('blog_change_notification_body_'.$a_action);
$ntf->addAdditionalInfo('blog_posting', $posting->getTitle());
if($a_comment)
{
	$ntf->addAdditionalInfo('comment', $a_comment, true);
}	
$ntf->setGotoLangId('blog_change_notification_link');				
$ntf->setReasonLangId('blog_change_notification_reason');				
 
$notified = $ntf->sendMail($users, "_".$a_posting_id, 
	($admin_only ? "write" : "read"));

Example 2 Annotations

1. -
2. Parameter: Personal Workspace mode aka "Where did my ref_id go?"
3. -
4. If you have a specific ref_id in your context it should be set (instead of setObjId()).
5. If the notification was triggered by an event you can add the "responsible" user (as opposed to cron-jobs)
6. -
7. $a_action: different events lead to different messages.
8. -
9. -
10. -
11. 3rd Parameter: multi-line
12. -
13. -
14. -
15. -
16. 2nd Parameter: goto suffix
17. 3rd Paramter: goto permission

Additional notes

ilSystemNotification does not have a threshold for repeating messages, see ilNotification for that. Attachments and HTML are not supported (yet?). Depending on the user settings the messages will be sent internally or as email.

If there is the need to handle the mail transport separately use composeAndGetMessage().

See ilCourseMembershipMailNotification for an example how to use ilMailNotification directly.