Customizing IBM Lotus Connections 3.0 digests and notifications

Transcription

1 Customizing IBM Lotus Connections 0 digests and notifications Vincent Burckhardt Software Engineer - Lotus Connections Development IBM Collaboration Solutions Mulhuddart, Ireland Lorenzo Notarfonzo Software Engineer - Lotus Connections IBM Collaboration Solutions Mulhuddart, Ireland March 2011 Copyright International Business Machines Corporation 201 All rights reserved. Summary: One of the primary new features of IBM Lotus Connections 0 is the 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 s, ranging from changing the look and feel of s to more complex customizations such as adding your company-specific content to the digests. In addition, this paper also covers customizing individual notification s sent by the Lotus Connections services. Table of Contents 1 Introduction Configuring and administrating notifications Properties section Default preferences section Channel config channelconfig section Template section Enabling and disabling notifications Customizing daily and weekly digests How the digest capability works Customizing digest messages Development environment to customize digest templates Step-by-step customization example Customizing individual notifications Individual templates Locating the template file to edit Variables and dynamic content template localization Examples of individual template customization Check-in / Check-out scripts to retrieve and update JSP template files

2 5 Conclusion Appendix: Comprehensive overview of all notifications in Lotus Connections Activities Bookmarks Blogs Communities Profiles Files Wikis Forums News Resources About the authors Introduction Lotus Connections is a Web 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 notifications. There are various types of notifications sent from the different services that can be split into two main categories: Daily and weekly 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 digests are new to Lotus Connections 0. Individual 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 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 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 notifications in Lotus Connections 0. The second and third sections deal with customizing digests and individual notifications s. A comprehensive reference on existing individual notifications is provided in the Appendix. 2

3 2 Configuring and administrating notifications 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/<cellname>/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 messages sent from Lotus Connections. Default preferences setting. Defines the default preferences for notifications and digests. Users can override the default preferences on an individual basis from the settings page. channel config. This section groups the configuration settings related to the SMTP server used to send s. Template. The template files used to define the output of 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: 1 Properties section The 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, globalsender address : <properties> <property name="globalsender address">global-admin@your- -domain.com</property> </properties> This property specifies a sender mail address in the case when Lotus Connections is configured to hide 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 4 Template section below. You can find additional optional properties in the Lotus Connections 0 documentation topic, Defining valid administrator addresses. 2 Default preferences section As of release 0 of Lotus Connections, users can centrally control the following settings related to digest and notifications: address to which Lotus Connections messages Language of the 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

4 Set the frequency of notifications for 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 s, include the notification in the daily or weekly digest messages, or to receive no notification at all. Figure 1 shows the Preference setting page (available via the "Settings" link in the navigation page header available across Connections services). Figure Preferences page From the default preference section of notification-config.xml, the administrator can control most of the default settings for preferences available to all users (see listing 1). Listing Default settings for preferences  <default preferences>  <allow addressoverride>true</allow addressoverride>  <uselanguagefromcallingcomponent>true</uselanguagefromcallingcomponent>  <defaultlanguage>en</defaultlanguage>  <send sfordirectnotifications>true</send sfordirectnotifications>  <defaultresponsesfrequency>individual</defaultresponsesfrequency>  <defaulttagfollowfrequency>weekly</defaulttagfollowfrequency> </default preferences> 4

5 You may notice that the default preferences 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 Listing Frequency settings definitions <source defaultfollowfrequency="daily" enabled="true" imagesurl="{notification.source.url}/images/" name="activities"> <source defaultfollowfrequency="weekly" enabled="true" imagesurl="{notification.source.url}/rollerui/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 0 Product Documentation topic, Enabling users to specify notification preferences. 3 Channel config channelconfig section The channelconfig section is used to define the configuration related to the SMTP server(s) used by Lotus Connections to send . In addition, the section is used to define some properties that JavaTM Mail uses during 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 delivery and the backend infrastructure, refer to the Lotus Connections 0 documentation topic, Configuring notifications in IBM Lotus Connections 0. 1 Using DNS MX server resolution To 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 5

6 Listing Properties for DNS MX server resolution <channelconfigs> < channelconfig> <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> </ channelconfig> </channelconfigs> You can also configure some specific properties that are used directly by the JavaMail framework used by Lotus Connections to send s through the SMTP servers, such as Debug mode and the timeout value. 2 Using the WebSphere Application Server JavaMail Session To 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> < channelconfig> <usejavamailprovider>true</usejavamailprovider> <maxrecipients>50</maxrecipients> </ channelconfig> </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 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

7 Figure 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. 3 Common preferences In both the above cases, the administrator can configure the maximum number of recipients per , 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 s 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. 4 Template section The set of templates used by the different Lotus Connections services to generate the output of the 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

8 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=" "> <property <property name="url">{notification.source.url}/ /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=" "> <property <property name="url">{notification.source.url}/ /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 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 address that appears in the From field for: s sent automatically from the system, for example, when an activity auto-completes after a period of time. Note that the From field of s sent for directed notifications (a given user sending a message through Lotus Connections to a set of users) is set to the address of the user at the origin of the notification. Directed notification in the case when Lotus Connections is configured to not show addresses. The sender property is also used when the user sending the directed notification does not have an address. In the case when the sender property is not specified, the globalsender address is used (see Properties section above). 8

9 Channel. A source can send a notification over two communications channels, and event; however, the event channel is for internal use and should not be modified: <channel enabled="true" name=" "> <property name="sender">activities-admin@example.com</property> <property name="url">{notification.source.url}/ /notifymail.jsp</property> </channel> Url property. The url property specifies the location of the template file used to generate the output of notification s. 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. 5 Enabling and disabling notifications 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 s 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 digests As already mentioned, the digests feature was introduced in version 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 message generated by the digest capability. 9

10 Figure Example message In this section we first introduce how digest messages are generated by the aggregation service. In that way, you'll have the background knowledge on how to fully customize and extend messages, depending on your use cases. Then we discuss an overview of the possible customizations of the digest capability, using a real-world example. 1 How the digest capability works The Connections News service delivers newsletters containing an overview of the elements of interest for the recipient in the past 24 hours ( daily digest ) or past week ( weekly digest ). 1 High-level architecture overview The system responsible for generating the 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 messages. The generated s are multi-part messages, including both the HTML output of the as well as a text version for clients that don't support HTML. 10

11 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 message output based on a supplied template file. 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 from the aggregation service for a given person (the recipient of the ). The settings in the 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 preference section for more details on setting preferences. Passing the set of stories to the templating engine, which then invokes the template file to generate the final output of the message. Sending the message with the output returned from the templating engine. 2 List of stories content included in digests The stories included in a given 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 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 Default preferences section above for more details. Elements that are of interest to the 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 Notification content and the Following concept in Lotus Connections Here are the elements that the system can include in the personalized 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

12 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 digest messages; the stories from both are displayed in the 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. 2 Customizing digest messages Let's now discuss the aspects of customizing the digests messages. 12

13 1 Customization aspects template files Customization of the 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 by editing the template files. Adding or removing content from the generated s. 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. 2 Location and registration of digest template files The 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 digests as seen out-of-the-box on a Connections 0 deployment is shown in listing 5. (Recall that Section 2 above, Configuring and administering notifications provides a more general introduction to the options provided in notificationconfig.xml.) Listing 5. Templates configuration file <templates>  <source defaultfollowfrequency="daily" enabled="true" imagesurl="{notification.source.url}/news/ /images/" name="news"> <type name="dailydigest" notificationtype="follow"> <channel enabled="true" name=" "> <property name="sender">news-admin@example.com</property> <property name="ftl">{notification.source.url}/news/ /dailydigest.ftl</property> <property name="bundlepath">{notification.source.url}/news/ /</property> <property name="bundlename">notification</property></channel> </type>  </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 digest. For the daily digest, it points to the dailydigest.ftl file with the default value of {notification.source.url}/news/ /dailydigest.ftl. If you wish to point to a new template file, this is the property to edit. 13

14 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 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 4.4 Handling internationalization. The property sender. This is the address of the sender of the digest message ( From field in the received s). 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 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 s). 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/<cellname>/LotusConnections-config/news/ /dailyDigest.ftl. 3 FreeMarker templating engine FreeMarker is the templating engine used by Lotus Connections to generate the daily and weekly message output. Consequently, the templates file provided for 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 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. 4 Structure of the out-of-the-box daily and weekly template files As outlined in the Location and registration of 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

15 The template files are located under the /news/ 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 messages including 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-bystep 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/ /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 digest messages. The set of Cascading Style Sheets (CSS) styles defining the look and feel of the 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 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 newsletter header defined in the same file. Macro digestfooter : Renders the footer of the message, that is, the box with a link directing the user to the -digest setting preferences page. Macro digestsection : Renders the HTML code for each section of the 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 . Figure 6 shows the macros responsible for generating the HTML (and text) output of the different sections of the digest message. 15

16 Figure 6. Macros and their corresponding sections of the digest message util.ftl. This is the set of utility and helper functions used in various places in 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 Development environment to customize digest templates This part provides more details on the development environment to customize 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 0 documentation topic, Configuring notifications, for more details. 1 Working on a single-node deployment The 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 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. 2 Forcing the system to deliver an digest message immediately To facilitate the development effort, an action in the form of a URL can be hit to trigger immediately the generation of an containing the same output as a standard daily or weekly message. The generated is sent only to the authenticated user who hit the action (for example, the developer). 16

17 The URL of the action is located at: 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: 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 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 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. 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: The generated output message is sent to the address of the authenticated user that hit the action. Note that the address used is the one configured in the settings page, so ensure that the address is correct for the authenticated user on that page. You may need to change the default settings of allow addressoverride in notification-config.xml to be able to edit the address in the settings page for testing purposes (see Default preferences section in Configuring and administrating notifications ). Additionally, no is sent if there is no story for the user who hit the action. Since the stories included in the 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 digest messages. 17

18 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: On the Lotus Connections Blogs My Blogs tab, click Start a Blog. Enter some values for the new blog and click Save. 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 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

19 Figure 8. Newly created blog entry followed in the News Feed section 3 Enabling the server trace log related to digests The server trace log details related to 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: In the WebSphere administrative console, select Resources Mail Mail Sessions. Select the Lotus Connections mail session (named lcnotification by default). 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 3 Channel Config 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 template files that you write or modify. 19

20 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 digests. Figure 9. Example syntax error in template file 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 digest messages, most common 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 (see figure 10). Figure 10. View page source option in Lotus Notes 8.5 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

21 Each part of the message is delimited by a boundary, which starts with the characters ---- in digest messages, with the exact boundary sentence given in: Content-Type: multipart/related; boundary="----=_part_64_ " The HTML content part of the messages generated from the templates starts after the boundary: =_Part_64_ Content-Transfer-Encoding: 7bit Content-Type: text/html;charset=utf-8 Figure 11 shows the source of an 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 1 Source of an in Lotus Notes 4 Step-by-step customization example Using 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

22 The customized files are attached in the Download, digestcustomizations.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 0 digest messages. Figure 1 Original theme of the digest messages Figure 13 shows the same message after the new Lotus Knows theme has been applied. 22

23 Figure 1 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 4.1 Replacing the logo in digest messages Let's go through the steps to replace the Lotus Connections logo (see figure 15) at the top of the digest messages with the Lotus Knows logo (see figure 16). Figure 15. digest header bar with standard Lotus Connections logo Figure 16. digest header bar with custom Lotus Knows logo Add the image for the logo under the directory LotusConnections-Config/news/ /images. Notice this is the directory pointed to by the imageurl attribute of the node source in 23

24 notification-config.xml, as mentioned above in the Location and registration of digest template files section. Any standard image format can be used (.jpg,.gif,.png are the main ones); however, note that some older clients cannot render.png images properly. In this example, we use the image named LotusKnows.jpg, which is included in the Downloads (inside digestcustomizations.zip) accompanying this paper. Edit the file style.ftl (located under the LotusConnections-Config/news/ /aggregated directory) with any standard text editor. Look for the section defining the macro named newsletter header, 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 By using an embedded image, the client doesn't need to fetch the image from a remote server when the recipient opens the messages. In addition, most modern 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 , 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 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 digest to allow them to be translated. 4.2 Modifying the styles of the messages Here we show how to modify the visual theme of the 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

25 Figure 17. New digest message styles applied in this section The visual appearance of the 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 header To 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 4 Viewing the message source 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 digest messages is defined as an HTML row element ( tr element) with the CSS class newsletter header. The CSS class newsletter header is defined as such in style.ftl:.newsletter header { 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 ). 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 newsletter header is:.newsletter header { background-color: #333333; color: #ffffff; bordercolor: blue; border-style: solid; } Modifying the background color of the section headers In 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 ( digestcustomizations.zip) 25

26 4.3 Adding new content to the digest The dataset passed to the templates is larger than the information visible in the default messages provided out-of-the-box in Lotus Connections 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 digestbean, which is an instance of a Java class implementing the interface I DigestStoriesContainer. The Javadoc for interfaces of the beans available in digest templates is in the Documentation topic, Lotus Connections 3 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. I DigestStoriesContainer 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 I DigestStory (see Javadoc link, Lotus Connections 3 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: Consult the Java Doc documentation to see whether the information to surface is available. In the case of this example, I DigestStory exhibits a getter named getentryhtmlurl returning the URL of the page for the entry in Lotus Connections corresponding to this story. 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. 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

27 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. 4.4 Handling internationalization Until 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/ 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: 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. Add the corresponding string in French in notification_fr.properties: 27

28 OPEN_ITEM=Ouvrir élément dans navigateur 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> 4.5 Deploying customized template and resources files to a production environment To deploy the customized template files and associated resources (images) onto a production environment, the recommended steps are to: Deploy the customized template files onto the Deployment Manager (DM) node of the deployment. The digest template files for digest are located under <WAS-install>/AppServer/profiles/<Dmgr>/config/cells/<cellName>/LotusConnectionsconfig/news/ You may also deploy any new image file referenced from the customized templates on the DM node (under /news/ /images). 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 and administrating notifications for more details.) 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

29 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 notifications Let's now discuss in more detail how to customize individual notifications. 4.1 Individual templates Templates define the output of 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 s 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 s 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 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 digests, the News aggregation service also delivers individual notifications. Individual notifications are sent to users when updates occur for the places, people, and items the user follows across the Connections services. Refer to 3 Notification content and the Following concept in Lotus Connections for more details. NOTE: The templates for daily and weekly 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 digest templates can also be applied to customizing individual notifications using this technology (Files, Wikis, and individual notifications from News). 29

30 Customizing notifications in a nutshell Customizing 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 edit To 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 Lotus Connections 0 for a detailed list of notification s and their associated template files. 4.3 Variables and dynamic content A 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 template Table 1 lists the variables that are available in any template type. Table Variables and their descriptions Variable name Description {notification.sender.name} The notification's sender name {notification.sender. } The notification's sender address 30

31 {notification.replyto.name} The notification's reply name {notification.replyto. } The notification's reply 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 type In 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 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 Variables available for each template Service Notification name Template 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 autocompleteactivit No Variables ymail.jsp create creat .jsp No Variables notify notifymail.jsp {message} {activity.node.description} {activity.node.related.valuelabel} Bookmarks notify notifytemplate.jsp {bookmarktitle} {sendername} {comments} {helpurl} notifyreplaceu RL replaceurltemplate.j {bookmarktitle} sp 31

32 {origurlstr} {replaceurlstr} {editbookmarkurl} {brokenbookmarkurl} {replaceurlstr} {mybookmarksurl} Wikis commentadd commentadded.ftl ${notification.actor.name} ${notification.actor.name} ${notification.actor.name} roleadd librarymemberupdat ${wikimemberadd} ed.ftl ${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 collectionmedia collectionmediaadd ${notification.actor.name} Add ed.ftl ${notification.media.label} ${containername} ${subject} ${header} ${(notification.media.summary) ${notification.media.url} $ 32

33 {notification.media.download.url} $ {notification.media.subscribe.url } ${(notification.media.tags) collectionmemb collectionmemberup ${notification.actor.name} erupdate dated.ftl ${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) communityvisibi communityvisibility ${notification.community.title} lityupdate Updated.ftl ${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.summar y} 33

34 $ {notification.media.download.url} $ {notification.media.library.name} ${notification.media.library.url} Profiles notify invitecolleagu . {sender.profile.url} jsp { .invite.sender.name} { .invite.body} {accept.invite.url} notifyboardown notifyboardownerf erforcomment orcomment.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} notifyboardown notifyboardownerf erforentry orentry.jsp {board.actor.profile.url} {board.actor.name} {board.entry.text} {board.owner.profile.url} {board.entry.text} notifyentryown erforcomment notifyentryownerfo {board.actor.name} rcomment.jsp {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

35 {community.name} invite invitedtojoinmail.jsp {community.name} {community.description} {join.community.url} {decline.invite.url} {template.url.prefix} memberadded memberaddedmail.js {community.name} p {community.description} {community.url} {leave.community.url} memberremov memberremovedmail community.name} ed.jsp reject rejectnotic .jsp {reject.explanation} {community.name} {community.description} Blogs approvedcomment approved_comment. {item.correlation.url} jsp {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- confirmflagged_com {reporter} comment ment.jsp {item.name} 35

36 {administrator. } {lotusconnections.home} confirmflagged- confirmflagged_entr {reporter} entry y.jsp {item.name} {administrator. } {lotusconnections.home} notifyflaggedcomment notifyflagged_comm {item.correlation.name} ent.jsp {reporter} {item.content} {comment} {item.review.url} notifyflaggedentry notifyflagged_entry.j {item.correlation.name} sp {reporter} {item.content} {comment} {item.review.url} {lotusconnections.home} notify {notify.sender} notify.jsp {notify.description} {entry.link} {entry.title} {entry.website.name} {entry.author} {lotusconnections.home} notifyrepostedentry notifyreposted_entr {item.review.url} y.js {item.name} {submitter.name} {item.content} {item.review.url} {lotusconnections.home} 36

37 notifyreviewcomment notifyreview_comm ent.jsp {item.correlation.name} {submitter.name} {item.review.url} {item.content} notifyreviewentry notifyreview_entry.j sp {item.correlation.name} {submitter.name} {item.review.url} {item.content} notifyreviewtrackback notifyreview_trackb {mail.subject} ack.jsp {item.correlation.name} {item.correlation.url} {item.content} {lotusconnections.home} notifyupdatedentry notifyupdated_entry. {entry.title} jsp {editor.name} {entry.edit.link} {entry.link} {lotusconnections.home} ownermsg ownermsg.jsp {comment.creator} {entry.title} {comment.content} {comment.deleteurl} quarantinedcomment quarantined_comme {reviewer.name} nt.jsp {item.content} {comment} {reviewer. } quarantinedentry quarantined_entry.js {reviewer.name} p 37

38 {item.content} {comment} {reviewer. } rejectedcomment rejected_comment.j {reviewer.name} sp {item.content} {comment} {reviewer. } rejected-entry rejected_entry.jsp {reviewer.name} {item.content} {comment} {reviewer. } restoredcomment restored_comment.j {reviewer.name} sp {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 38 DigestBean. This variable is an instance of the a class with interface I DigestStory.

39 4.4 template localization 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 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 s based on JSP files To 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 Components and their resource files Component I18N resources files Resources file folder Activities resources.properties oawebui.war/webinf/lib/oawebui.jar/com/ibm/openactivities/web/coreui/res ources Bookmarks resources.properties dogear.webui.war/webinf/lib/dogear.svc.jar/com/ibm/dogear/resources Communities resources.properties comm.web.war/webinf/lib/comm.web.jar/com/ibm/tango/ /resources/reso urces Profiles mail.properties peoplepages.war/webinf/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 folder File Language resources_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

40 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 { }: .open.activity=open this activity .notify.body. .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 Default 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=" %> [ jsp code ] <fmt:message key=" .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

41 based on FreeMarker templates Connections Files and Wikis use FreeMarker templates. News (aggregation service) also uses the FreeMarker template for generating the content of daily and weekly 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 folder News notification.properties LotusConnections-config/news/ Files notification.properties LotusConnections-config/files/ Wikis notification.properties LotusConnections-config/wikis/ 4.5 Examples of individual template customization The examples in this subsection describe the most common type of customizations: Changing the styles of the notification s Updating, removing, or adding new messages (strings) to the s 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 messages The typical way to do this is: Establish the relationship between the to customize and the action in Lotus Connections generating the . Based on this relationship, retrieve the original template file responsible for the generated . See 4.2 Locating the template file to edit for more details. Copy the template file to a working folder. 4. Edit the template to apply the customization. 5. Stop the application generating the 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 JSP template files for more details. Let's show how to change the color of the text of the generated by Lotus Connections Communities when a user broadcasts a message to the community. The default generated by Communities in Lotus Connections 0 is shown in figure 2 41

42 Figure 2 Out-of-the-box broadcast community -notification message This message is sent on the following action: 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. Click the Community Actions button (at the top right-hand corner) and select Mail Community (see figure 22). Figure 2 Mail Community The template file used by Communities to generate the 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

43 Figure 2 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 -notification message after the customizations we've just applied. Figure 24. Final result of the customizations Example 2: Updating localized strings The typical steps used are: Establish the relationship between the and the action in Lotus Connections generating the . Based on this relationship, find the original template file. See 4.2 Locating the template file to edit for more details. 43

44 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 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 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 generated when a user notifies another user about an Activity entry. The template file corresponding to this 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 , in which the two strings ( Activity name and Activity Goal ) to be modified are outlined in the red boxes. Figure 25. Original 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 .activity.name: <b><fmt:message key=" .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: .activity.name=activity name: which we change to: 44

45 .activity.name=activity: The Activity goal message is updated in the same way: .activity.goal=activity goal: to .activity.goal=activity target: Figure 26 shows how the new will look with the new custom messages (outlined in red). Figure 26. generated with the two string modifications made 4.6 Check-in / Check-out scripts to retrieve / update JSP template files As 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 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 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

46 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 file File 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.sh The 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

47 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 edit Variable name Variable description was_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.sh The 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

48 Figure 27. Choose the Activities service Modifying the templates The 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

49 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: Go into the template work directory, and edit the file as needed. If you also want to modify the resources files, go into the i18n folder in the work directory and update the files. Once you've modified the files, you are ready to check them in back to the Connections deployment directories. Running checkin.sh Check-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

50 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 Conclusion After outlining the most important aspects of configuring and administrating notifications in Lotus Connections 0, we provided the details of customizing both the daily and weekly 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 s consistent with your company branding. 50

51 6 Appendix: Comprehensive overview of all notifications in Lotus Connections 0 Here is the list of Lotus Connections components that use mail notifications: Activities Bookmarks Blogs Communities Profiles Files Wikis NOTE: News in Connections 0 is a special component that is responsible for sending digest s based on what a user is following. For each service, this appendix provides a table summarizing the actions that trigger the s, 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: lc Let's begin our comprehensive overview for all the mails and templates presented in Connections Activities Connections 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 message is created following the actions listed in table Table Activities actions and their templates Action Name Template General notification notify {notification.source.url}/ /notify Mail.jsp When the activity is completed autocomplete {notification.source.url}/ /auto CompleteActivityMail.jsp Create a new activity create {notification.source.url}/ /creat .jsp Adding a member to an activity add-member {notification.source.url}/ /add MemberMail.jsp Notify users about an activity entry You can generate the notification (see figure 1) by following these steps: 4. Go to Lotus Connections Activities. 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. Open an existing entry or create a new one. Click More actions and notify people (see figure 1). Template file: {notification.source.url}/ /notifymail.jsp 51

52 Figure New activity notification Notification sent when an activity is completed When an activity's due date expires, an with a general notification that the activity is completed is automatically generated from the system. Activity owners receive an warning them that one of their inactive activities will be marked complete, unless it is updated. To generate the Go to Connections Activities. Select an activity and set a due date. Template file: {notification.source.url}/ /autocompleteactivitymail.jsp Notification sent to member of a new activity A general notification is automatically sent to activity members who are added when a new activity is created. To generate the notification (see figure 2): Go to Lotus Connections Activities. Click Start a new Activity. Fill in the form and save it. Template file: {notification.source.url}/ /creat .jsp Figure New member notification for new activity 52

53 Notification sent to members added to an existing activity When 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): Go to Lotus Connections Activities 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. In the Members area, click Add a member. Template file: {notification.source.url}/ /addmembermail.jsp Figure New member notification for existing activity 6.2 Bookmarks Connections 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 notifications. In Bookmarks a mail message is created following the actions in table Table Bookmarks actions and their templates Action Type Template Notify 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: lc Notify a user about a bookmarks Users can send notifications to other users to inform them about useful bookmarks (see figure 4). To do this: Go to Lotus Connections Bookmarks. Click More next to a bookmark. 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

54 Template file: {notification.source.url}/templates/notifytemplate.jsp Figure 4. Useful bookmark notification Notify a user about a broken bookmark Users can send a notification to the bookmark author to inform him/her about a broken bookmark link (see figure 5). To do this: Go to Lotus Connections Bookmarks. Click More Actions next to a bookmark. Click Flag as Broken URL. Template file: {notification.source.url}/templates/replaceurltemplate.jsp Figure 5. Broken bookmark notification 6.3 Blogs The 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 message is sent for the following the actions in table Table Blogs actions and their templates Action Type Template A user notify another user of a given blog posts notify {notification.source.url}/templates/ notifytemplate.jsp Notification sent when a new ownermsg comment is posted to owner of the blog {notification.source.url}/notification s/ownermsg.jsp 54