Customizing IBM Lotus Connections 3.0 email digests and notifications

Vincent BurckhardtSoftware Engineer - Lotus Connections DevelopmentIBM Collaboration SolutionsMulhuddart, Ireland

Lorenzo NotarfonzoSoftware Engineer - Lotus Connections IBM Collaboration SolutionsMulhuddart, Ireland

March 2011

© Copyright International Business Machines Corporation 2011. All rights reserved.

Summary: One of the primary new features of IBM® Lotus® Connections 3.0 is the email digest capability, which provides personalized daily and weekly newsletters that are generated based on the activities and updates in the user's social network. This white paper describes how to customize the daily and weekly digests emails, ranging from changing the look and feel of emails to more complex customizations such as adding your company-specific content to the email digests. In addition, this paper also covers customizing individual notification emails sent by the Lotus Connections services.

Table of Contents1 Introduction....................................................................................................................................22 Configuring and administrating email notifications.........................................................................3

2.1 Properties section..................................................................................................................32.2 Default email preferences section..........................................................................................32.3 Channel config – emailChannelConfig section.......................................................................52.4 Template section....................................................................................................................72.5 Enabling and disabling email notifications..............................................................................9

3 Customizing daily and weekly email digests..................................................................................93.1 How the email digest capability works..................................................................................103.2 Customizing email digest messages....................................................................................123.3 Development environment to customize email digest templates..........................................163.4 Step-by-step customization example...................................................................................21

4 Customizing individual notifications.............................................................................................294.1 Individual email templates....................................................................................................294.2 Locating the template file to edit...........................................................................................304.3 Variables and dynamic content............................................................................................304.4 Email template localization...................................................................................................394.5 Examples of individual email template customization...........................................................414.6 Check-in / Check-out scripts to retrieve and update JSP template files...............................45

1

5 Conclusion...................................................................................................................................506 Appendix: Comprehensive overview of all notifications in Lotus Connections 3.0........................52

6.1 Activities...............................................................................................................................526.2 Bookmarks...........................................................................................................................546.3 Blogs....................................................................................................................................556.4 Communities........................................................................................................................616.5 Profiles.................................................................................................................................646.6 Files.....................................................................................................................................666.7 Wikis....................................................................................................................................686.8 Forums.................................................................................................................................706.9 News....................................................................................................................................70

7 Resources...................................................................................................................................718 About the authors........................................................................................................................71

1 IntroductionLotus Connections is a Web 2.0 social software platform for business consisting of several services that enable users to easily cooperate, share information, and execute work items in a collaborative way. An important feature of social software resides around attention management, that is, notifying the end users about the activities and updates going on in the system, based on their preferences.

One of the core aspect of the attention-management system in Lotus Connections takes the form of email notifications. There are various types of notifications sent from the different services that can be split into two main categories:

• Daily and weekly email digests. Digests are personalized newsletters automatically generated by Lotus Connections that provide a snapshot of updates of interest to the recipient in the past day or week. Daily and weekly email digests are new to Lotus Connections 3.0.

• Individual email notifications. Sent for a given action occurring in the system to interested users. Some directed notifications messages can also be sent explicitly by a user in the system to a set of users.

This paper is targeted at a technical audience – administrator and developers – interested in customizing and rebranding the out-of-the-box daily/weekly digest and individual email notifications. On a more general basis, this paper can also be used to get a deeper understanding on how the overall notification mechanisms work in Lotus Connections 3.0.

It is assumed that the reader has a basic knowledge in development using Web technologies (HTML, CSS). It is also recommended that you are able to perform basic administrative tasks on the IBM WebSphere® Application Server deployment hosting Lotus Connections, such as starting/stopping the cluster nodes and editing XML configuration files.

The first section of this paper provides a general introduction of the administrative and configuration aspects of email notifications in Lotus Connections 3.0. The second and third sections deal with customizing email digests and individual notifications emails. A comprehensive reference on existing individual notifications is provided in the Appendix.

2

2 Configuring and administrating email notificationsEmail notifications and digests sent by the different Lotus Connections services can be administered from a single configuration file, notification-config.xml, located under the LotusConnections-config directory (<WAS-directory>/profiles/<Dmgr|AppSrv>/config/cells/<cell-name>/LotusConnections-config/ ).

The notification-config.xml file is divided into four main sections:

• Properties. Located at the top of the file, this section allows the administrator to configure general properties applied to all email messages sent from Lotus Connections.

• Default email preferences setting. Defines the default preferences for email notifications and digests. Users can override the default preferences on an individual basis from the email settings page.

• Email channel config. This section groups the configuration settings related to the SMTP server used to send emails.

• Template. The template files used to define the output of email messages for the different types of notifications sent by the Lotus Connections services (Activities, Wikis, etc.) are referenced in this section. The templates for daily and weekly digests are also defined.

More details on each section are provided below:

2.1 Properties sectionThe “properties” element of notification-config.xml defines some general properties used when notifications are sent by applications.

By default, only one property is listed in this section, “globalSenderEmailAddress”:

<properties> <property name="globalSenderEmailAddress">global-admin@your-email-domain.com</property> </properties>

This property specifies a sender mail address in the case when Lotus Connections is configured to hide email addresses. This global setting can be overwritten in a finer way in the template section, in which an administrator can specify a different sender for each different notification template. More details are given in the 2.4 Template section below.

You can find additional optional properties in the Lotus Connections 3.0 documentation topic, “Defining valid administrator email addresses.”

2.2 Default email preferences sectionAs of release 3.0 of Lotus Connections, users can centrally control the following settings related to email digest and notifications:

• Email address to which Lotus Connections email messages

• Language of the email messages

• Opt to receive direct notifications from other users in Lotus Connections. Note that these direct notifications also appears on the Homepage Updates page, under “Notifications”.

3

• Set the frequency of email notifications for email generated by the different Lotus Connections services, responses to the content the user created, and notifications for the tags. The user can choose whether to receive individual emails, include the notification in the daily or weekly digest messages, or to receive no notification at all.

Figure 1 shows the E-mail Preference setting page (available via the "Settings" link in the navigation page header available across Connections services).

Figure 1. E-mail Preferences page

From the defaultEmailPreference section of notification-config.xml, the administrator can control most of the default settings for email preferences available to all users (see listing 1).

Listing 1. Default settings for email preferences<!-- Sets default email preferences for users who have not set their own preferences. --> <defaultEmailPreferences> <!-- If true, users will be able to override the email address that emails to them will be delivered to. --> <allowEmailAddressOverride>true</allowEmailAddressOverride> <!-- If true, then if the user has not specified a preferred language for emails to be delivered in then the language they last visited the web UI for the component generating the email will be used. This is the default behaviour in previous versions. --> <useLanguageFromCallingComponent>true</useLanguageFromCallingComponent> <!-- If useLanguageFromCallingComponent is false, then if the user has not set their own language preference, this default language will be used. --> <defaultLanguage>en</defaultLanguage> <!-- The default for whether directed notification (sent from one user to another or by the system should be received by email. These notification are also aggregated onto the Home Page. --> <sendEmailsForDirectNotifications>true</sendEmailsForDirectNotifications> <!-- Specifies how email notifications for responses to authored content are sent. Options are INDIVIDUAL (single, immediate emails) DAILY, WEEKLY or NONE. --> <defaultResponsesFrequency>INDIVIDUAL</defaultResponsesFrequency> <!-- Specifies how email notifications updates about tags a user is following are sent. Options are INDIVIDUAL (single, immediate emails) DAILY, WEEKLY or NONE. --> <defaultTagFollowFrequency>WEEKLY</defaultTagFollowFrequency> </defaultEmailPreferences>

4

You may notice that the defaultEmailPreferences section allows you to set only the default frequency for tags and responses. The frequency value is a fixed constant string that can accept only these values: NONE, INDIVIDUAL, DAILY, WEEKLY.

Due to backward compatibility with previous versions of Lotus Connections, the frequency settings for Activities, Blogs, Communities, Profiles, Files, Wikis, and Forums are defined in the template section of the configuration file under the source element, as shown in listing 2.

Listing 2. Frequency settings definitions<source defaultFollowFrequency="DAILY" enabled="true" imagesURL="{notification.source.url}/images/" name="Activities"><source defaultFollowFrequency="WEEKLY" enabled="true" imagesURL="{notification.source.url}/roller-ui/images/" name="Blogs"><source defaultFollowFrequency="DAILY" enabled="true" imagesURL="{notification.source.url}/images/" name="Communities"><source defaultFollowFrequency="WEEKLY" enabled="true" imagesURL="{notification.source.url}/images/" name="Profiles"><source defaultFollowFrequency="DAILY" enabled="true" name="files"><source defaultFollowFrequency="DAILY" enabled="true" name="wikis"><source defaultFollowFrequency="DAILY" enabled="true" imagesURL="{notification.source.url}/images/" name="Forums">

A comprehensive guide on how administrators can changes these settings is available in the Lotus Connections 3.0 Product Documentation topic, “Enabling users to specify email notification preferences.”

2.3 Channel config – emailChannelConfig sectionThe emailChannelConfig section is used to define the configuration related to the SMTP server(s) used by Lotus Connections to send email. In addition, the section is used to define some properties that JavaTM Mail uses during email delivery. There are two ways to reference an SMTP server, using either a:

• Domain Name System (DNS) Mail Exchanger (MX) server resolution. Under this configuration, Lotus Connections performs a DNS lookup to retrieve a list of available SMTP servers. This is the most reliable approach as mail can still be sent, as long as at least one SMTP server is available.

• Reference to a WebSphere Application Server JavaMail provider session. The details of the SMTP server to use are registered in the JavaMail session in WebSphere Application Server. This approach only one SMTP server to be registered – if this single server is down, mail fail to be delivered.

For more information on how to configure email delivery and the backend infrastructure, refer to the Lotus Connections 3.0 documentation topic, “Configuring notifications in IBM Lotus Connections 3.0”.

2.3.1 Using DNS MX server resolutionTo use DNS MX server resolution:

• The property useJavaMailProvider must be set to false.• The smtpJNDILookupURL must point to the DNS server used for the resolution.

For example, see listing 3.

5

Listing 3. Properties for DNS MX server resolution <channelConfigs> <emailChannelConfig> <useJavaMailProvider>false</useJavaMailProvider> <smtpJNDILookup> <smtpJNDILookupURL>dns:mycompny.com</smtpJNDILookupURL> <authentry>smtpAdmin</authentry> <javamail> <property name="mail.debug">false</property> <property name="mail.smtp.connectiontimeout">120000</property> <property name="mail.smtp.timeout">120000</property> <property name="mail.smtp.port">465</property> <property name="mail.smtp.socketFactory.port">465</property> <property

name="mail.smtp.socketFactory.class">javax.net.ssl.SSLSocketFactory</property> <property name="mail.smtp.socketFactory.fallback">false</property> </javamail> </smtpJNDILookup> <maxRecipients>50</maxRecipients> </emailChannelConfig> </channelConfigs>

You can also configure some specific properties that are used directly by the JavaMail framework used by Lotus Connections to send emails through the SMTP servers, such as Debug mode and the timeout value.

2.3.2 Using the WebSphere Application Server JavaMail SessionTo configure Lotus Connections to use a JavaMail Session defined in WebSphere Application Server, the configuration setting useJavaMailProvider must be set to true (see listing 4).

Listing 4. Properties for JavaMail Session <channelConfigs> <emailChannelConfig> <useJavaMailProvider>true</useJavaMailProvider> <maxRecipients>50</maxRecipients> </emailChannelConfig> </channelConfigs>

In this way, the SMTP server configured in the WebSphere Application Server mail session “lcnotification” is used by Lotus Connections. The WebSphere Application Server mail session defines most of the properties related to sending email through the SMTP server.

The mail session is located under Resources – Mail – Mail Session in the WebSphere Integrated Solutions Console. Refer to the WebSphere WebSphere Application Server Version 7.0 Information Center for more details on configuring mail sessions. Figure 2 shows the mail session set by the Lotus Connections Installer in the WebSphere Integrated Solutions Console.

6

Figure 2. Mail Sessions window

NOTE: The properties in the “javamail” section of the configuration file do not apply when the WebSphere Mail Session is used. The javamail properties must be set from the “Mail Session” in WebSphere, under the “Custom properties” section.

2.3.3 Common preferencesIn both the above cases, the administrator can configure the maximum number of recipients per email, using the maxRecipients property. For example, if a given notification must be sent to 100 users, and maxRecipients is set to 50, then two actual emails will be created, each having 50 recipients in the TO field.

This setting is important for performance and must be consistent with the SMTP server throughput so as to not overload or underload it. By default this value is set to 50; however, if the administrator knows that the SMTP server can handle more, the number of recipients can be increased.

This information is collected by the Installer during the install process and is saved in the notification-config.xml file. An Administrator can change the values later on.

2.4 Template sectionThe set of templates used by the different Lotus Connections services to generate the output of the email messages is registered in the template section of notification-config.xml. Here we provide a general overview of the template section; a closer examination of templates is in subsequent parts of this paper.

The templates section defines template files for each type of notification supported by Lotus Connections services, where a service is defined by the “source” name. It is possible to enable or disable the notifications for a given source (i.e., Lotus Connections service), using the attribute named “enabled” in the source tag.

Listing 5 is the extract of the template section of notification-config.xml and shows the definition of two template types for the Lotus Connections Activities service.

7

Listing 5. Extract of template section of notification-config.xml <templates>

[...omissis...] <source defaultFollowFrequency="DAILY" enabled="true" imagesURL="{notification.source.url}/images/"

name="Activities"> <type name="notify" notificationType="DIRECTED"> <channel enabled="true" name="email"> <property name="sender">activities-admin@example.com</property> <property name="url">{notification.source.url}/email/notifyMail.jsp</property> </channel> <channel enabled="true" name="event"> <property name="eventName">activities.notification.notify</property> <property

name="transformerClass">com.ibm.lotus.connections.core.notify.channels.even...</property> </channel> </type> <type name="autocomplete" notificationType="DIRECTED"> <channel enabled="true" name="email"> <property name="sender">activities-admin@example.com</property> <property

name="url">{notification.source.url}/email/autoCompleteActivityMail.jsp</property> </channel> <channel enabled="true" name="event"> <property name="eventName">activities.notification.autocomplete</property> <property

name="transformerClass">com.ibm.lotus.connections.core.notify.channels.event....</property> </channel> </type>

[...omissis...]

</templates>

Important elements in the template section are:

• imagesURL. Templates can have references to images. The imagesURL attribute is used to specify the images directory location. This value sets the root directory of images referenced in the template files.

• defaultFollowFrequency. As mentioned in the “Default email preferences” section above, it is now possible to specify for a given source (Activities, Blogs, Communities, Profiles, Files, Wikis) the default frequency with which the notification are sent. This is done via the attribute defaultFollowFrequency, the value of which is a fixed constant string that can accept the following values: NONE, INDIVIDUAL, DAILY, WEEKLY.

• Sender property. This property is the email address that appears in the “From” field for:

◦ Emails sent automatically from the system, for example, when an activity auto-completes after a period of time. Note that the “From” field of emails sent for directed notifications (a given user sending a message through Lotus Connections to a set of users) is set to the email address of the user at the origin of the notification.

◦ Directed notification in the case when Lotus Connections is configured to not show email addresses. The sender property is also used when the user sending the directed notification does not have an email address. In the case when the sender property is not specified, the globalSenderEmailAddress is used (see “Properties section” above).

8

• Channel. A source can send a notification over two communications channels, email and event; however, the event channel is for internal use and should not be modified:

<channel enabled="true" name="email"> <property name="sender">activities-admin@example.com</property> <property name="url">{notification.source.url}/email/notifyMail.jsp</property>

</channel>

• Url property. The url property specifies the location of the template file used to generate the output of notification emails. The template can be a JSP or FreeMarker template file.

NOTE: The variable {notification.source.url} is resolved at runtime to the source directory containing the template file. The way in which it's done differs from from service to server. Refer to the third and fourth parts of this paper for more details on how this variable is resolved.

2.5 Enabling and disabling email notificationsEmail notifications can be enabled or disabled at any time. This is useful in a number of scenarios, for example, when there is an outage or a maintenance on the SMTP server, to prevent the Lotus Connections services from trying to send emails that would be lost.

The notifications can be disabled as follows:

• At a global level, by editing the value of the “enabled” attribute in the header element of notification-config.xml:

• Per service level, by editing the “enabled” attribute on the service tags in the template section of notification-config.xml. See “Templates section” above for more details.

3 Customizing daily and weekly email digestsAs already mentioned, the email digests feature was introduced in version 3.0 of Lotus Connections and delivers newsletters with personalized content for the recipient on a daily and/or weekly basis.

The Lotus Connections Aggregation service (called Lotus Connections “News”) automatically generates the content of the newsletters based on the activities and updates in the recipient's social network, as well as other elements of interest to the recipient (outlined later in this section).

Figure 3 shows an example of an email message generated by the email digest capability.

9

Figure 3. Example email message

In this section we first introduce how email digest messages are generated by the aggregation service. In that way, you'll have the background knowledge on how to fully customize and extend email messages, depending on your use cases. Then we discuss an overview of the possible customizations of the email digest capability, using a real-world example.

3.1 How the email digest capability worksThe Connections News service delivers email newsletters containing an overview of the elements of interest for the recipient in the past 24 hours (“daily email digest”) or past week (“weekly email digest”).

3.1.1 High-level architecture overviewThe system responsible for generating the email digest messages can be logically separated into the following components:

• Aggregation service. Gathers and aggregates data from all Connections services. Aggregated data is stored in the form of “stories”. A story represents an event or an activity that occurred in Lotus Connections and, as such, stories are generated for almost any user action creating or updating contents in Lotus Connections, for example, creating a new blog post, commenting a wiki page.

The list of “stories”, also called the “river of news” or the “activity stream”, is surfaced in various places in Lotus Connections, notably in the Updates tab of the Homepage service where the News Feed, Discover, and Saved sections of the tab show lists of stories. Besides the river of news in the Homepage, the content of daily and weekly digest messages is also built from the list of stories, divided into categories.

• Templating engine. Responsible for generating the output of the email messages. The generated emails are multi-part messages, including both the HTML output of the email as well as a text version for email clients that don't support HTML.

10

The Aggregation service passes the list of “stories” for a given period – and related to the recipient – to the templating engine, which then renders the email message output based on a supplied template file.

• Email digest scheduler. The scheduler runs a task on a regular basis and is responsible for:

◦ Fetching the set of “stories” for a daily or weekly email from the aggregation service for a given person (the recipient of the email). The settings in the email settings preferences determine what stories are collected.

For instance, if the user opts to not see stories from Connections Activities in the weekly digest, then the set of stories collected for daily digest for this user will not contain any story from Connections Activities. See “Default email preference section” for more details on setting email preferences.

◦ Passing the set of stories to the templating engine, which then invokes the template file to generate the final output of the email message.

◦ Sending the email message with the output returned from the templating engine.

3.1.2 List of stories – content included in email digestsThe stories included in a given email digest message are selected based on the following three criteria:

• Time frame. For daily digests, only events from the past 24 hours are passed to the template engine. Similarly, for weekly digests, only the events from the past seven days are passed to the templates. Note that it is possible for older events to be passed to templates for the very first daily and weekly digest message sent to a given user after the Connections deployment is started.

• The user's email preferences. A user can configure by category what items are included in their daily and weekly digests. The categories correspond to each Connections service, plus tags and responses. The user can also choose not to include a set of stories from a given category in the daily and weekly digests, from the preference page. Refer back to figure 1 and “2.2 Default email preferences section” above for more details.

• Elements that are of interest to the email recipient. In a nutshell, this is based on the content the user is following across Lotus Connections, as well as on the responses to the user's contribution. The next subsection contains a more comprehensive list of the elements that are considered of interest to users by the system.

3.1.3 Notification content and the “Following” concept in Lotus ConnectionsHere are the elements that the system can include in the personalized email newsletter:

• List of responses to the user's contribution across all Connections services. This includes, for instance, any response to the user's Blog entries, Files, Wikis page, etc.

• List of updates from the places and items the user follows. Users can follow a wide range of places and items across Lotus Connections, such as Blogs, Wikis, Activities, and Files. To start following a given item, users click the Follow button in the user interface of the corresponding items (see figure 4).

11

Figure 4. Example of Follow button on Wiki page

Similarly, the user can stop following items from the user interface as well, using the same process as for the following item (button).

Note that after some actions, it is possible that the user automatically follows an item. This is the case, for instance, when the user downloads a file in Connections Files.

• List of updates from people in the user's “social network,” which is the list of the user's colleagues and the list of people who the user follows. For instance, this list would contain information such as any new Blog entry, Bookmark, Wiki page created by people in the user's social network. This list also includes status updates (“micro-blogging”) from people in the user's network.

NOTE: Users can follow and add people to their network through the business card displayed when they hover over any name across Lotus Connections (see figure 5). The business card provides options to follow and add the person as a colleague (Invite to My Network).

Figure 5. Connections Business card

There is no major difference between the colleague and Follow relationships with respect to email digest messages; the stories from both are displayed in the email digest messages.Generally, however, the colleague relationship is “stronger” than the Follow relationship in that the colleague relationship goes two ways and requires validation of the network invitation. Also, users can manage their list of colleagues from the Connections Profiles service.

3.2 Customizing email digest messagesLet's now discuss the aspects of customizing the email digests messages.

12

3.2.1 Customization aspects – template filesCustomization of the email messages is done mainly through the template files. Depending on the range of customization that you want to accomplish, you can either edit the existing template files provided out-of-the-box with Lotus Connections, or create new template files from scratch.

The most common types of customization are:

• Changing the look and feel of the message. This includes updating the background and font colors as well as changing or adding images; for example, replacing the default “Lotus Connections” logo with that of your company. Moreover, you can completely change the layout of the generated email by editing the template files.

• Adding or removing content from the generated emails. To maximize the customization capabilities, the aggregation service passes a larger set of information for stories than the information visible in the default templates. For example, the list of tags associated with each story is passed to the templates, but the default template does not render them. You can choose to render this information in the templates.

• Adding or updating static text. This includes internationalized text.

3.2.2 Location and registration of email digest template filesThe template files used for daily and weekly digests are registered in the notification-config.xml file, in the section “templates” for the source “news”.

The configuration of templates for email digests as seen out-of-the-box on a Connections 3.0 deployment is shown in listing 5. (Recall that Section 2 above, “Configuring and administering email notifications” provides a more general introduction to the options provided in notification-config.xml.)

Listing 5. Templates configuration file <templates><!-- content removed for readability -->

<source defaultFollowFrequency="DAILY" enabled="true" imagesURL="{notification.source.url}/news/email/images/" name="news"> <type name="dailyDigest" notificationType="FOLLOW"> <channel enabled="true" name="email">

<property name="sender">news-admin@example.com</property><property

name="ftl">{notification.source.url}/news/email/dailyDigest.ftl</property><property

name="bundlePath">{notification.source.url}/news/email/</property><property name="bundleName">notification</property></channel>

</type><!-- same type of registration for weekly newsletter with type name=”weeklyDigest” --></source> </templates>

The important aspects in this configuration file are:

• The property “ftl”. The value of this property is the reference to the template file for the corresponding type of email digest. For the daily email digest, it points to the dailyDigest.ftl file with the default value of {notification.source.url}/news/email/dailyDigest.ftl. If you wish to point to a new template file, this is the property to edit.

13

• The properties “bundlePath” and “bundleName”. These point to the base path of the resource bundle files and the resource bundle name. The resource bundles are files containing locale-specific data (translated string of characters) used in the email digest messages.

The data (strings of characters) in the resource bundles for the locale of the recipient is made available programmatically in the template as described below in “3.4.4 Handlinginternationalization“.

• The property “sender”. This is the email address of the sender of the email digest message (“From” field in the received emails).

• The attribute “imageURL” in the source tag element. This attribute points to the root directory in which are stored the images embedded in-line in the defined type of email notifications (daily and weekly digests, and individual messages, in the case of the “news” application).

• The “enabled” attribute in the source tag element. Offers the possibility to enable and disable notifications (daily and weekly emails).

• The “channel” element in the configuration file. This is used for internal purposes. It is not recommended to edit this element for the purpose of customization.

NOTE: In the properties and attributes described above, the syntax “{notification.source.url}” refers to a variable pointing to the root of the Connections configuration directory. This variable is resolved to the correct directory on the server file system and is required, as the name of the directories can change depending on factors specific to the WebSphere Application Server deployment.

In addition, the template files and configuration files are replicated across all servers and nodes constituting a cluster deployment of Lotus Connections. For instance, on the deployment manager server, the property value “ftl” is resolved to “<WAS>/profiles/<Dmgr>/config/cells/<cell-name>/LotusConnections-config/news/email/dailyDigest.ftl”.

3.2.3 FreeMarker – templating engineFreeMarker is the templating engine used by Lotus Connections to generate the daily and weekly email message output. Consequently, the templates file provided for email digests are written following the FreeMarker templating language.

The official FreeMarker documentation provides a quick tutorial that contains most of the information you need to know on the basics of FreeMarker templating language to customize templates for email digests. It is strongly recommended to refer to this documentation in order to fully understand the examples in this paper.

You can also refer to the full FreeMarker documentation to get an advanced overview of the capabilities of the templating language.

3.2.4 Structure of the out-of-the-box daily and weekly template filesAs outlined in the “Location and registration of email digest template files” section above, the properties for daily and weekly digests in notification-config.xml are configured by default to point to two main template files:

• dailyDigest.ftl, responsible for generating the output of the daily newsletters messages• weeklyDigest.ftl, responsible for generating the output of the weekly newsletters messages

14

The template files are located under the /news/email directory in the LotusConnections-config directory. The LotusConnections-config directory is the location under which most configuration files for Lotus Connections are located. The template files for email messages – including email digest messages – using the FreeMarker templating engine can be found under that directory, located under

<WAS-directory>/profiles/<Dmgr|AppSrv>/config/cells/<cell-name>/LotusConnections-config/

The content of the directory is replicated across all the servers of the deployment. The “Step-by-step example of customization” section below has additional information on how to edit the content of these templates for real-world scenarios.

The daily and weekly digest template files leverage two additional files, style.ftl and util.ftl (both under <LotusConnections-config>/news/email/aggregated), for common capabilities and styling. The two files are included in the template files through the FreeMarker directive <#import> and provide the following functionality:

• style.ftl. This template file defines the following additional macros used in both the daily and weekly digest template:

◦ Macro “document”: Generates the heading part of the HTML document sent as part of the email digest messages. The set of Cascading Style Sheets (CSS) styles defining the look and feel of the email digest are declared in this macro.

◦ Macro “digestHeader”: Renders the visual header of the daily and weekly digests, which corresponds to the blue box at the top of the email messages, giving the date of the digest and containing the Lotus Connections logo. Note that this macro delegates some of the work to another macro called “newsletterEmailHeader” defined in the same file.

◦ Macro “digestFooter”: Renders the footer of the email message, that is, the box with a link directing the user to the email-digest setting preferences page.

◦ Macro “digestSection”: Renders the HTML code for each section of the email digest messages. This macro is called for each category by dailyDigest and weeklyDigest.ftl templates. The term “section” refers to the different categories of items, such as responses or updates to the category of the item, followed by the recipient of the email.

Figure 6 shows the macros responsible for generating the HTML (and text) output of the different sections of the email digest message.

15

Figure 6. Macros and their corresponding sections of the email digest message

• util.ftl. This is the set of utility and helper functions used in various places in email digest templates. In particular, it defines the function “resource” to access the strings located in the resource bundle, depending on the locale of the recipient (see the “Handling internationalization” section below).

3.3 Development environment to customize email digest templatesThis part provides more details on the development environment to customize email digest templates in an efficient way.

It is assumed that your Lotus Connections deployment is already properly configured for sending notifications. Refer to the Lotus Connections 3.0 documentation topic, “Configuring notifications,” for more details.

3.3.1 Working on a single-node deploymentThe template files and resources for daily and weekly digest are replicated on all servers/nodes constituting the Connections deployment cluster. For development purposes, it is recommended to work on a test deployment with a cluster of a single node.

This way, you can deploy or edit directly the template files on the single-node machine and test the modifications without having to do any further synchronization steps to propagate the files, allowing a faster development flow.

Section “3.4.5 Deploying customized template and resources files to a production environment,” describes the steps to synchronize the files in a production environment with several nodes.

3.3.2 Forcing the system to deliver an email digest message immediatelyTo facilitate the development effort, an action – in the form of a URL – can be “hit” to trigger immediately the generation of an email containing the same output as a standard daily or weekly email message. The generated email is sent only to the authenticated user who hit the action (for example, the developer).

16

The URL of the action is located at:

http://<server:port>/news/web/testEmailDigestSendMail.action

Note that the context root of the News application is “/news” by default. Make the necessary adjustments in the above URL if the context root was changed on the deployment used for development.

Accessing the URL of this action triggers the following processes in order:

1. The system gathers all stories related to the authenticated user. The stories are gathered in exactly the same way as for daily- and weekly-digest scheduled tasks in normal operation, except that there is no time box to define which stories are included in the mail – as opposed to the “real” daily / weekly newsletter in which only the stories created in the past 24 hours / 7 days are considered.

NOTE: As for daily and weekly digests, the email user preferences are also used to define which stories are gathered from the system. When working on a daily digest template, make sure that the email preferences of the currently authenticated user are set to “Daily Newsletter” and likewise for the weekly digest, for which the settings should be set to “Weekly Newsletter”.

2. The daily template files configured in notification-config.xml are “invoked” by the templating engine with the list of stories gathered from the system.

NOTE: You can append the request parameter type=weekly to force the system to use the weekly digest template file. Example: http://<server:port>/news/web/testEmailDigestSendMail.action?type=weekly

3. The generated output message is sent to the email address of the authenticated user that hit the action.

Note that the email address used is the one configured in the email settings page, so ensure that the email address is correct for the authenticated user on that page. You may need to change the default settings of allowEmailAddressOverride in notification-config.xml to be able to edit the email address in the settings page for testing purposes (see “Default email preferences section” in “Configuring and administrating email notifications”).

Additionally, no email is sent if there is no story for the user who hit the action. Since the stories included in the email digests are the same as displayed in the Connections Homepage News Feed, the easiest way to verify there are stories for the current user is to check the content of Homepage, as follows:

◦ On the Lotus Connections Homepage, click the “Updates” tab.◦ Select “News Feed” on the navigation bar.◦ Verify that the list of stories is not empty.

Figure 7 shows a News Feed displaying stories in the main section. The same stories are included in the email digest messages.

17

Figure 7. News Feed stories

To add new stories for testing purposes, one approach is to create content in places you follow, such as creating a blog you follow:

1. On the Lotus Connections Blogs “My Blogs” tab, click “Start a Blog”.

2. Enter some values for the new blog and click Save.

3. Access the blog you just created from the My Blogs tab.

4. On the top left-hand corner, click the Follow this Blog button. From this point on, any action you make in this blog, for instance, creating a new blog entry, will generate stories that are included in the email digest of that user (and in the Homepage News Feed view).

In the top half of figure 8, user A, “Betty,” creates a new blog entry that is followed by user B. User B sees the story on the creation of the new blog entry in the Homepage Updates page (“News Feed” section).

18

Figure 8. Newly created blog entry followed in the News Feed section

3.3.3 Enabling the server trace log related to email digestsThe server trace log details related to email digests are:

freemarker.*=all: com.ibm.lconn.news.service.impl.emd.*=all: com.ibm.lotus.connections.core.notify.*=all: javax.mail.*=all

Refer to the WebSphere Application Server documentation topic, “Enabling trace on a running server,” for details on enabling the trace logs.

In addition to enabling the trace log above, enable the debug mode for the Connections mail session. If the WebSphere Java Session is used to reference the SMTP server in your deployment, then:

1. In the WebSphere administrative console, select Resources – Mail – Mail Sessions.

2. Select the Lotus Connections mail session (named “lcnotification” by default).

3. Place a check the “Enable debug mode” box and validate by clicking OK.

If DNS MX is used to reference a pool of SMTP servers on your deployment, then set the “mail.debug” property to true in notification-config.xml. See “2.3 Channel Config – Email Channel config section” above for more details.

By turning on the logs, the output and the error messages from the FreeMarker templating engine are visible, allowing you to troubleshoot errors, such as syntax errors in the email template files that you write or modify.

19

Figure 9 is an example of a syntax error in the template file surfaced as an error in the trace.log file of the cluster node hosting News and generating the email digests.

Figure 9. Example syntax error in template file

3.3.4 Viewing the message source output in IBM Lotus Notes®In addition to using the server-side trace logs to view the output of the email digest messages, most common email clients provide a way to view the source of the message. In Lotus Notes 8.5, you can view the source of a message via View – Show – Page Source in email (see figure 10).

Figure 10. View page source option in Lotus Notes 8.5

Email digest messages are MIME multi-part messages, in which multiple parts of information are sent as part of the same message, as follows:

• HTML content• Text-only content• Embedded images

20

Each part of the message is delimited by a boundary, which starts with the characters “----” in email digest messages, with the exact boundary sentence given in:

Content-Type: multipart/related; boundary="----=_Part_64_434641384.1289257769762"

The HTML content part of the messages generated from the templates starts after the boundary:

------=_Part_64_434641384.1289257769762Content-Transfer-Encoding: 7bitContent-Type: text/html;charset=UTF-8

Figure 11 shows the source of an email as seen in Lotus Notes 8.5. Notice the two parts of the message, the text and HTML outputs, separated by the boundary above.

Figure 11. Source of an email in Lotus Notes

3.4 Step-by-step customization exampleUsing a real-world example, we now address the most common customization steps, specifically:

• Replacing the default “Lotus Connections” logo• Changing the color theme of the message• Adding new content to the generated newsletter

To be close to a real scenario, let's re-brand the digest messages to the Lotus Knows theme, which represents an advertising campaign with a strong graphical identity based on its own logo and the black and orange colors. You can then adapt the steps to match your own company's look and feel.

21

The customized files are attached in the Download, emailDigestCustomizations.zip, accompanying this paper. The steps involved are:

• Changing the “Lotus Connections” logo in the newsletter to the “Lotus Knows” logo• Changing the background and font colors of the newsletter to match the ones (black,

orange) of the “Lotus Knows” theme• Adding a link below each story in the newsletter, to allow the recipient to open the

corresponding item directly in a Web browser.

Figure 12 shows the original theme of the Connections 3.0 email digest messages.

Figure 12. Original “theme” of the email digest messages

Figure 13 shows the same message after the new Lotus Knows theme has been applied.

22

Figure 13. Email digest message with the new Lotus Knows theme applied

Figure 14 shows the story with new “Open item in browser” link allowing the recipient to open the item directly in a Web browser.

Figure 14. New link added

3.4.1 Replacing the logo in email digest messagesLet's go through the steps to replace the Lotus Connections logo (see figure 15) at the top of the email digest messages with the Lotus Knows logo (see figure 16).

Figure 15. Email digest header bar with standard Lotus Connections logo

Figure 16. Email digest header bar with custom Lotus Knows logo

1. Add the image for the logo under the directory LotusConnections-Config/news/email/images. Notice this is the directory pointed to by the imageURL attribute of the node “source” in

23

notification-config.xml, as mentioned above in the “Location and registration of email digest template files” section.

Any standard image format can be used (.jpg, .gif, .png are the main ones); however, note that some older email clients cannot render .png images properly. In this example, we use the image named “LotusKnows.jpg”, which is included in the Downloads (inside emailDigestCustomizations.zip) accompanying this paper.

2. Edit the file style.ftl (located under the LotusConnections-Config/news/email/aggregated directory) with any standard text editor.

3. Look for the section defining the macro named “newsletterEmailHeader”, which is responsible for generating the HTML code of the header. The exact HTML line for the logo image is:

<img src="cid:LotusConnections-BlackBrick.png" alt="${u.resource("LOTUS_CONNECTIONS_ICON_ALT")}"/>

NOTE: The images are embedded as a “parts” of the multi-part message sent to the client. Each part is identified by a unique “Content ID”, or “cid”, for short. For images, the content ID is set to the filename of the image by Lotus Connections. The “cid:” defined in the src element is therefore pointing to the embedded image mentioned in step 1.

By using an embedded image, the email client doesn't need to fetch the image from a remote server when the recipient opens the email messages. In addition, most modern email clients block the remote images by default for security reasons, and it would require an action from the recipient to see the images in the email, including the logo.

4. Edit the HTML tag element in step 3 to point to the new logo image:

<img src="cid:lotusKnows.jpg" alt="${u.resource("LOTUS_CONNECTIONS_ICON_ALT")}"/>

5. In addition to changing the logo image, we must change the alternative text that is displayed in place of the image, in case images are disabled on the email client or when the recipient uses accessible technologies, such as a screen-reader software application.

<img src="cid:lotusKnows.jpg" alt="Lotus Knows Logo"/>

In this step, the text is changed directly in the template file. Though this is the easiest approach, it is not recommended if your deployment supports multiple languages, as the same alternative text is displayed regardless of the preferred locale of the recipient. The “Handling internationalization” section below has a full example involving externalizing the strings used in the email digest to allow them to be translated.

3.4.2 Modifying the styles of the messagesHere we show how to modify the visual theme of the email digest messages. We go through the concrete example of updating the color scheme of the message from the “blue-ish” out-of-the-box Connections theme to a new color scheme based on black and orange colors.

In this example (see figure 17):

• The background color of the header is replaced with a dark-grey (almost black) background, and the initial black font color of the header becomes white.

• The background color of section headers is changed from light blue to orange.• The background of the footer is changed from white to dark grey.

24

Figure 17. New email digest message styles applied in this section

The visual appearance of the email digest messages is controlled through CSS styles, like any traditional HTML page. As introduced above, the styles of the default templates are centralized in the style.ftl file, specifically, in the macro named “document”.

Changing the background and font colors of the message headerTo update the styles for your customization needs, the first step is typically to find the HTML element(s) and CSS class(es) to modify. You can do this either by analyzing the existing template source code or by looking at the output of the HTML message (see 3.3.4 Viewing the messagesource output in IBM Lotus Notes®).

For our current example, if you look at the output of the message, you can determine that the header of the email digest messages is defined as an HTML row element (“tr” element) with the CSS class “newsletterEmailHeader”. The CSS class “newsletterEmailHeader” is defined as such in style.ftl:

.newsletterEmailHeader { background-color: #728bb4; border-color: blue; border-style: solid; }

Consequently, to replace the default color, we simply change the background color (blue; hexadecimal value #728bb4) to the new color (dark grey; hexadecimal value 333333). In addition, the font color is overridden from the default black to white (hexadecimal value #FFFFFF) through the “color” CSS . The new definition of the style newsletterEmailHeader is:

.newsletterEmailHeader { background-color: #333333; color: #ffffff; border-color: blue; border-style: solid; }

Modifying the background color of the section headersIn this example, the section header color is changed from light blue to orange as was shown in figure 17.

As with the previous step, looking at the generated HTML code of the messages shows that the section headers are table row elements. These elements are generated by the macro named “digestSection” defined in style.ftl. The following CSS class element controls the style on this element:

.newsletterHeadingRow { height: 32px; background-color: #f5f6f7; }

which we edit to change the background color to orange (F7C01F in hexadecimal):

.newsletterHeadingRow { height: 32px; background-color: #F7C01F; }

The principle of editing the color of the footer is the same as above. The source code of the final templates is in the Downloads (emailDigestCustomizations.zip)

25

3.4.3 Adding new content to the email digestThe dataset passed to the templates is larger than the information visible in the default messages provided out-of-the-box in Lotus Connections 3.0. You can choose to display additional information related to stories in the messages, depending on your need.

The dataset is passed to the templates in the form of a property named emailDigestBean, which is an instance of a Java class implementing the interface IEmailDigestStoriesContainer. The Javadoc for interfaces of the beans available in email digest templates is in the Documentation topic, “Lotus Connections 3 Email Digest.”

This instance is already populated by the aggregation service with a dataset specific to the recipient (list of stories classed by categories). The default templates use this property heavily to output the digest messages by iterating through the different categories. It is recommended that you become familiar with the way this property is used by looking at it in the default templates.

IEmailDigestStoriesContainer defines three main getters that can be used from the template:

• getStories(). Returns the list of stories by category for the recipient of the digest message. The dataset available for each story is defined by the interface IemailDigestStory (see Javadoc link, “Lotus Connections 3 Email Digest.”)

• getBegin() and getEnd(). Returns the date range for the stories included in the message.

• getStoriesStats(). Returns the total number of stories by category for the time period. For performance reasons, getStories (the first bullet) returns only the five latest stories per category and cannot be used to get the total number of stories for the time period.

We show how use this property, using an example in which we add links under each story in the digest messages pointing to the page of the entry related to the story in Lotus Connections. The links are labelled “Open item in browser” (see figure 18).

Figure 18. Open item in browser link added to each story in the digest message

Here are the steps:

1. Consult the Java Doc documentation to see whether the information to surface is available. In the case of this example, IEmailDigestStory exhibits a getter named getEntryHtmlUrl returning the URL of the page for the entry in Lotus Connections corresponding to this story.

2. Locate the place to add the additional information in the default template. In our link example, looking at the generated HTML output, you can see that each story title is generated as a table row in the macro named “digestSection” in the file style.ftl.

3. The process is thus to modify the macro to add an additional table row for each story with the link to the entry. By looking at the source of the macro, you can see that each row of the message is generated through a loop iterating across all stories of a given category with the FreeMarker declaration <#list stories as item> .

Note that each story is referred through the variable named “item” in the loop. The code snippet in listing 6 is added at the end of the loop to produce the “Open item in browser” link.

26

Listing 6. Code added at end of loop<tr class="newsletterDoubleLineRow">

<td></td><td colspan="2">

[<a href="${item.entryHtmlUrl}">Open item in browser</a>]</td>

</tr>

Note that the table row follows the format (number of column and colspan) of the row for the stories defined in the same macro, thus ensuring proper visual alignment.

3.4.4 Handling internationalizationUntil now, all the strings have been added directly inside the template files. This approach is appropriate in the case of a single-locale Lotus Connections deployment, in which all users speak the same language. However, if multiple languages are supported, the strings must be externalized from the template files to separate files – called “resource bundles” – containing locale-specific strings.

By default, all the strings of the default template are externalized in files named

notification_<locale>.properties (located under <LotusConnections-Config>/news/email directory)

where “<locale>” is the locale code of the language (for example, “en” for English, “fr” for French).

In resource bundles, each string is identified by a unique key. The string in the resource bundle corresponding to the language of the recipient is loaded and made available from the template. It is recommended to use the helper function “resource” (defined in util.ftl) to access the strings and optionally apply parameters:

<#function resource messageKey params...>

If the following key/value pair is defined in the resource bundle file “notification_en.properties:”

RESOURCE_KEY=Example bundle string with parameter: {0}

then the following statement in the template file:

${resource(''RESOURCE_KEY”, “a param”)

outputs the string, “Example bundle string with parameter: a param”, when the locale is English (en).

For example, let's externalize the message, “Open item in browser”, as follows:

1. Add the following line in notification.properties and notification_en.properties:

OPEN_ITEM=Open item in browser

NOTE: notification.properties is the default bundle that's used when the key is not found in the locale-specific bundle file. This allows you to, at least, display a message in English in case there is no translation available in some other languages.

2. Add the corresponding string in French in notification_fr.properties:

27

OPEN_ITEM=Ouvrir élément dans navigateur

3. In the template file style.ftl modified in the previous set, replace the “hardcoded” string

<a href="${item.entryHtmlUrl}">Open item in browser</a>

with:

<a href="${item.entryHtmlUrl}">${u.resource(“OPEN_ITEM”)}</a>

3.4.5 Deploying customized template and resources files to a production environmentTo deploy the customized template files and associated resources (images) onto a production environment, the recommended steps are to:

1. Deploy the customized template files onto the Deployment Manager (DM) node of the deployment. The email digest template files for email digest are located under

<WAS-install>/AppServer/profiles/<Dmgr>/config/cells/<cellName>/LotusConnections-config/news/email

You may also deploy any new image file referenced from the customized templates on the DM node (under /news/email/images).

2. If necessary, edit the configuration file, notification-config.xml, on the DM node. In the case of customization, this step is needed only if you want to point to other template files rather than editing the existing template provided out-of-the-box. (Refer to “2 Configuring andadministrating email notifications” for more details.)

3. Synchronize all nodes of the Lotus Connections deployment with the DM. This step ensures that the customized templates files and images deployed in step 1 are correctly propagated across all nodes of the deployment in which the News application is installed:

a) From the WebSphere Web administration console (deployment manager), select System administration – Nodes (see figure 19).

Figure 19. System admin – Nodes

b) Select all nodes in which Connections News is installed, and click “Full Resynchronize” (see figure 20).

28

Figure 20. Full Resynchronize

Synchronization can also be done via wsadmin commands. Refer to the WebSphere Application Server documentation topic, “Synchronizing nodes using the wsadmin scripting tool,” for more details.

NOTE: The steps in this section also apply to any customization made to individual notification templates for Wikis, Files, and News applications (FreeMarker templates). We go into more details on individual notifications in Section 4 below.

4 Customizing individual notificationsLet's now discuss in more detail how to customize individual notifications.

4.1 Individual email templatesTemplates define the output of email notifications sent by the different Connections services. There are two main types of templates used in Lotus Connections for individual notifications:

• JSP templates. Used for individual notification emails generated by the Activities, Bookmarks, Communities, and Profiles services. The JSP template files are located inside the Connections service deployment directory (EAR file) and are written following the JavaServer Pages (JSP) technology.

• FreeMarker templates. Used for individual notification emails generated by Files, Wikis, and News. The FreeMarker template files are located under the LotusConnections-Config directory (which is itself located at the configuration cell directory; in other words, outside the service deployment directory). They are written following the FreeMarker templating engine syntax.

The template files are registered per notification type and service in the notification-config.xml file. Refer to “Template section” in “Configuring and administrating email notifications” above for more details. Additionally, you can find a comprehensive list of the notification type supported and corresponding templates in the Appendix section of this document.

Beside daily and weekly email digests, the News aggregation service also delivers individual email notifications. Individual email notifications are sent to users when updates occur for the places, people, and items the user follows across the Connections services. Refer to “3.1.3 Notificationcontent and the “Following” concept in Lotus Connections” for more details.

NOTE: The templates for daily and weekly email digests (generated by the News service) are based on FreeMarker as well and are registered in the same way as individual notifications in notification-config.xml. Many of the concepts introduced for FreeMarker email digest templates can also be applied to customizing individual notifications using this technology (Files, Wikis, and individual notifications from News).

29

Customizing email notifications in a nutshellCustomizing email notifications consists of:

• Locating the JSP or FreeMarker template file to modify on the Connections deployment and making a copy of the template file locally in order to edit them.

• Editing the copy of the templates file, plus the relevant resources properties containing the externalized strings. The following sections give more details on the variables available to each template and identify the location of the property files containing the externalized strings.

• Updating the Connections deployment with the customized files.

In general, if you need to modify the template for Activities, Bookmarks, Communities, Profiles, or Blogs, you must modify the JSP and the linked resources files; if you want to modify the template for Files, Wikis, and News, you must update the FTL files within their linked resources files.

4.2 Locating the template file to editTo locate the template file used to generate the individual notification you want to customize, the easiest way is to:

• Look at the template section of the notification-config.xml configuration file; all supported templates are registered in this section. For instance,

{notification.source.url}/mail/broadcastMail.jsp

• For JSP templates, search for the file on the server file system by name (under <WAS>/profiles/<AppSrv>/installedApps/<CellNode> directory). For instance, on a Linux® system, you can do this via the standard command, “find . -name broadcastMail.jsp”. For FTL templates, simply look in one of the subdirectories of the LotusConnections-Config directory.

Additionally, you can refer to “6 Appendix: Comprehensive overview of all notifications in LotusConnections 3.0“ for a detailed list of notification emails and their associated template files.

4.3 Variables and dynamic contentA template file contains only static text. However, in most cases, the generated notification messages contain information that must vary from one message to the following one (title, sender, text of the notifications, etc.). The dynamic content is passed from the source service to the templating engine through variables, which are referred in the template files with the characters {...} (curly braces).

There are two types of substitution parameters (variables):

• global variables that are available in all notification template types• variables that are specific to templates for a given Connections service

Variables available in any templateTable 1 lists the variables that are available in any template type.

Table 1. Variables and their descriptionsVariable name Description

{notification.sender.name} The notification's sender name

{notification.sender.email} The notification's sender email address

30

{notification.replyto.name} The notification's reply name

{notification.replyto.email} The notification's reply email address

{notification.source} The notification source service

{notification.type} The notification type relative to the source

{notification.subject} The notification's mail subject

Specific variables by template typeIn addition to the general variables listed above, there are variables specific to each Connections service template. The list of variables available for each template type is given in table 2. In addition, with respect to customization, you can search for these specific variables in the template file themselves. Variables are defined between the characters { }, for example, {myvariable}.

Table 2. Variables available for each templateService Notification

nameTemplate file Variables

Activities add-member addMemberMail.jsp {message}

{activity.node.description}

{activity.name}

{activity.description}

{activity.description}

{activity.node.name}

{activity.node.related.valuelabel}

autocomplete autoCompleteActivityMail.jsp

No Variables

create createMail.jsp No Variables

notify notifyMail.jsp {message}{activity.node.description}{activity.node.related.valuelabel}

Bookmarks notify notifytemplate.jsp {bookmarkTitle}

{senderName}

{comments}

{helpURL}

notifyReplaceURL

replaceurltemplate.jsp

{bookmarkTitle}

31

{origURLStr}

{replaceURLStr}

{editBookmarkURL}

{brokenBookmarkURL}

{replaceURLStr}

{mybookmarksURL}

Wikis commentAdd commentAdded.ftl ${notification.actor.name} ${notification.actor.name} ${notification.actor.name}

roleAdd libraryMemberUpdated.ftl

${wikiMemberAdd}

${notification.actor.name}${notification.library.title}${wikiMemberAdd}${notification.actor.name}${notification.actor.url}${notification.library.title}${notification.library.url}${metadataRoleTitle} ${roleDescription}${notification.library.lastupdate}

mediaEdit mediaUpdated.ftl ${notification.actor.name}

${notification.media.title}

${notification.media.url}

${notification.media.tags}

${notification.media.size}

Files collectionMediaAdd

collectionMediaAdded.ftl

${notification.actor.name}

${notification.media.label}

${containerName}

${subject}

${header}

${(notification.media.summary)

${notification.media.url}

$

32

{notification.media.download.url}${notification.media.subscribe.url}${(notification.media.tags)

collectionMemberUpdate

collectionMemberUpdated.ftl

${notification.actor.name}

${notification.collection.title}

${subject}

${notification.collection.url}

${roleDescription}

commentAdd commentAdded.ftl ${notification.media.title}

${notification.actor.name}

${notification.actor.url}

${notification.media.library.name}${notification.media.download.url}${(notification.media.tags)

communityVisibilityUpdate

communityVisibilityUpdated.ftl

${notification.community.title}

${subject}

mediaShare mediaShared.ftl ${notification.media.title}

${notification.actor.name}

${notification.media.url}

${notification.media.download.url}${notification.media.lastupdate}

${notification.media.summary}

${notification.media.size}

mediaUpdated mediaUpdated.ftl ${notification.actor.name}

${notification.media.title}

${subject}

${notification.media.url}

${notification.media.change.summary}

33

${notification.media.download.url}${notification.media.library.name}${notification.media.library.url}

Profiles notify inviteColleagueMail.jsp

{sender.profile.url}

{email.invite.sender.name}

{email.invite.body}

{accept.invite.url}

notifyBoardOwnerForComment

notifyBoardOwnerForComment.jsp

{board.actor.name}

{board.actor.profile.url}

{board.actor.name}

{board.entry.owner.profile.url}

{board.entry.owner.name}

{board.comment.text}

{board.owner.profile.url}

{board.comment.text}

notifyBoardOwnerForEntry

notifyBoardOwnerForEntry.jsp

{board.actor.profile.url}

{board.actor.name}

{board.entry.text}

{board.owner.profile.url}

{board.entry.text}

notifyEntryOwnerForComment

notifyEntryOwnerForComment.jsp

{board.actor.name}

{board.owner.name}

{board.actor.profile.url}

{board.owner.profile.url}

{board.comment.text}

Communities broadcastMail broadcastMail.jsp {body}

{community.url}

{leave.community.url}

{notification.sender.name

34

{community.name}

invite invitedToJoinMail.jsp {community.name}

{community.description}

{join.community.url}

{decline.invite.url}

{template.url.prefix}

memberAdded memberAddedMail.jsp

{community.name}

{community.description}

{community.url}

{leave.community.url}

memberRemoved

memberRemovedMail.jsp

community.name}

reject rejectNoticeMail.jsp {reject.explanation}

{community.name}

{community.description}

Blogs approved-comment

approved_comment.jsp

{item.correlation.url}

{item.correlation.name

{reviewer.name}

{item.content}

{item.url}

{lotusConnections.home}

approved-entry approved_entry.jsp {item.correlation.url}

{item.correlation.name

{reviewer.name}

{item.content}

{item.url}

{lotusConnections.home}

confirmflagged-comment

confirmflagged_comment.jsp

{reporter}

{item.name}

35

{administrator.email}

{lotusConnections.home}

confirmflagged-entry

confirmflagged_entry.jsp

{reporter}

{item.name}

{administrator.email}

{lotusConnections.home}

notifyflagged-comment

notifyflagged_comment.jsp

{item.correlation.name}

{reporter}

{item.content}

{comment}

{item.review.url}

notifyflagged-entry

notifyflagged_entry.jsp

{item.correlation.name}

{reporter}

{item.content}

{comment}

{item.review.url}

{lotusConnections.home}

notify notify.jsp {notify.sender}

{notify.description}

{entry.link}

{entry.title}

{entry.website.name}

{entry.author}

{lotusConnections.home}

notifyreposted-entry

notifyreposted_entry.js

{item.review.url}

{item.name}

{submitter.name}

{item.content}

{item.review.url}

{lotusConnections.home}

36

notifyreview-comment

notifyreview_comment.jsp

{item.correlation.name}

{submitter.name}

{item.review.url}

{item.content}

notifyreview-entry

notifyreview_entry.jsp

{item.correlation.name}

{submitter.name}

{item.review.url}

{item.content}

notifyreview-trackback

notifyreview_trackback.jsp

{mail.subject}

{item.correlation.name}

{item.correlation.url}

{item.content}

{lotusConnections.home}

notifyupdated-entry

notifyupdated_entry.jsp

{entry.title}

{editor.name}

{entry.edit.link}

{entry.link}

{lotusConnections.home}

ownermsg ownermsg.jsp {comment.creator}

{entry.title}

{comment.content}

{comment.deleteURL}

quarantined-comment

quarantined_comment.jsp

{reviewer.name}

{item.content}

{comment}

{reviewer.email}

quarantined-entry

quarantined_entry.jsp

{reviewer.name}

37

{item.content}

{comment}

{reviewer.email}

rejected-comment

rejected_comment.jsp

{reviewer.name}

{item.content}

{comment}

{reviewer.email}

rejected-entry rejected_entry.jsp {reviewer.name}

{item.content}

{comment}

{reviewer.email}

restored-comment

restored_comment.jsp

{reviewer.name}

{item.content}

{item.url}

{lotusConnections.home}

restored-entry restored_entry.jsp {reviewer.name}

{item.content}

{item.url}

{lotusConnections.home}

returned-entry returned_entry.jsp {item.name}

{item.content}

{comment}

{item.edit.url}

{lotusConnections.home}

News followIndividual followIndividual.ftl EmailDigestBean. This variable is an instance of the a class with interface IemailDigestStory.

38

4.4 Email template localizationEmail templates support localized messages. The use of a localized resource varies depending on whether the template is JSP or FreeMarker based. The following subsections outline the differences. Out of the box, 24 locales are supported in Lotus Connections 3.0:

Arabic, Czech, Danish, German, Greek, English, Spanish, Finnish, French, Hungarian, Italian, Hebrew, Japanese, Korean, Dutch, Norwegian, Polish, Brazil, Portuguese, Russian, Swedish, Turkish, Chinese, Taiwan

Emails based on JSP filesTo support internationalization in JSP templates (Activities, Bookmarks, Communities, Profiles, and Blogs services), the JSP Standard Tag Library (JSTL; commonly referred as “fmt”) is used, providing an easy way to localize content inside the JSP template.

Table 3 shows the resource files used by the services in which the strings are externalized.

Table 3. Components and their resource files Component I18N resources files Resources file folderActivities resources.properties oawebui.war/WEB-

INF/lib/oawebui.jar/com/ibm/openactivities/web/coreui/resources

Bookmarks resources.properties dogear.webui.war/WEB-INF/lib/dogear.svc.jar/com/ibm/dogear/resources

Communities resources.properties comm.web.war/WEB-INF/lib/comm.web.jar/com/ibm/tango/email/resources/resources

Profiles mail.properties peoplepages.war/WEB-INF/lib/peoplepages.svc.jar/com/ibm/peoplepages/internal/service/notification

Blogs ui.properties blogs.war/WEB-INF/classes/com/ibm/lconn/blogs/strings/

As mentioned above, each resources file is translated into 24 languages, and a resources folder contains all the files listed in table 4.

Table 4. Contents of resources folderFile Languageresources_ar.properties Arabic

resources_cs.properties Czech

resources_da.properties Danish

resources_de.properties German

resources_el.properties Greek

resources_en.properties English

resources_es.properties Spanish

resources_fi.properties Finnish

resources_fr.properties French

resources_hu.properties Hungarian

resources_it.properties Italian

resources_iw.properties Hebrew

39

resources_ja.properties Japanese

resources_ko.properties Korean

resources_nl.properties Dutch

resources_no.properties Norwegian

resources_pl.properties Polish

resources.properties default

resources_pt_BR.properties Brazil

resources_pt.properties Portuguese

resources_ru.properties Russian

resources_sl.properties Slovenian

resources_sv.properties Swedish

resources_tr.properties Turkish

resources_zh.properties Simplified Chinese

resources_zh_TW.properties Traditional Chinese (Taiwan)

In table 4 above, the file is named resources_<localeName>.properties; other valid names are (1) ui_<localeName.properties, (2) mail_<localeName>.properties, and (3) notification_<localeName>.properties.

The resource bundle files follow the standard Java name-value pair format, in which each value is an externalized string identified by a key. Note that strings can contain variables, as well, whose value is set by the Connections service.

Here is an example of externalized texts that do not contain any variables, and of text that contains two variables delimited by the characters {…}:

email.open.activity=Open this activityemail.notify.body.email.empty=<b>{activity.event.sender.display.name}</b> has notified you about <b>{activity.node.name}</b>

Note that the externalized resources can use HTML code as shown in this example. At runtime the fmt and the JSP will pick up the correct file and use the information presented in the file based on recipient locale (see “2.2 Default email preferences section“ for more details on how the locale is determined).

Here is a sample code snippet showing how the JSP, using the fmt tag library, loads the externalized string:

<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>

[ jsp code … ]

<fmt:message key="email.open.activity"/>

[ jsp code …. ]

To modify and customize the mail contents, you must edit the properties files for those languages that are supported in your deployment. As best practice, we suggest always to modify the default resource too.

40

Email based on FreeMarker templatesConnections Files and Wikis use FreeMarker templates. News (aggregation service) also uses the FreeMarker template for generating the content of daily and weekly email digests. Those templates are stored inside the LotusConnections-config directory, located under

<WAS-directory>/profiles/<Dmgr|AppSrv>/config/cells/<cell-name>/LotusConnections-config/

Along with the template files, the resource bundle files for externalized strings can also be found (see table 5).

Table 5. Components and their resource files Component I18N resource files Resource file folderNews notification.properties LotusConnections-config/news/email

Files notification.properties LotusConnections-config/files/email

Wikis notification.properties LotusConnections-config/wikis/email

4.5 Examples of individual email template customizationThe examples in this subsection describe the most common type of customizations:

• Changing the styles of the notification emails• Updating, removing, or adding new messages (strings) to the emails

This set of operations is supported in both JSP and FreeMarker templates, though the customization approach is slightly different for each.

Example 1: Changing the styles of the notification messagesThe typical way to do this is:

1. Establish the relationship between the email to customize and the action in Lotus Connections generating the email.

2. Based on this relationship, retrieve the original template file responsible for the generated email. See “4.2 Locating the template file to edit“ for more details.

3. Copy the template file to a working folder.

4. Edit the template to apply the customization.

5. Stop the application generating the email in WebSphere Application Server.

6. Copy back the template in the correct place, overriding the original template file.

7. Start the application.

Note that scripts are provided to facilitate the steps to copy the template files and associated resources to a working directory. See “4.6 Check-in / Check-out scripts to retrieve / update JSPtemplate files“ for more details.

Let's show how to change the color of the text of the email generated by Lotus Connections Communities when a user broadcasts a message to the community. The default email generated by Communities in Lotus Connections 3.0 is shown in figure 21.

41

Figure 21. Out-of-the-box broadcast community email-notification message

This message is sent on the following action:

1. In Lotus Connections Communities, access a community to which you belong by clicking the My Communities tab and selecting a Community. Depending on the population of your Connections deployment, you may need to create a new community or join an existing one.

2. Click the Community Actions button (at the top right-hand corner) and select Mail Community (see figure 22).

Figure 22. Mail Community

The template file used by Communities to generate the email message sent to the community member is located in {notification.source.url}/mail/broadcastMail.jsp.

NOTE: The variable {notification.source.url} is resolved at runtime to:

<WAS>/AppSrv/profiles/<AppSrv>/installedApps/<cellName>/Communities.ear/comm.web.war/templates/mail/broadcastMail.jsp.

Figure 23 shows the original content of the broadcastMail.jsp file.

42

Figure 23. Original content of the community broadcast JSP template file

In this example, we will change the color of the body of the message to green. In addition, the string “Custom notification with this body:“ is added in front of the message body.

We start from this HTML snippet in the original template:

<div class=”message”>{body}</div>

and go to this, where we specify the color using CSS and add the string before the {body} variable:

<div class=”message” style=”color: green”>Custom notification with this body: {body} </div>

Figure 24 shows the broadcast community email-notification message after the customizations we've just applied.

Figure 24. Final result of the customizations

Example 2: Updating localized stringsThe typical steps used are:

1. Establish the relationship between the email and the action in Lotus Connections generating the email.

2. Based on this relationship, find the original template file. See “4.2 Locating the template file toedit“ for more details.

43

3. Find the key in the template file used to reference the externalized string:

◦ In JSP files, look for the tags, <fmt:message key="my.key" />◦ In FreeMarker templates, look for the function calls, ${resource(''my.key”)}

4. Find the resource file with the externalized text (see “4.4 Email template localization“).

5. Edit the resource file with the new message.

6. Iterate step 5 for each supported languages.

7. Stop the application generating the email in WebSphere Application Server.

8. Copy back the resources files overriding the original file.

9. Start the application.

For example, let's suppose two strings are updated in the email generated when a user notifies another user about an Activity entry. The template file corresponding to this email notification is notifyMail.jsp, and the resources files containing the externalized strings are located in the following directory:

oawebui.war/WEB-INF/lib/oawebui.jar/com/ibm/openactivities/web/coreui/resources

Figure 25 shows the original email, in which the two strings (“Activity name” and “Activity Goal”) to be modified are outlined in the red boxes.

Figure 25. Original email

The following JSP snippet (notifyMail.jsp) is responsible for placing the externalized string in the generated output, informing us that the key of the string in the property file is email.activity.name:

<b><fmt:message key="email.activity.name" /></b> {activity.name}<br>

To update the strings, we edit the default resources file (resources.properties) in this folder, as well as all the other files (resources_<localeName>.properties) that contain translated strings you support. In the original resources.properties file we have:

email.activity.name=Activity name:

which we change to:

44

email.activity.name=Activity:

The Activity goal message is updated in the same way:

email.activity.goal=Activity goal:to

email.activity.goal=Activity target:

Figure 26 shows how the new email will look with the new custom messages (outlined in red).

Figure 26. Email generated with the two string modifications made

4.6 Check-in / Check-out scripts to retrieve / update JSP template filesAs mentioned previously, JSP template files are located inside the deployed applications; hence, it is relatively difficult to locate, retrieve, and update JSP template files for each application.

To simplify the procedure for retrieving the correct files to modify during email customization and the procedure for updating the component's EAR file with the updated files, two scripts, checkIn.sh and checkOut.sh, are provided with this paper. The scripts are inside the .zip file, TemplateCheckInOut.zip, in the Downloads section, and you can run them once extracted.

The scripts work on UNIX-based systems but are easily changeable and adaptable for other operating systems. The operation to retrieve the email templates is called “check out operation,” contrary the operation to update the applications components, which is called “check in operation.”

The TemplateCheckInOut.zip file contains the following files:

• README.txt - a simple text file, giving instructions on how to use the scripts• init.sh - an initialization file script that you need to edit to set some important variables• initComponentUpdate.sh - an initialization file script that you do not need to edit• checkIn.py - this script is used by checkIn.sh to update the deployed EAR, using the

WebSphere Application Server Admin console; you don't need to run it directly• checkIn.sh - script used to check in the update templates• checkOut.py - script used by checkOut.sh to extract the component EAR from a working

Lotus Connections installation; you don't need to run it directly• checkOut.sh - script used to check out the template resources to temporary location from

where you can edit them

45

Using checkIn.sh and checkOut.sh, you can extract and update the mail template from a deployed distribution of Lotus Connections. The init.sh is used to set up some environment variables that are required by the check in/out scripts.

Table 6 summarizes the above files, their descriptions, and their purpose.

Table 6. Summary of the files contained in the .zip fileFile Must Edit? Must Run? What is it for?README.txt N N A short README about the all the scripts

init.sh Y N To initialize some environment variables that the scripts need

InitComponentToUpdate.sh N N To initialize some environment variables that the scripts need

checkIn.py N N Executed from checkIn.sh

checkIn.sh N Y To check back the modified template

checkOut.py N N Executed from checkOut.sh

checkOut.sh N Y To check out the template

Before using checkIn.sh and checkOut.sh, remember to give the correct permission to all the extracted files. You can set the permission after you have extracted them, using chmod 755 * .

All the extracted files must have root privileges, and you must be root to execute checkIn.sh and checkOut.sh (this paper assumes that WebSphere Application Server was installed using the root privilege). Before running the files, ensure that:

• You have root privileges. • All the files belong to the root user and group. • All seven files (README, init.sh, etc.) are inside the same directory. • WebSphere Application Server is up and running, and Lotus Connections is working properly. • You can tolerate an unexpected outage of Lotus Connections, in case something goes wrong. • You have a backup copy of your deployment. • You have properly edited the init.sh file.

Remember also that, after you run the checkIn.sh, you must restart WebSphere Application Server for the changes to take effect.

Here is an overview of the steps used to check in/out files, followed by more details for each step:

(1) Open and manually edit the init.sh.(2) Run the check-out script to extract the template files and associated resources to edit in the

current working directory.(3) Modify the extracted template files and resources according your customization needs.(4) Run the check-in script to update the application with the changes made to the templates and

resources in your working directory.(5) Restart the updated Lotus Connections application.

Editing init.shThe init.sh file is the script responsible for initializing variables used by the check in/out scripts. The variables must be set to appropriate values, depending on the specificity of your WebSphere Application Server and Lotus Connections deployment. Therefore, you must edit this file prior to running the check in/out scripts.

46

Figure 27 shows how the file looks out of the box.

Figure 27. init.sh file out of the box

Open the file and edit the values of the environments variables listed in table 7.

Table 7. Environment variables to editVariable name Variable descriptionwas_user wasadmin username

was_pwd wasadmin password

work_folder Working folder where you plan to extract and edit the files

was_home Installation path of your WebSphere Application Server

was_profile Deployment Manger profile name

lc30config_home Full path of the LotusConnections-config folder in Deployment Manager profile

Running checkOut.shThe checkOut.sh script is used to extract the JSP templates and resource files from Lotus Connections to the directory pointed to by the variable “work_folder” set in init.sh. Before running it, make sure that the value of the variables in init.sh are appropriately set as indicated above. Additionally, make sure that Lotus Connections is up and running properly on the application server.

When running checkOut.sh, you are prompted to choose the Connections service from which to extract the templates and resources. In this sample we assume that /root/Desktop/Lorenzo is the working folder, while we have extracted the scripts under /root/templateCheckInOut.

For instance, for Connections Activities, we select choice 2 in figure 27. The files are then extracted into the work directory specified in init.sh.

47

Figure 27. Choose the Activities service

Modifying the templatesThe next step is simply to edit the template and resource files to apply your customizations. Figure 28 shows how the folder to which the relevant files have been extracted looks (for the case in which Activities is the selected service).

Figure 28. Folder with extracted files

where:

48

• activities.ear is the extracted EAR• i18n is the directory where the externalized resources are• template is the directory where the templates are stored• tmp and update are two directories you can safely ignore; in fact, do not touch these

directories as they are used by the scripts to unpack and pack files

To change and edit the templates and resources files:

1. Go into the template work directory, and edit the file as needed.

2. If you also want to modify the resources files, go into the i18n folder in the work directory and update the files.

3. Once you've modified the files, you are ready to check them in back to the Connections deployment directories.

Running checkIn.shCheck-in is the process of copying the edited files from the working directory to the Connections deployment directories. To do this, run the checkIn.sh script and select the component you want to update (see figure 29).

Figure 29. checkIn.sh script

49

After running this script, you must restart the application(s) for which you have edited the template and resource files. Note that, if you have a network deployment, you will need to synchronize your changes.

5 ConclusionAfter outlining the most important aspects of configuring and administrating email notifications in Lotus Connections 3.0, we provided the details of customizing both the daily and weekly email digests as well as individual notification messages generated by Lotus Connections.

You should now know enough to create simple customizations such as changing the default logo, and be able to go beyond the examples in this paper and fully implement customized emails consistent with your company branding.

50

6 Appendix: Comprehensive overview of all notifications in Lotus Connections 3.0

Here is the list of Lotus Connections components that use mail notifications:

• Activities• Bookmarks • Blogs • Communities • Profiles• Files• Wikis•NOTE: News in Connections 3.0 is a special component that is responsible for sending digest emails based on what a user is following.

For each service, this appendix provides a table summarizing the actions that trigger the emails, along with the corresponding templates associated with these actions. We then list the steps to reproduce these actions.

NOTE: For further information about the related action description, refer to the Connections Product Documentation topic, “Configuring notifications: lc3.”

Let's begin our comprehensive overview for all the mails and templates presented in Connections 3.0.

6.1 ActivitiesConnections Activities help you organize your work, plan next steps, and invite members of your professional networks to help execute tasks related to a project goal.

In Activities, an email message is created following the actions listed in table 1.

Table 1. Activities actions and their templatesAction Name TemplateGeneral notification notify {notification.source.url}/email/notify

Mail.jsp

When the activity is completed autocomplete {notification.source.url}/email/autoCompleteActivityMail.jsp

Create a new activity create {notification.source.url}/email/createMail.jsp

Adding a member to an activity add-member {notification.source.url}/email/addMemberMail.jsp

Notify users about an activity entryYou can generate the notification (see figure 1) by following these steps:

1. Go to Lotus Connections Activities.2. Open any of the activities to which you have access. You may need to create a new activity if

there is no existing activity on the system.3. Open an existing entry or create a new one.4. Click “More actions” and notify people (see figure 1).

Template file: {notification.source.url}/email/notifyMail.jsp

51

Figure 1. New activity notification

Notification sent when an activity is completedWhen an activity's due date expires, an email with a general notification that the activity is completed is automatically generated from the system. Activity owners receive an email warning them that one of their inactive activities will be marked complete, unless it is updated.

To generate the email:

1. Go to Connections Activities.2. Select an activity and set a due date.

Template file: {notification.source.url}/email/autoCompleteActivityMail.jsp

Notification sent to member of a new activityA general notification email is automatically sent to activity members who are added when a new activity is created.

To generate the notification (see figure 2):

1. Go to Lotus Connections Activities.2. Click Start a new Activity.3. Fill in the form and save it.

Template file: {notification.source.url}/email/createMail.jsp

Figure 2. New member notification for new activity

52

Notification sent to members added to an existing activityWhen an activity owner or author adds members to an activity, a notification is automatically sent to the new members informing them about the activity.

To generate the notification (see figure 3):

1. Go to Lotus Connections Activities2. Open any activity for which you have rights to add members (Owner or Author role). You may

need to create such an activity if one does not exist in your environment.3. In the Members area, click Add a member.

Template file: {notification.source.url}/email/addMemberMail.jsp

Figure 3. New member notification for existing activity

6.2 BookmarksConnections Bookmarks not only provides a better way to manage your own bookmarks but also a way to share, subscribe, and search the community's bookmarks. You can notify your colleagues of an existing useful bookmark via email notifications.

In Bookmarks a mail message is created following the actions in table 2.

Table 2. Bookmarks actions and their templatesAction Type TemplateNotify for a bookmarks notify {notification.source.url}/templates/

notifytemplate.jsp

Notify for a broken bookmarks notifyReplaceURL {notification.source.url}/templates/notifytemplate.jsp

For further information about the related action description, refer to the Connections Product Documentation topic, “Configuring notifications: lc3.”

Notify a user about a bookmarksUsers can send notifications to other users to inform them about useful bookmarks (see figure 4). To do this:

1. Go to Lotus Connections Bookmarks.2. Click More next to a bookmark.3. Click Notify Other People.

Users can also notify others from the My Bookmarks page by selecting one or more bookmarks (with the checkboxes next to the bookmark title) and clicking the Notify button at the top.

53

Template file: {notification.source.url}/templates/notifytemplate.jsp

Figure 4. Useful bookmark notification

Notify a user about a broken bookmarkUsers can send a notification to the bookmark author to inform him/her about a broken bookmark link (see figure 5). To do this:

1. Go to Lotus Connections Bookmarks.2. Click More Actions next to a bookmark.3. Click Flag as Broken URL.

Template file: {notification.source.url}/templates/replaceurltemplate.jsp

Figure 5. Broken bookmark notification

6.3 BlogsThe Blogs service allows people to share their opinion through blogs. When content is quarantined or flagged as inappropriate, an automatic notification is sent to blog owners to inform them about it.

In Blogs, an individual email message is sent for the following the actions in table 3.

Table 3. Blogs actions and their templatesAction Type TemplateA user notify another user of a given blog posts

notify {notification.source.url}/templates/notifytemplate.jsp

Notification sent when a new comment is posted to owner of the blog

ownermsg {notification.source.url}/notifications/ownermsg.jsp

54

Notify for an edited posted notifyupdated-entry {notification.source.url}/notifications/notifyupdated_entry.jsp

Notify for a post which need to be reviewed

notifyreview-entry {notification.source.url}/notifications/notifyreview_entry.jsp

Notify when a post is approved approved-entry {notification.source.url}/notifications/approved_entry.jsp

Notify the author of a rejected post rejected-entry {notification.source.url}/notifications/rejected_entry.jsp

Notify the reviewer of inappropriate posts

notifyflagged-entry {notification.source.url}/notifications/notifyflagged_entry.jsp

Notify the author for an approved comment

confirmflagged-entry {notification.source.url}/notifications/confirmflagged_entry.jsp

Notify the authors of a quarantined post

quarantined-entry {notification.source.url}/notifications/quarantined_entry.jsp

Notify the authors for a returned post

returned-entry {notification.source.url}/notifications/returned_entry.jsp

Notify content reviewers to review a comment

notifyreposted-entry {notification.source.url}/notifications/notifyreposted_entry.jsp

Notify reviewers of a new trackback comment posted

notifyreview-comment {notification.source.url}/notifications/notifyreview_trackback.jsp

Notify a comment creator about the approved comment

notifyreview-trackback {notification.source.url}/notifications/approved_comment.jsp

Notify a comment creator about the rejected comment

approved-comment {notification.source.url}/notifications/rejected_comment.jsp

Notify content reviewers about an inappropriate comment

rejected-comment {notification.source.url}/notifications/notifyflagged_comment.jsp

Notify the flag creator that his flag is confirmed

notifyflagged-comment {notification.source.url}/notifications/confirmflagged_comment.jsp

Notify the comment creator when a comment is quarantined

quarantined-comment {notification.source.url}/notifications/quarantined_comment.jsp

Notify the post authors about a restored post

restored-entry {notification.source.url}/notifications/restored_entry.jsp

Notify the comment author about a restored comment

restored-comment {notification.source.url}/notifications/restored_comment.jsp

Notification one user sends to others to inform them about useful blog postsTo generate this notification (see figure 6):

1. Go to Lotus Connections Blogs.2. Go to the blog entry view page.3. Click "More Actions/Notify other users".

Template file: {notification.source.url}/notifications/notify.jsp

55

Figure 6. Useful blog post notification to others

Notification when a new comment is postedWhen a new comment is posted, an automatic notification is sent to the entry creator about the new comment (see figure 7). To generate this notification:

1. Go to Lotus Connections Blogs.2. Go to the blog entry view page.3. Click "Add a Comment".4. Enter a comment and click "Submit".

Template file: {notification.source.url}/notifications/ownermsg.jsp

Figure 7. New comment notification

Notification for an edited blog entryWhen a blog post is edited or updated by another users, an automatic notification is sent to the entry creator to inform him about the update (see figure 8). To generate the notification:

1. Go to Lotus Connections Blogs.2. Go to the blog entry view page.3. Click "Edit" to edit the entry.4. Edit and click "Post to Blog".

Template file: {notification.source.url}/notifications/notifyupdated_entry.jsp

56

Figure 8. New blog entry notification

Notification sent for a post that needs reviewWhen a new post is added and put in a pending state, an automatic notification is sent to content reviewers, who include anyone in the global-moderator role, to let them know they need to review it. To generate this notification:

1. Go to Lotus Connections Blogs.2. Go to the blog entry view page.3. Click "Edit" to edit the entry.4. Edit and click "Post to Blog".

Template file: {notification.source.url}/notifications/notifyreview_entry.jsp

Notification sent when a post is approvedWhen a post is approved, an automatic notification is sent to the entry authors, including the post creator and its last editor, to inform them about it. To generate the notification:

1. Go to Lotus Connections Blogs.2. Go to the Moderation page.3. Go to the "Entry Approval" page and select the Require Approval tab.4. Select one or more blog entries, and click the Approve button.

Template file: {notification.source.url}/notifications/approved_entry.jsp

Notify the author of a rejected postWhen a post is rejected, an automatic notification is sent to the post authors, including the post creator and its last editor, to inform them about it. To generated this notification:

1. Go to Lotus Connections Blogs.2. Go to the Moderation page.3. Go to the Entry Approval page, and click the Require Approval tab.4. Select one or more blog entries, and click the Reject button.

Template file: {notification.source.url}/notifications/rejected_entry.jsp

Notify the reviewer about inappropriate postsWhen a post is flagged as inappropriate, an automatic notification is sent to content reviewers, including anyone in the global-moderator role, to inform them about it. To generated this notification:

57

1. Go to Lotus Connections Blogs.2. Go to the blog entry view page.3. Click "Flag as inappropriate" for this entry.

Template file: {notification.source.url}/notifications/notifyflagged_entry.jsp

Notify the author about an approved commentWhen a flag on a comment is confirmed, an automatic notification is sent to the flag creator to inform him about it. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the Moderation page.3. Go to the Flagged Comments page, and select the Awaiting Decision tab.4. Select one or more blog entries, and click the Quarantine button.

Template file: {notification.source.url}/notifications/confirmflagged_entry.jsp

Notify the authors about a quarantined postWhen a post is quarantined, an automatic notification is sent to the post authors, including the post creator, its last editor, and blog owners, to inform them about it. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the Moderation page.3. Go to the "Flagged Entries" page, and select the Awaiting Decision tab.4. Select one or more blog entries, and click the Quarantine button.

Template file: {notification.source.url}/notifications/quarantined_entry.jsp

Notify authors about a returned postWhen a post is returned, an automatic notification is sent to the post authors, including the post creator, its last editor, and blog owners, to inform them about it. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the Moderation page.3. Go to the "Flagged Entries" page, and select the Quarantined tab.4. Select one or more blog entries, and click the Return to Author button.

Template file: {notification.source.url}/notifications/returned_entry.jsp

Notification sent to content reviewers to review a commentWhen a new comment is posted and put in pending status, an automatic notification is sent to content reviewers, including anyone in the global-moderator role, to let them know they need to review it. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the blog entry view page.3. Click "Add a Comment".4. Edit and click "Submit".

Template file: {notification.source.url}/notifications/notifyreposted_entry.jsp

Notify reviewers on a new trackback comment postedWhen a new trackback comment is posted and put in pending status, an automatic notification is

58

sent to content reviewers, including anyone in the global-moderator role, to let them know they need to review the trackback comment. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the blog entry view page, and copy the entry URL.3. Create a new entry.4. Edit this entry, and paste the previous entry URL into the Trackback URL field.5. Click "Send Trackback".

Template file: {notification.source.url}/notifications/notifyreview_trackback.jsp

Notify a comment creator about the approved commentWhen a comment is approved, an automatic notification is sent to the comment creator to inform him about it. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the Moderation page.3. Go to the Comment Approval page, and select the Require Approval tab.4. Select one or more blog comments, and click the Approve button.

Template file: {notification.source.url}/notifications/approved_comment.jsp

Notify a comment creator about a rejected commentWhen a comment is rejected, an automatic notification is sent to the comment creator to inform him about it. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the Moderation page.3. Go to the Comment Approval page, and select the Require Approval tab.4. Select one or more blog comments, and click the Reject button. Template file: {notification.source.url}/notifications/rejected_comment.jsp

Notify content reviewers about an inappropriate commentWhen a comment is flagged as inappropriate, an automatic notification is sent to content reviewers, including anyone in the global-moderator role, to inform them about it. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the blog entry view page.3. Click "Flag as inappropriate" for this comment.

Template file: {notification.source.url}/notifications/notifyflagged_comment.jsp

Notify the flag creator that his flag is confirmedWhen a flag on a post is confirmed, an automatic notification is sent to the flag creator to inform him about it. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the blog entry view page.3. Click "Flag as inappropriate" for this comment

Template file: {notification.source.url}/notifications/confirmflagged_comment.jsp

59

Notify the comment creator when a comment is quarantinedWhen a comment is quarantined, an automatic notification is sent to the comment creator and the blog owners to inform them about it. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the Moderation page.3. Go to the Flagged Comments page, and select the Require Approval tab.4. Select one or more blog comments, and click the Quarantine button.

Template file: {notification.source.url}/notifications/quarantined_comment.jsp

Notify the post author about a restored postWhen a post is restored, an automatic notification is sent to the post authors, including the post creator, its last editor, and blog owners, to inform them about it. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the Moderation page.3. Go to the Flagged Entries page, and select the Quarantined tab.4. Select one or more blog entries, and click the Restore button.

Template file: {notification.source.url}/notifications/restored_entry.jsp

Notify the comment author about a restored commentWhen a comment is restored, an automatic notification is sent to the comment creator and blog owners to inform them. To generate this:

1. Go to Lotus Connections Blogs.2. Go to the Moderation page.3. Go to the Flagged Comments page, and select the Quarantined tab.4. Select one or more blog entries, and click the Restore button.

Template file: {notification.source.url}/notifications/restored_comment.jsp

6.4 CommunitiesThe Communities feature helps people who share a common interest collaborate by exchanging and sharing information, or interacting among each another, via their Web browser and email software.

Members can send notifications to other members to inform them about important events. Users can request to join a community by sending an email to the community's owner, and an email is automatically generated and sent to members when they are added to a community. In Communities a mail message is created following the actions in table 4.

Table 4. Communities actions and their templatesAction Type TemplateSending a mail to the community members

broadcastMail {notification.source.url}/mail/broadcastMail.jsp

Adding a member memberAdded {notification.source.url}/mail/memberAddedMail.jsp

Removing a member memberRemoved {notification.source.url}/mail/memberRemovedMail.jsp

Sending a request to join a community

requestToJoin {notification.source.url}/mail/requestToJoinMail.jsp

60

Send an invite to join a community invite {notification.source.url}/mail/invitedToJoinMail.jsp

Sending an email to the community membersAn email with general information is sent to the community's members each time a member decides to notify the other members (see figure 9). To do this:

1. Go to Lotus Connections Communities.2. Open any of the Communities to which you are assigned.3. Click the Community actions icon, and click “Mail to Community'.

Template file: {notification.source.url}/mail/broadcastMail.jsp

Figure 9. Communities email notification

Adding a memberAn email communicating that a member is added is posted to the added user after the community owner adds the member (see figure 10). To do this:

1. Go to Lotus Connections Communities.2. Open any of the Communities for which you are an administrator,3. Click Members, and click Add member.

Template file: {notification.source.url}/mail/memberAddedMail.jsp

Figure 10. Added to a community notification

Removing a memberAn email communicating that a member is removed is posted to the removed user after the community owner removes the member (see figure 11). To do this:

1. Go to Lotus Connections Communities.2. Open any of the Communities for which you are an administrator.3. Click Members, find your member, and click Remove.

61

Template file: {notification.source.url}/mail/memberRemovedMail.jsp

Figure 11. Removed from a community notification

Sending a request to join a communityAn email is sent to the community owner each time a user requests to join a community, after which the owner can add the member (see figure 12). To do this:

1. Go to Lotus Connections Communities.2. Open any of the Communities that you want to join.3. Click the Join Community button.

Template file: {notification.source.url}/mail/requestToJoinMail.jsp

Figure 12. Join a community request notification

Send an invite to join a communityMembers can send an invitation to a non-member to join the community (see figure 13). To do this:

1. Go to Lotus Connections Communities.2. Open any of the Communities of which you are member.3. Click the Members section of the community, and click Invite member.

Template file: {notification.source.url}/mail/invitedToJoinMail.jsp

62

Figure 13. Invitation to join a community notification

6.5 ProfilesLotus Connections Profiles helps you quickly find the people you need by searching across your organization, using keywords to identify expertise, current projects, and responsibilities. In your Profile you can update your status with any message you like, and you can also leave comments on your colleague's board.

In Profiles a mail message is created following the actions in table 5.

Table 5. Profiles actions and their templatesAction Type TemplateWhen a user invite a colleague notify {notification.source.url}/mail/invite

ColleagueMail.jsp

Board owners are notified when someone posts a message in their message board

notifyBoardOwnerForEntry {notification.source.url}/mail/notifyBoardOwnerForEntry.jsp

Board owners are notified when someone comments on their message board

notifyBoardOwnerForComment {notification.source.url}/mailnotifyBoardOwnerForComment.jsp

Board owners are notified when someone comments on a message board entry

notifyEntryOwnerForComment {notification.source.url}/mailnotifyEntryOwnerForComment.jsp

When a user invites a colleagueAn email with an invitation message is sent to a colleague when a Profiles user requests to add the colleague to his network (see figure 14). Also, if a person designates someone else as a colleague, the colleague is sent an email inviting them to join that person's network. To do this:

1. Go on Profiles and search for a colleague.2. Select the colleague's Profile.3. Click the Invite to My Network button.

Template file: {notification.source.url}/mail/nviteColleagueMail.jsp

63

Figure 14. Profiles invitation to join network notification

Board owners are notified when someone posts a message in their message boardTo generate this notification (see figure 15):

1. Go to Lotus Connections Profiles2. Select a colleague.3. On the colleague's board, add a message and click Post Message.

Template file: {notification.source.url}/mailnotifyBoardOwnerForEntry.jsp

Figure 15. Message posted notification

Board owners are notified when someone comments on their message boardTo generate this notification (see figure 16):

1. Go to Lotus Connections Profiles2. Select a colleague, and find an area where you would like to add a comment.3. Click Write another comment, write the comment, and click Post Comment.

Template file: {notification.source.url}/mailnotifyBoardOwnerForComment.jsp

Figure 16. Comment on message board notification

64

Board owners are notified when someone comments on a message board entryTo generate this (see figure 17):

1. Open the Profiles page of a user in the system. Do this via the business card and select “Profiles”.

2. In the board of the user, add a comment on an existing message.

Template file: {notification.source.url}/mailnotifyEntryOwnerForComment.jsp

Figure 17. Comment on a message board entry notification

6.6 FilesLotus Connections Files enables users to find and share any type of file.

In Files a mail message is created following the actions in table 6.

Table 6. Files actions and their templatesAction Type TemplateSharing a file with other users mediaShare {notification.source.url}/files/email/

mediaShared.ftl

Notification sent to users when a file they are following is edited

mediaEdit {notification.source.url}/files/email/mediaUpdated.ftl

Adding a comment to a shared file commentAdd {notification.source.url}/files/email/commentAdded.ftl

Notification sent to users when a folder is shared with them, or when their folder access level changes. This applies to individual users, not groups.

collectionMemberUpdate {notification.source.url}/files/email/collectionMemberUpdated.ftl

Notification sent to owners of a community when the community was made public and non-public files shared with the community were removed from it.

communityVisibilityUpdate {notification.source.url}/files/email/communityVisibilityUpdated.ftl

Notification sent to users when a file is added to a folder or community they are following

collectionMediaAdd {notification.source.url}/files/email/collectionMediaAdded.ftl

Sharing a file with other usersAn mail to advise that a new file has been shared with a user is sent to a colleague when a Files user shares a document with him. To generate this notification (see figure 18):

65

1. Go to Lotus Connections Files.2. Open a file you own, and select the Share tab.3. Add users in the Reader or Editor role.

Note that it's possible share the file even during the first-time upload. This notification is posted by default.

Template file: {notification.source.url}/files/email/mediaShared.ftl

Figure 18. Share a file notification

Notification sent to users when a file they are following is editedAn mail indicating that a file has been updated is sent to all the users who are sharing the same file each time the file owner changes the file's properties (name, etc.). (Users can follow files by opening the file page and clicking Follow). To generate this notification:

1. Go to Lotus Connections Files.2. Open a file that you own, and click More Actions.3. Click Edit Properties, and change the name or the file description.4. Click OK.

Template file: {notification.source.url}/files/email/mediaUpdated.ftl

Adding a comment to a shared fileAn email communicating that a new comment has been added to the file that's been shared with you is sent each time an user adds a new comment. The email is sent to users when a comment is created on a file they are following. (Users can follow files by opening the file page and clicking Follow.) To generate this notification (see figure 19):

1. Go to Lotus Connections Files.2. Open any file that is shared with you, or any public file.3. Select the Comment tab, and add a comment to the file.

Template file: {notification.source.url}/files/email/commentAdded.ftl

66

Figure 19. Comment added to shared file notification

Notification sent to users when a folder is shared with them, or when their folder access level changesThis applies to individual users, not groups. To generate this notification, share or update a user to a new role.

Template file: {notification.source.url}/files/email/collectionMemberUpdated.ftl

Notification sent to owners of a community when the community is made public and non-public files shared with the community were removed from it

To generate this notification:

1. Create a community that is private.2. Share files that are private with that community.3. Make the community public.

Template file: {notification.source.url}/files/email/communityVisibilityUpdated.ftl

Notification sent to users when a file is added to a folder or community they are followingTo generate this notification (see figure 20):

1. Follow the folder.2. As another user, add a file to the folder.3. A notice should be received.

Template file: {notification.source.url}/files/email/collectionMediaAdded.ftl

Figure 20. File added to a followed folder notification

67

6.7 WikisWikis is the part of Lotus Connections that helps people create a wiki. In Wikis you can even collaborate with other colleagues, editing content and adding a contribution to an existing wiki.

In Wikis a mail message is created following the actions in table 7.

Table 7. Wikis actions and their templatesAction Type TemplateEditing the wikis properties mediaEdit {notification.source.url}/wikis/email/

mediaUpdated.ftl

Adding a comment to a wiki where you work on

commentAdd {notification.source.url}/wikis/email/commentAdded.ftl

Notification sent to users when they are made a member of a wiki

roleAdd {notification.source.url}/wikis/email/libraryMemberUpdated.ftl

Editing the wikis propertiesAn email notifying that a property has changed in the wiki in which you are interested or working is sent when someone changes the wiki properties (see figure 21). The email is sent to users when an event occurs in a wiki page or wiki they are following.

Events include title or description edits; new tags; and new or deleted pages, edits, or comments. Users can follow wiki pages or wikis by opening a page and clicking Follow and then Follow this Page or Follow this Wiki. To generate this notification:

1. Go to Lotus Connections Wikis2. Open an existing wiki and click Edit.3. Modify the wiki text in the editor.4. Click Save or Save and Close.

Template file: {notification.source.url}/wikis/email/mediaUpdated.ftl

Figure 21. Wikis property change notification

Adding a comment to a wiki on which you workAn email communicating that a new comment has posted to the wiki that you are following is posted to you (see figure 22). To generate this notification:

1. Go to Lotus Connections Wikis.2. Open an existing wiki, and select a page.3. Click "Add a comment", and enter text in the dialog box.4. Click Save.

Template file: {notification.source.url}/wikis/email/commentAdded.ftl

68

Figure 22. Comment added to followed wiki notification

Notification sent to users when they are made a member of a wikiThis applies to individual users, not groups. This notification is also sent to users when their wiki access level is changed. To generate this notification:

1. Go to Lotus Connections Wikis2. Create a wiki or open an existing wiki.3. Specify the members to be added to the wiki and their roles (Owner/Editor/Reader), and add a

new member for the Role.4. Click OK.

Template file: {notification.source.url}/wikis/email/libraryMemberUpdated.ftl

Figure 23. Added as member of a wiki notification

6.8 ForumsA forum is an online discussion board where people can ask questions, share their experiences, and discuss topics of common interest.

With the Forums application you can start discussions about a specific topic or debate solutions to shared problems. By participating in a forum, you can exchange ideas, ask questions, and leverage the expertise of other people in your organization.

There is no template specific for Forums; however, email notifications can be received when an event occurs in forum that's followed by a user. In such a case, the email notifications are generic and are generated by the Connections News service. Refer to the following News section for more details.

6.9 NewsLotus Connections News is the aggregation service of the social platform. It is mainly responsible for generating the daily and weekly digests as outlined in “3 Customizing daily and weekly email

69

digests“. However, News also sends generic individual email notifications for any update related to the places, item, or people that the user follows across Lotus Connections.

Generic individual notifications are also sent for responses to the user contributions. Generic notifications are sent only when there is no existing notification templates defined by the Lotus Connections service in which the update occurs.

Template file: LotusConnections-config/news/email/followIndividual.ftl

Figure 24 shows an individual notification sent to a follower of a community. In this case, another user added a bookmark in the community.

Figure 24. Generic notification

7 Resources• Lotus Connections 3.0 Documentation:

http://www-10.lotus.com/ldd/lcwiki.nsf/xpViewCategories.xsp?lookupName=Lotus%20Connections%203%20documentation

• WebSphere Application Server Version 7.0 Information Center:http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp

• Lotus Connections product page:http://www-01.ibm.com/software/lotus/products/connections/

• Synch.rono.us, the Lotus Connections product team blog: http://synch.rono.us/social/blog.nsf/

• Lotus Connections forum:http://www-10.lotus.com/ldd/lcforum.nsf

• Configuring notifications: Lotus Connections 3.0:http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Configuring_notifications_lc3

• Lotus Connections 3.0 Email digest JavaDoc:http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Lotus_Connections_3_Email_Digest

• Tips and tricks for developing HTML for compatible with email clients: http://www.slideshare.net/ExactTarget/html-for-email-technical-tips-and-tricks-developing-emails

• Guide to CSS support in Email clients: http://www.campaignmonitor.com/css/

70

8 About the authorsVincent Burckhardt is the Development Lead for the Lotus Connections News service at IBM's Dublin Software Laboratory, and is the primary Software Engineer working on email digest capability.

Lorenzo Notarfonzo is a Software Engineer working on the Lotus Connections Homepage development team, and is the author of the developerWorks white paper, “Customizing email notifications in IBM Lotus Connections 2.5.”

Trademarks• AIX, developerWorks, IBM, Lotus, and WebSphere are trademarks or registered trademarks of IBM

Corporation in the United States, other countries, or both.

• Microsoft and Windows are registered trademarks of Microsoft Corporation in the United States, other countries, or both.

• Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States, other countries, or both.

• Other company, product, and service names may be trademarks or service marks of others.

71