Enter your keyword

Custom Notifications and HTML Emails

(Introduced in version 2019.03.02)
We have enabled functionality to allow each alert to have a custom notification message (i.e. the push notification that pops up on your mobile and the subject line in an email) and a custom html email body. This can all be managed through the create/edit view on the Ping web portal but does require knowledge of HTML to ensure the email body will work across different mail clients.

Custom Email Body

To customise the email body you will need to be able to understand and manipulate the HTML. You can import one of the templates as a starting point and these will help you understand the approach to the layout of the template. There is a reason for the structure we have used as each email client renders HTML differently so nesting the tables is the best approach to ensure it is consistent in each client. Of course, you are welcome to use whatever structure you require but we would suggest you test on multiple email clients to ensure it is consistent.

The custom notification/subject is the push notification message for the mobile and the subject line in an email. This enables you to target the message with enough information to act without having to open the body of the record. To give you an idea of how to use this field we have provided the following examples.

In the table below we provide some examples of how you can construct your notification message with simple text and/or using the dynamic variables:

Example Notification/Subject Code Example
Plain text
"PING : You're about to run out of stock"
Using the alert name
"PING : " + {{alertname}}
Single alert example
"PING : " + {{Measures}} + " is " + {{threshold}} + " !"
Drill to dimension alert example
"PING : " + {{DimArrayLength}} + " " + {{dimension}} + " with " + {{Measures}} + " \t " + {{threshold}} + " !"

See the dynamic variables section below for a full list of those that can be used in the notification messages and the email message body.

There is one key requirement when you are using the a custom email body message. You must include the full HTML code syntax structure as outlined below for the email to construct correctly. Use the preview button to review your code to see the structure you have created.

<!DOCTYPE HTML >
<html lang="en">
<head> .... </head>
<body> .... </body>
</html>

 

Importing example templates

In version 2019.03.02 you have the option of importing a html template file into the custom editor so you have a starting example to adapt. You can use one of the following template files, which are copies of the standard templates that are included in the Ping install, to load into this editor.

Standard alert with no filters template
Standard alert with filters template
Drill to dimension alert with no filters template
Drill to dimension alert with filters template

The following are a list of text variables that can be called in the notification/subject and/or body of your customised notification. There are also more complex looping elements you can use which are covered in the next section.

Variable Label Variable Code Description
Recipient User Name
{{UserName}}
Provides the full name of the user to whom the triggered notification will be sent. This can be the owner of the alert, the broadcast alert recipient or the managed shared alert recipient.
Alert ID
{{alertid}}
Provides the Alert ID (GUID) which is used in the unsubscribe URL link. This is not normally presented but may be useful for debugging purposes.
Alert Name
{{alertname}}
Provides the name of the alert record.
Alert Triggered Timestamp
{{triggerTime}}
Provides the timestamp when the alert was triggered in Ping.
Alert Measure
{{Measures}}
Provides the measure name that is scanned for the alert. This can be either the master item label or the entered label for advanced Qlik expressions.
Alert Measure Current Value
{{CurrentValue}}
Provides the current value of the measure at the time of the scan.
NOTE: This variable is does not exist for Drill to Dimension alerts.
Alert Measure Previous / Last Scanned Value
{{PreviousValue}}
Provides the last scanned value of the measure at the time of this scan which can be one of the conditions to compare against.
NOTE: This variable is does not exist for Drill to Dimension alerts.
Alert Condition
{{threshold}}
Provides the conditions that the scan will check againstĀ  to trigger the email. This is shown as a string.
Unsubscribe from Alert URL
{{email.unsubscribe}}
Provides the URL which can be clicked on to unsubscribe to the alert. Allowing users to opt out of an alert if they do not feel it adds value for them.
Ping login URL
{{qliksenseurl.pinghostname}}
Provides the URL which can be used as a link to go straight to the Ping login screen on the web portal.
Qlik Sense Application Name
{{qliksenseurl.appname}}
Provides the name of the Qlik Sense Application which the alert will scan.
Qlik Sense Application ID
{{qliksenseurl.appid}}
Provides the ID of the Qlik Sense Application which the alert will scan.
Qlik Sense Application URL Link (with filters)
{{qliksense_url_dynamic}}
Provides a URL link to the Qlik Sense application which includes the filters and sheet reference as setup in the alert (or derived by the Ping Extension for Qlik Sense).
Qlik Sense Server
{{qliksenseurl.qliksense_url}}
Provides the URL which can be used as a link to go straight to the Ping login screen on the web portal.

There are two types of loops that are used in our default templates. These are used for filters, and the arrays of values associated with them, and for the drill to dimension results.

Loop Variable Type Example code extract
Filter Table Loop Example

This shows all fields that have filters assigned to them (the #filtersetField loop) and the values assigned to them (the #Value loop)

<table style="color:#494848; font-size:13px; line-height:1.8; table-layout:auto; width:100%;">
	<tr style="background-color: #fff">
		<td style="width:40%"><strong>Field</strong></td>
		<td><strong>Selections</strong></td>
	</tr>
	{{#filtersetField}}
		<tr style="border-bottom:1px solid #dfdfdf;">
			<td>{{Field}}</td>
			<td>
				<table style="padding:0px; font-size:13px; width:100%">
					{{#Value}}
					<tr>
						<td>{{qText}}</td>
					</tr>
					{{/Value}}
				</table>
			</td>
		</tr>
	{{/filtersetField}}
</table>
Drill to Dimension Results Loop Example

There is one loop in this example as it is returned as one array of data, the #DimenstionValue loop.

<table style="color:#494848; font-size:13px; line-height:1.8; table-layout:auto; width:100%;">
	<tr style="background-color: #fff">
		<td><strong>{{dimension}}</strong></td>
		<td><strong>{{Measures}}</strong></td>
	</tr>
	{{#DimenstionValue}}
		<tr>
			<td>{{qText}}</td>
			<td>{{qNum}}</td>
		</tr>
	{{/DimenstionValue}}
</table>

A common request, particularly if you are sending alert emails to external organisations, is to be able to embed a logo or other images into the body of the alert. The answer is of course “Yes, you can!”
NOTE: The one provision (as of version 2019.03.02) is that the image is publicly available on a hosted site, such as an image hosted on your organisations website.

To add this functionality you can change the HTML and add an <img> tag as per the example below.

<table width="100%">
    <tr>
        <td align="center" style="padding:10px 25px;">
            <div style="text-align:right">
		<img src="http://help.pingalerting.com/wp-content/uploads/2019/09/Democo_05.jpg" alt="PingLogo" height="64">
            </div>
        </td>
    </tr>
</table>

The email templates can be adapted to provide right-to-left language support for Arabic, Aramaic, Azeri, Dhivehi/Maldivian, Hebrew, Kurdish (Sorani), Persian/Farsi and Urdu. In order to enable this you must change the <style> code at the start of the template. There are two places that you will need to adjust to ensure the template works in right to left format. You will of course need to change the text, the labels and be using an application that is built using the language of your choice.

Orientation Example CSS changes
Default Left-to-Right CSS
<style type="text/css">
	div {
		direction: ltr;
		text-align: left;
		vertical-align: top;
		font-family: Tahoma, Ubuntu, Helvetica, Arial, sans-serif;
	}

	table, th, td {
		direction: ltr;
		text-align: left;
		border-collapse: collapse;
		mso-table-lspace: 0pt;
		mso-table-rspace: 0pt;
		word-break:break-word;
		vertical-align:top;
	}
</style>
Changes for Right-to-Left CSS
<style type="text/css">
	div {
		direction: rtl;
		text-align: right;
		vertical-align: top;
		font-family: Tahoma, Ubuntu, Helvetica, Arial, sans-serif;
	}

	table, th, td {
		direction: rtl;
		text-align: right;
		border-collapse: collapse;
		mso-table-lspace: 0pt;
		mso-table-rspace: 0pt;
		word-break:break-word;
		vertical-align:top;
	}
</style>

The default email templates are shipped with the Ping installer. However, it is possible for an organisation to edit these base templates so that the default emails (and those templates that are imported into the custom editor) are customised for your organisation.

IMPORTANT:

  • You will need to have remote desktop access to the Ping server, or to the C:/ drive folder on this server.
  • You must have edit rights to the files in this location
  • These changes will need to be migrated when you upgrade Ping. You will need to make copies of them and then replace the new templates that will be copied as part of the upgrade. Please ensure that you check if any variables have been updated as you may need to make some changes to your templates over time.

Steps to follow:

  • Navigate to the C:\Ping <version>\server\Connection\EmailHtmlTemplate\ folder
  • Make a backup copy of the file you wish to edit.
  • Edit the .hjs files in any text editor, change the language type when viewing the file to HTML to make it simpler to read.
  • Save and test by creating and triggering an alert.

 

Which files relate to which emails.

Email Type Created Email Template Triggered Email Template
Single measure alert with no filters measureCreateAlert.hjs measureTriggeredAlert.hjs
Single measure alert with filters filterCreateAlert.hjs filterTriggeredAlert.hjs
Drill to Dimension alert with no filters dimensionCreateAlert.hjs dimensionTriggeredAlert.hjs
Drill to Dimension alert with filters dimensionWithFilterCreateAlert.hjs dimensionWithFilterTriggeredAlert.hjs
System Alerts taskCreate.hjs taskTriggered.hjs