Editing CR4 templates for single emails

HCL Connections™ CR4 offers new ways to customize the standard email messages that are sent by the applications in HCL Connections, including the auto-generated notifications that are generated by the News application.

Before you begin

Important: Before making any customizations, first back up your original notifications folder. In addition, ensure that any customized files are backed up before performing a product upgrade or applying a cumulative refresh or fix pack, as you might need to merge your changes again manually after making updates.

To customize a template

All customization illustrated in this document assumes that the templates are updated by the following procedure.

1. Locate the FreeMarker template that corresponds to the notification that you want to customize. For more information about the notification types used in HCL Connections, see Notification types.

   Notification templates are stored in the following location:

   app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/

   where app_server_root is the WebSphere® Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.

   You can find folders for each application in this location and a shared resources folder. Look for the FreeMarker template for the notification that you want to customize in the relevant application folder. When you find the template that you want to modify, open the .ftl file in a text editor.

2. Make your customizations to the template as needed.

   Note:

   • See CR4 notification template reference.
   • See Customizing shared resources for notifications (CR4 templates). For information about editing the templates, refer to the FreeMarker documentation on the following web page:

   http://freemarker.sourceforge.net/docs/index.html

   The FreeMarker version currently used is 2.3.28.

3. Save your changes and then close the file.

4. Synchronize all the nodes using the Integrated Solutions Console.
5. Stop and restart the News application.

Deprecated resources and content

To facilitate a cleaner and more focused design, some elements present in the pre-CR4 templates have been removed. Where possible, the content has been moved to sections of the templates commented "Deprecated" to retain the original content for reference. Not all pre-CR4 content is present in the new templates so it may be necessary to refer to the pre-CR4 templates for reference.

Changing the title of a notification

In each notification template file, there is a variable used to define the document title.

<#-- Title of notification -->
<#assign title = STRING />

This variable is passed to the commonStructure (comStructure) document macro and can either be set to a literal string or make use of localized resource strings.

The resource strings can be identified by the call to comUtil.resource() requesting a formatted string from one of two locations:

• the application property files, {APPLICATION} being the application name (activities, blogs, etc.)

  app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/{APPLICATION}/resources/nls

  common resource property files

  app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/resources/nls

Note:

• Some titles are defined conditionally based on other properties of a notification.
• The value is sanitized by commonUtil (comUtil) convertHtmlStructuresToText function.

Changing the subject of a notification

In each notification template file, there is a variable used to define the document subject. This is displayed (styled in bold by default) at the top of the notification body.

<#-- Subject of notification -->
<#assign subject = STRING />

This variable is passed to the commonStructure (comStructure) subject macro and can either be set to a literal string or make use of localized resource strings.

The resource strings can be identified by the call to comUtil.resource() requesting a formatted string from one of two locations:

• the application property files, {APPLICATION} being the application name (activities, blogs, etc.)

  app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/{APPLICATION}/resources/nls

• common resource property files

  app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/resources/nls

Note:

• Some subjects are defined conditionally based on other properties of a notification or through utility functions.
• The value is sanitized with commonUtil (comUtil) convertHtmlStructuresToText function.
• The value is processed with commonUtil (comUtil) breakLongWords function.

Changing notification actions

Many notifications have actions associated with them. The two most common actions are to open the notification in Connections and to open the notification in the Connections mobile application.

Note: Not all notification templates follow this exact pattern due to functional differences. This can be used as a reference for altering or adding actions in those cases.

Additional actions can be added to the actions list variable.

<#-- Actions -->
<#assign actions = [ LIST ] />

This variable is passed to the commonStructure (comStructure) actions macro via the commonStructure (comStructure) noteItem macro.

Each list element can be either a (label, url) collection entry or a string containing a pre-built anchor link.

• Collection entries can be constructed using the commonUtil (comUtil) entry function.
• Pre-built anchor links can be constructed using the commonUrlUtil (comUrlUtil) linkify functions.

Action labels are predominantly defined in the localized resource strings.

The resource strings can be identified by the call to comUtil.resource() requesting a formatted string from one of two locations:

• the application property files, {APPLICATION} being the application name (activities, blogs, etc.)

  app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/{APPLICATION}/resources/nls

• common resource property files

  app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/resources/nls

Note:

• Some actions are defined and/or enabled conditionally based on other properties of a notification or through utility functions.
• The action list is often constructed incrementally throughout the template.

Changing notification metadata

Metadata is displayed as key:value data in notifications and represents items such as a community or activity name.

Most metadata present in the pre-CR4 notifications has been removed or is only displayed conditionally to facilitate a streamlined and more efficient design. Where deprecated items are not present, the pre-CR4 templates can be used as a further reference for items available in each template.

Items can can added, removed, or edited in the metadata list variable.

<#-- Meta -->
<#assign metadata = [ LIST ] />

Each list element is a (key, value) collection entry constructed with the commonUtil (comUtil) entry function.

Note:

• Some metadata items are defined and/or enabled conditionally based on other properties of a notification or through utility functions.
• The metadata list is often constructed incrementally throughout the template.

Changing notification message content

Message content is added to notifications using calls to the commonStructure (comStructure) message macro.

<@comStructure.message>TEXT</@comStructure.message>

Multiple messages are often achieved with sequential calls, each formatted roughly as a paragraph.

Static message content can be found in the localized resource strings.

The resource strings can be identified by the call to comUtil.resource() requesting a formatted string from one of two locations:

• the application property files, {APPLICATION} being the application name (activities, blogs, etc.)

  app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/{APPLICATION}/resources/nls

• common resource property files

  app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/resources/nls

Changing footer links in notification

Footer links are displayed as text links, like "Edit Notification Settings", at the bottom of a notification.

Other links can added to or replace the existing footer links by editing or adding the call to the commonStructure (comStructure) footer macro.

<@comStructure.footer [LIST]>

Each list element can be either a (label, url) collection entry or a string containing a pre-built anchor link.

• Collection entries can be constructed using the commonUtil (comUtil) entry function.
• Pre-built anchor links can be constructed using the commonUrlUtil (comUrlUtil) linkify functions.

The link labels are often defined in the localized resource strings.

The resource strings can be identified by the call to comUtil.resource() requesting a formatted string from one of two locations:

• the application property files, {APPLICATION} being the application name (activities, blogs, etc.)

  app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/{APPLICATION}/resources/nls

• common resource property files

  app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications_v2/resources/nls

By default, any links passed to the footer macro will be appended to the "Edit Notification Settings" link. This default link can be disabled by setting the optional "append" parameter to false in the footer macro call.

<@comStructure.footer [LIST] false>

Enable live profile links for @mentions

The active links for @mentions have been converted to text in the CR4 templates to facilitate a cleaner layout.

These links can be re-enabled by the profile link formatting parameters.

The parameters are defined in the LinkFormatArgs variable included in the following two files:

• commonStyleUtil.ftl
• newsUtl.ftl

The LinkFormatArgs variable is a hash containing formatting options for each of the six types of links. The 'profile' section controls how @mention links are formatted. The default method of text, shown below, causes @mention link to be converted to text, using the body of the link for content.

'profile': {
    'method': 'text'
}

To enable live @mention links to the user's profile page in Connections, change the method to 'pass'. This will allow the live links.

'profile': {
    'method': 'pass'
}

This change can be enabled in either commonStyleUtil.flt, newsUtl.flt, or both to allow for independent control of @mention link formatting.

Parent topic:Customizing notifications sent as single emails