Customizing email notifications using the app registry
If Component Pack for HCL Connections™ is installed in your deployment, you can use the app registry to change the look and content email notifications and newsletters, making them particular to your organization.
About this task
You can add or override the defaults for several characteristics of the email notifications sent by Connections to users: company name, sender name and email, application icon, company logo, background colors, date format, maximum number of events, placement of the name of the specific Connections application that the notification was sent from, footer, and whitelisted domain names that allow links within those domains to be live.
The following procedure explains how to use the cloud administration console to create and edit an app/organization extension that you can use to make these customizations.
Procedure
- Log in as a user with Organization Administration privileges, click Admin on the navigation bar and then click Manage Organization.
- In the navigation, click Organization Extensions.
- Click new Apps Manager.
-
Create the application:
- Click New App.
- Click App Name and enter a name for the app, for example, Notifications <org name>.
- Click Short Description and enter a brief description, for example, Notification customizations <org name>.
- Click Next.
-
Create the extension:
-
In the Extension JSON Editor, inside the brackets after
payload, enter the property name and value for only the attributes that you
want to add or change. Use the following information to help ensure that you enter the additions or
changes in the proper format:
- To customize the company name used in the email subject and body:
- Change "Connections Cloud" to your company name by adding the platformName
property in the payload, making the value your company name, as in the following
example:
"platformName": "Renovations"
- Hide "Connections Cloud" or your company name by setting this property to an empty
string.
"platformName": ""
- Change "Connections Cloud" to your company name by adding the platformName
property in the payload, making the value your company name, as in the following
example:
- To customize the sender name and email used in notifications and email digests:
- To make the name and email of the sender something meaningful for your organization, for example
<Renovations-Newsflash@example.com>, in the payload section add the
lines for the orgSenderEmail and orgSenderName properties,
making the values what you want users to see, as in the following
example:
"orgSenderEmail": "Newsflash@example.com", "orgSenderName": "Renovations"
- To make the name and email of the sender something meaningful for your organization, for example
<Renovations-Newsflash@example.com>, in the payload section add the
lines for the orgSenderEmail and orgSenderName properties,
making the values what you want users to see, as in the following
example:
- To customize the application icon image:
- Displaying the iconThe photoType property displays an image of the icon for the particular Connections application sending an email notification. The default is to display these icons, using the following property setting:
"photoType": "stock"
- Icon background colorThe stock application icon images have transparency, and you can therefore make use of a customized background color. To change the background color behind the image, add lines for the
sidebarBackgroundColor
property in the payload section, setting it to the desired color as an RGB hex triplet or as "transparent"."style": { "sidebarBackgroundColor": "#3d6cf0" }
- Hiding the iconIf you don't want to display an application icon in notifications, set the photoType property to empty ('').
"photoType": ""
- Displaying the icon
- To customize the company logo:Note: Supported image file formats are jpg/jpeg and png (under 40Kb in size due to email client restrictions).
- Logo imageAdd the orgIcon property, making the value the base64 encoded string for the file that contains your company logo. The orgIcon data is truncated in this example for brevity.
"orgIcon":"data:image/png;base64,..."
- Image width
The width of the logo is not scaled, but the default width of the notification container is 600 pixels and larger images could result in layout issues.
- Image background colorLogo images with transparency can make use of a customized background color. To change the background color used behind the logo, add the
mastLogoBackgroundColor
style property and set it to the desired color as an RGB hex triplet or as "transparent". The default value of "transparent" allows the body background color to show through."style": { "mastLogoBackgroundColor": "#eeeeee" }
- Hide logo imageIf you don't want to display a logo in notifications, the image can be disabled by setting the image height to zero.
"style": { "mastLogoHeight": "0" }
- Logo image
- To customize the background colors in the notification:
- Notification bodyTo change the overall background color of the notification, add the
bodyBackgroundColor
style property to the payload and set it to the desired color as an RGB hex triplet."style": { "bodyBackgroundColor": "#eeeeee" }
- Notification message contentTo change the background color of the notification message content section, add the
messageBackgroundColor
style property and set it to the desired color as an RGB hex triplet."style": { "messageBackgroundColor": "#ffffff" }
- Notification body
- To customize the date format used in notifications:
- Add the activityDateFormat property, making the value the date format that
you want. You can use any of the formats specified by the International
Components for Unicode (ICU) specification. For example, in the United States locale, you
could use "MM/d/yy" to display a date like 01/24/19, or "EEE, MMM d,
yyyy" to display one like Thu, Jan 24,
2019.
"activityDateFormat": "dd MMM"
- Add the activityDateFormat property, making the value the date format that
you want. You can use any of the formats specified by the International
Components for Unicode (ICU) specification. For example, in the United States locale, you
could use "MM/d/yy" to display a date like 01/24/19, or "EEE, MMM d,
yyyy" to display one like Thu, Jan 24,
2019.
- To customize the maximum number of events displayed in the daily or
weekly newsletter:
- Add the activityMax property to the payload, making the value the number
that you want.
"activityMax": "25"
- Add the activityMax property to the payload, making the value the number
that you want.
- To customize the placement of the Connections application name in the
subject line:This name shows which application the notification is coming from.
- Add the subjectAppNameAppend property and set it to the placement you want.
"subjectAppNameAppend" : "tail"
Valid values are as follows:tail
is the default value, displaying the application name at the end of the subject line.head
displays the application name at the beginning of the subject line.none
causes no application name to be displayed.
- Add the subjectAppNameAppend property and set it to the placement you want.
- To add or customize the footer in notifications:
- Add the orgFooter property and set it to what you want the footer in
notifications to say. If you include a link in the footer, you must use the format [website label]
(website URL) and make sure that the domain that contains the website is listed in whitelist
described in the following section. Here's an example of a footer that includes links:
"orgFooter": "To contact support, please visit [Support] (https://renovations.com/support). For more information, please visit [Renovations] (https://renovations.com). Thank you!"
- Add the orgFooter property and set it to what you want the footer in
notifications to say. If you include a link in the footer, you must use the format [website label]
(website URL) and make sure that the domain that contains the website is listed in whitelist
described in the following section.
- To add or customize the whitelisted domain names that exempt live links
from those domains from being "stripped" of their HTML anchor tags in notifications:
- Add the liveLinksWhitelist property and set it to one or more domain names
for the domains whose URL's you consider safe to display as-is in notifications. Separate the domain
names with commas.
"liveLinksWhitelist": "example1.com, example2.com, example.com"
By adding the domains to the whitelist, you can help users confirm that the locations indicated by the clickable URLs in notifications are the actual destination. For example, if a link is to a destination outside of your whitelisted domains, it will be "stripped" of misleading text in the URL. The label and destination of any link that is not from an approved domain will be rendered as shown in the following example, allowing the user to see that the label does not match the destination:www.safe.com [<a href="http://www.unknown.com>www.unknown.com</a>;]
Tip: Because link stripping tends to add clutter to email notifications by displaying the full URL and title of the anchor tag side by side, it is best to add trusted domains to the whitelist so that only the intended link text gets displayed. - Add the liveLinksWhitelist property and set it to one or more domain names
for the domains whose URL's you consider safe to display as-is in notifications. Separate the domain
names with commas.
- Review all additions/changes to the payload. If you chose to add multiple properties, your
payload field might look something like
this:
"platformName": "Renovations", "orgSenderEmail": "Newsflash@example.com", "orgSenderName": "Renovations, "photoType": "", "orgIcon": "data:image/png;base64,...", "style": { "bodyBackgroundColor": "#eeeeee", "sidebarBackgroundColor": "#3d6cf0", "messageBackgroundColor": "#ffffff" }, "activityDateFormat": "MM/d/yy", "activityMax": "10", "subjectAppNameAppend": "none", "orgFooter": "To contact support, please visit [Support] (https://test.com/support). For more information, please visit [Test site] (https://test.com). Thank you!", "liveLinksWhitelist": "example1.com, example2.com, example3.com"
- To customize the company name used in the email subject and body:
-
Click Add to enter your customizations into the payload and then click
Save to save the extension. You can return to the extension later if you want
to add or change other properties.
Note: If you later decide that you don't want to show an element, you must delete only the value (""), not the entire property.
-
If you no longer want to use the currently enabled notification customizations, perform the
following steps to disable the organization extension: