View source for Notification

[[Category:End users]]
[[Category:Portal builders]]
{{FeatureInfo
|editions=wcm,ecm,comm
|fromversion=6.0.4
|wikicomplete=100%
|interest=enduser,builder
}}

{{NewDocs|/docs/notification}}

{{SNTOC}}

=Overview=
{{LeadImage|Notification.png|Notification}} Notification is a feature for users who want to be informed about Content changes in the system. Users can subscribe to notifications on possible changes to the Content. Notifications are email messages sent to the subsriber's address. 
{{clear}}

=Details=
These Content changes can be any kind of change like making a new Content, editing, deleting, renaming, copying or moving an existing Content. These changes can be important for the administrators of the system so we made this functionality to make these users able to know about these changes. The current administrator of the system will receive emails about these Content changes. For these emails custom templates can be set. The administrator can view, edit, delete, activate or deactive these Notifications. For more details about these functions see [[Notification#List_of_Notification_portlets|Notification Portlets]] below.
{{Info|Notification is turned on by default (in versions 6.2 and above). To turn off this feature you have to disable it in the application configuration file. For details, see the [[Notification#Configuration|Configuration]] section.}}

=List of Notification portlets=
*[[Notification activator Portlet]]
*[[Notification delete Portlet]]
*[[Notification editor Portlet]]
*[[Notification list Portlet]]

===Making a Notification===
Notifications can be set up for any Content in the system. They can be added easily in Explore mode. You have to click the dropdown action menu on a Content to get the list of avalaible action on it and then you have to select the ''Set Notification'' action to add a new one. The image below represents this:

{{Screenshot|Notification_add.png|How to set a Notification}}

After this you will see the Edit view of the Notification for creating a new one with defining it's properties. For more details about the Edit view see [[Notification#Editing_Notifications|Editing a Notification]] below.

====Listing Notifications====
To see all the Notifications in the sytem you have to use a Notification List Portlet on a page or you can browse the user's Notifications action. You should see something like this:
{{Screenshot|Notification_list.png|Notification list Portlet}}

For more details see [[Notification list Portlet]].

===Editing Notifications===
When you list Notifications you can simply edit them by clicking the ''Edit'' button. The edit view looks like this:
{{Screenshot|Notification_edit.png|Notification editor Portlet}}
In this edit view you can see the user's e-mail address, the frequency and the language of the notification you are editing and a property for making the notification active or inactive.
{{Warning|A user can not have more than one notification for the same content. Each time they try to set a new one, they will overwrite the previous setting.}}
{{Warning|In this version of Sense/Net notifications are bound to content paths in the repository. That means if the content path is changed, the notifications related to the content will be invalid. }}

===Deleting Notifications===
In the list view you can even delete the Notifications by clicking the ''Delete'' button in the view. The Notification will be deleted at the background the user won't be notified about this. The deleted notification will just disappear from the list view on a successful deletion.

===Notification Admin===
There is a possibility for administrators to manage other users' notifications. This admin page is accessible from the [[Explore]] view. You have to open the user's context menu and choose the ''Notification admin'' action. On this page you can modify or delete the notifications of that user.

=Configuration=
Notification configuration is placed in the "notification" section of the web.config. The section definition is:
<source lang="xml">
<section name="notification" type="System.Configuration.NameValueFileSectionHandler"/>
</source>
==Contents of the section==
===Feature activation===
There is a master switch for on or off the notification feature. Default: "on" that means the notification is enabled: events are collected and mails are sent. Deactivate the feature with this line:
<source lang="xml">
<add key="MasterSwitch" value="off"/>
</source>

{{Info|In versions prior to 6.2 notification is switched off by default. If you want to receive emails, you have to enable it using the MasterSwitch web.config key.}}

===Notification processing===
The notifications are sent periodically in one email per subscription or per user. Events' descriptions in the active periods are aggregated in one email. There are four configurable time frequency. Every frequency can be switched off with the "Never" keyword.
===Emails per user or per subscription===
If the user is subscribed to several different content (e.g. a couple of workspaces), emails may be sent per subscription or aggregated into one email per user. This depends on the following configuration setting:
<source lang="xml">
<add key="GroupNotificationsByUser" value="true"/>
</source>
By default grouping notifications by user is '''enabled'''.

===Instant notifications===
Instant emailing is done only in certain intervals to avoid performance degradation. We recommend that the notification's heartbeat should be a couple of minutes (2-10). The default setting is 5.
<source lang="xml">
<add key="TimerInterval" value="5"/>
</source>

==Configurations for every periods==
===Immediately===
Only the "Never" keyword can be used for switch off the instant mailing. If the instant notification is needed, delete or comment out this line in configuration:
<source lang="xml">
<add key="Immediately" value="Never"/>
</source>
===Daily===
The setting is the time of starting daily event collecting and sending mails. Valid value is: ''[minutes][:][seconds]''. For example:
<source lang="xml">
<add key="Daily" value="01:00"/>
</source>
===Weekly===
The setting is two term: a day of week and a time: ''[DayOfWeek][space][Time]''. Day of week is one of the followings: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. Time setting is the same as in the "Daily" case. Example:
<source lang="xml">
<add key="Weekly" value="Monday 01:00"/>
</source>
===Monthly===
This period can be configured for 3-ways.

1. Specify a day of the month. The valid value is: ''[Every][space][DayNumber][,][space][Time]''. For example:
<source lang="xml">
<add key="Monthly" value="Every 1, 01:00"/>
</source>
2. Specify a week and a weekday of the month. The valid value is: ''[Week][space][DayOfWeek][space][Time]''. Week can be 1st, 2nd, 3rd, 4th. DayOfWeek setting is the same as in the "Weekly" case. Time setting is the same as in the "Daily" case. Example:
<source lang="xml">
<add key="Monthly" value="1st Sunday 01:00"/>
</source>
3. Specify the last weekday of the month. The valid value is: ''[Last][space][DayOfWeek][space][Time]''. DayOfWeek setting is the same as in the "Weekly" case. Time setting is the same as in the "Daily" case. Example:
<source lang="xml">
<add key="Monthly" value="Last Sunday 01:00"/>
</source>
===Boundaries===

*If the setting is "4th Sunday 1:00" and the current month does not have 4 Sunday, the mails will be sent at 3th Sunday.
*Use "Last" keyword instead of 5th weekday.
*If the current month is shorter than the configured "Every" day number, the mails will be sent at last day of the month.
===Summary all setting ways of time periods:===
<source lang="xml">
<add key="Immediately" value="Never"/> <!-- or nothing -->

<add key="Weekly" value="Never"/>
<add key="Weekly" value="Monday 01:00"/>

<add key="Monthly" value="Never"/>
<add key="Monthly" value="Every 1, 01:00"/>
<add key="Monthly" value="1st Sunday 01:00"/>
<add key="Monthly" value="Last Sunday 01:00"/>
</source>
==Performance considerations==
It is recommended that notification processing happens when the server is in a calm period so configure times e.g. sometime at night.
Use longer period for instant mailing e.g. 5-10 (or more) minutes.
Do not use the instant period if it is not important. In this case the "TimerInterval" can be increased.
Do not use the monthly period if it is not important. The event collecting for subscriptions in the longest period can use large amount of memory.
Use the "MasterSwitch" instead of switch off every frequency. If the master switch is on, the events are recorded.
==Notification sending==
Under the notification section you will find five settings regarding to the notification sender componenet of the system:
*NotificationSenderAddress: this email address will be used as sender address in the notification messages.
*RetryCount: if there is any error which interrupts the message sending process (e.g. TransactionFailed) the system will wait for a while (defined in RetryDelay), then try to send the message again. RetryCount specifies the maximum number of these iterations.
*RetryDelay: time interval between two message sending attempts (in millisenconds)
*TakeCount: number of messages which will be retrieved from the message queue in each sending iteration
*MessageEncoding: codepage name which will be used in the messages (e.g. iso-8859-2, utf-8 )

==Sample configuration==
<source lang="xml">
<add key="NotificationSenderAddress" value="noreply@sensenet.com"/>
<add key="RetryCount" value="3"/>
<add key="RetryDelay" value="2000"/>
<add key="TakeCount" value="20"/>
<add key="MessageEncoding" value="utf-8"/>
</source>

=Templating=
Notification messages are emails which are templated by string resources. To modify these messages you should navigate to {{Demo|http://localhost/Root/Localization}} in Explore mode and then edit the ''MessageTemplateResources.xml'' resource file. Templates are multilingual and can be customize according to your needs.

==Notification message structure==
{|class="sn-table"
|- 
| class="dark"| <b>Subject</b>
| ''SUBJECT TEMPLATE''
|-
|class="dark" align="middle"| <b>Body</b>
| ''HEADER TEMPLATE'' <br /> ''...'' <br /> ''CHANGE TEMPLATE'' <br /> ''CHANGE TEMPLATE'' <br /> ''CHANGE TEMPLATE'' <br /> ''...'' <br /> ''FOOTER TEMPLATE''
|-
|}

==Default templates==
===Subject Templates===
{|class="sn-table"
! Name
! Value
|- 
| "ImmediatelySubject"
| Immediate report about document changes
|- 
| "DailySubject"
| Daily report about document changes
|- 
| "WeeklySubject"
| Weekly report about document changes
|- 
| "MonthlySubject"
| Monthly report about document changes
|-
|}

===Header Templates===
{|class="sn-table"
! Name
! Value
|- 
| "ImmediatelyHeader"
| Dear ''{Addressee}'',<br/><br/>Since the last notice, the following changes were made:
|- 
| "DailyHeader"
| Dear ''{Addressee}'',<br/><br/>Since the last notice, the following changes were made:
|- 
| "WeeklyHeader"
| Dear ''{Addressee}'',<br/><br/>Since the last notice, the following changes were made:
|- 
| "MonthlyHeader"
| Dear ''{Addressee}'',<br/><br/>Since the last notice, the following changes were made:
|-
|}

===Change Templates===
{|class="sn-table"
! Name
! Value
|- 
| "DocumentCreated"
| ''{Who}'' created the following content at ''{When}'': ''{ContentUrl}''
|- 
| "DocumentMajorVersionModified"
| ''{Who}'' modified a major version of the following content at ''{When}'': ''{ContentUrl}''
|- 
| "DocumentMinorVersionModified"
| ''{Who}'' modified a minor version of the following content at ''{When}'': ''{ContentUrl}''
|- 
| "DocumentCopiedFrom"
| ''{Who}'' copied the following content from another place at ''{When}'': ''{ContentUrl}''
|-
| "DocumentMovedFrom"
| ''{Who}'' moved the following content from another place ''{When}'': ''{ContentPath}''
|-
| "DocumentMovedTo"
| ''{Who}'' moved the following content to another place at ''{When}'': ''{ContentUrl}''
|-
| "DocumentRenamedFrom"
| ''{Who}'' renamed the following content at ''{When}'': ''{ContentUrl}''
|-
| "DocumentRenamedTo"
| ''{Who}'' renamed the following content to another name at ''{When}'': ''{ContentPath}''
|-
| "DocumentDeleted"
| ''{Who}'' deleted the following content at ''{When}'': ''{ContentUrl}''
|-
| "DocumentRestored"
| ''{Who}'' restored the following content at ''{When}'': ''{ContentUrl}''
|-
|}


===Footer Templates===
{|class="sn-table"
! Name
! Value
|- 
| "ImmediatelyFooter"
| Regards:<br/>Sense/Net 6 System
|- 
| "DailyFooter"
| Regards:<br/>Sense/Net 6 System
|- 
| "WeeklyFooter"
| Regards:<br/>Sense/Net 6 System
|- 
| "MonthlyFooter"
| Regards:<br/>Sense/Net 6 System
|}

==Keywords in templates==
You can use the following keywords inside the templates. They will be replaced with proper values.

{|class="sn-table"
! Keywords
! Subject Templates
! Header Templates
! Footer Templates
! Change Templates
|- 
| {Address}
| align="middle"|{{ok}}
| align="middle"|{{ok}}
| align="middle"|{{ok}}
| align="middle"|{{na}}
|- 
| {Addressee}
| align="middle"|{{ok}}
| align="middle"|{{ok}}
| align="middle"|{{ok}}
| align="middle"|{{na}}
|- 
| {Who}
| align="middle"|{{na}}
| align="middle"|{{na}}
| align="middle"|{{na}}
| align="middle"|{{ok}}
|- 
| {When}
| align="middle"|{{na}}
| align="middle"|{{na}}
| align="middle"|{{na}}
| align="middle"|{{ok}}
|- 
| {ContentUrl}
| align="middle"|{{na}}
| align="middle"|{{na}}
| align="middle"|{{na}}
| align="middle"|{{ok}}
|- 
| {ContentPath}
| align="middle"|{{na}}
| align="middle"|{{na}}
| align="middle"|{{na}}
| align="middle"|{{ok}}
|}

=Custom Notifications=
Besides changing the built-in configurations and templates it is possible to further customize the notification messages and control the notification process using Notification Configs. Please read the following article to learn more:
*[[Custom Notifications]]

=Example/Tutorials=

=Related links=
*[[Custom Notifications]]
*[[Notification activator Portlet]]
*[[Notification delete Portlet]]
*[[Notification editor Portlet]]
*[[Notification list Portlet]]
*[[Table of Contents#Portlets|List of Portlets]]
*[[Portlet]]

=References=