Handlebars Templates

Patriot supports handlebars templates for custom message formats.

Data Types

The data Patriot provides when rendering templates depends on the message context:

• StandardMessage - Manual Messaging (including manual Bulk Messaging).
• SignalMessage - Response Plan task assignment message. Triggered when a signal logged with the appropriate response plan assigned.
• PatrolDispatchMessage - Web Dispatch request/standdown email.

StandardMessage

Field Name	Data Type	Notes
User	User	The user the message is being sent to (if available)
Client	Client	The client the message is being sent to (if available)

note

For standard messages some fields are only available when applicable; for example:

• When sending a message to a client's contact number/email address (i.e. from the Client Contact tab or from Bulk Messaging) the User field will be unavailable.
• When sending bulk Messages to a number of Users the Client field will be unavailable.
• When sending bulk Messages to a number of manually entered destinations neither the Client or the User fields will be unavailable.

SignalMessage

Field Name	Data Type	Notes
User	User	The user the message is being sent to
Signal	Signal	The signal which triggered the message
MessageId	string	The Message ID is used for responding to First Response messages
HostName	string	The name of the machine where the message was generated

PatrolDispatchMessage

Field Name	Data Type	Notes
MessageType	string	One of the following values: DISPATCH_REQUEST STANDDOWN
MessageTypeDescription	string	Human-friendly (and translatable) description of MessageType: Dispatch Request Stand Down
User	User	The user the message is being sent to
DispatchURL	string	The URL used to respond to the dispatch request
Dispatch	PatrolDispatch	The signal which triggered the message
StanddownReason	string	Only included if this is a STANDDOWN message type

User

Field Name	Data Type	Notes
UserId	number
Name	string
Email	string
MobileEmail	string
PhoneNo	string
MobileNo	string
FaxNo	string
AfterHoursNo	string
PagerNo	string

Signal

Field Name	Data Type	Notes
Client	Client
Activation	Activation
SignalId	number
ActionPlanId	number
ActivationId	number
DateTime	DateTime
TypeNo	number
ModuleNo	number
ZoneUser	number	The zoneNo or userNo (depending on the signal type)
Description	string
RawData	string
Notes	string

Client

Field Name	Data Type	Notes
ExternalRefNo	number
ClientNoRaw	string	i.e. 123400301 for ClientNo 1234(3)-01
ClientNo	string	Formatted Client No i.e. 1234(3)-01
ClientId	string	i.e. 1234 for ClientNo 1234(3)-01
PortNo	string	i.e. 01 for ClientNo 1234(3)-01
AreaNo	string	i.e. 0003 for ClientNo 1234(3)-01
Name	string
Alias	string
AddressLine1	string
AddressLine2	string
AddressLine3	string
PostCode	string
CityName	string
StateName	string
CountryName	string
PostalAddressLine1	string
PostalAddressLine2	string
PostalAddressLine3	string
PostalCityName	string
PhoneNo	string
MobileNo	string
OkPassword	string
HoldUpPassword	string
Dealer	User	The client's dealer

PatrolDispatch

Field Name	Data Type	Notes
JobId	number
ActivationId	number
Description	string
DispatchDateTime	DateTime
StatusId	number	One of the following: 1 (Complete) 2 (Dispatch Requested) 3 (Accepted) 4 (Cancelled)
StatusLabel	string	Textual representation of the StatusId
CustomerOrderNo	string
DocketNo	string
CompletedDateTime	DateTime	Only set if the dispatch has been completed (or cancelled)
WorkOrderCategory	string
Client	Client
Activation	Activation
RequestForm	CustomForm
ResponseForm	CustomForm

Activation

Field Name	Data Type	Notes
ActivationId	number
Description	string
DateTime	DateTime
ZoneUser	number	The zoneNo or userNo (depending on the signal type)

CustomForm

Field Name	Data Type	Notes
Fields	Array<CustomFormField>

CustomFormField

Field Name	Data Type	Notes
Type	string	One of the following: NUMBER TEXT MULTILINE_TEXT BOOLEAN DATETIME SELECTOR
Name	string	The field name
Value	string	The raw field value
NumericValue	number	Only specified if Type is NUMBER
DateTimeValue	DateTime	Only specified if Type is DATETIME
BooleanValue	boolean	Only specified if Type is BOOLEAN

Partial Templates

Partial templates are able to be reused by other templates. Patrial templates must be stored in <[Storage Directory](../../system/local-storage-directory.md)>/HandlebarsTemplates/Shared. Partials are referenced by their file name without extension (i.e. myPatrial.txt) can be used in the following manner: {{>myPartial}}

Helpers

The following helpers return strings

Text Formatting

The {{format ...}} helper returns a textual representation of the provided value.

This can be used with DateTime, number or any IFormattable value type. For example the template:

Signal occured at
{{format Signal.DateTime 't'}}
on
{{format Signal.DateTime 'm'}}. When contacting us regarding this message please
quote Ticket No #{{format Signal.ActivationId '0000000'}}. Custom formatted
date:
{{format Signal.DateTime 'MMMM dd, yyyy'}}
en-US Format datetime:
{{format Signal.DateTime 'g' 'en-US'}}
es Format datetime:
{{format Signal.DateTime 'g' 'es'}}

Would produce a result as below:

Signal occured at 12:34 pm on 10 June.
When contacting us regarding this message please quote Ticket No #0000123

Custom formatted date: June 10, 2011
en-US Format datetime: 6/10/2011 12:34 PM
es Format datetime: 10/06/2011 12:34

Available Parameters:

• value The value to format. Any value of type IFormattable is allowed (DateTime and number are common cases)
• format Defines the output format
  • For DateTime values this can be either a standard or custom DateTime format string
  • For number values this can be either a standard or custom Numeric format string
  • For other types see IFormattable
• clutureName: string (Optional) Specifies the output culture
  • If specified, must be a supported culture name

Client No Formatting

The {{formatClientNo ...}} converts a raw clientNo into a formatted clientNo for display. This can be used like this {formatClientNo Client.RawClientNo}}

Raw ClientNo: {{Client.RawClientNo}}
Formatted ClientNo: {{formatClientNo Client.RawClientNo}}.

Would produce a result as below:

Raw ClientNo: 1234BASE01
Formatted ClientNo: 1234-01.

Or similarly:

Raw ClientNo: 1234000301
Formatted ClientNo: 1234(3)-01.

Available Parameters:

• value The value to format. Only RawClientNo is accepted here.

Substring

The {{subString ...}} helper returns a substring of the provided value.

Given a string A long value:

{{subString 'A long value' 2}}
{{subString 'A long value' 2 4}}
{{subString 'A long value' 6 -4}}
{{subString 'A long value' -10}}
{{subString 'A long value' -10 4}}
{{subString 'A long value' -6 -4}}

Would produce a result as below:

long value
long
long
long value
long
long

Available Parameters:

• value The value to format. This accepts only string inputs.
• startIndex The index to start the substring from.
  • A negative value can be used to start from the end of the original string.
• length (optional) the amount of characters to take from the startIndex.
  • A negative value can be given to take characters from the left of the startIndex.

Logical Boolean Helpers

A number of logical boolean helpers are provided. These helpers return either True or False and are useful in conjunction with the built-in #if and #unless helpers. For example the template:

{{#if (or (gte 100 Signal.TypeNo 109) (gte 1100 Signal.TypeNo 1109))}}
This is an open/close event.
{{/if}}

Would produce a result as below if Signal.TypeNo is in the range 100-109 or 1100-1109:

This is an open/close event.

Available boolean helpers:

• equals True if all parameters are equal
• gt True if each parameter is greater than the preceding value
• gte True if each parameter is greater than or equal to the preceding value
• lt True if each parameter is less than the preceding value
• lte True if each parameter is less than or equal to the preceding value
• and True if all of the parameters are truthy
• or True if any of the parameters are truthy
• regexMatch True if value matches pattern (see Regex Helpers)

Regex Helpers

The regexReplace and regexMatch helpers can be used with .Net Regex Patterns to replace and detect matching text.

Regex Replace

For example the template:

Raw: {{Signal.Description}}
Replaced:  {{regexReplace Signal.Description 'sba' 'Late To Close' 'i'}}

Would produce a result as below:

Raw: SBA - High Priority
Replaced: Late To Close - High Priority

Available Parameters:

• value The value to format. This accepts only string inputs.
• pattern The Regex pattern to use. This must be a valid .Net Regex Pattern.
• replacement The replacement pattern to use. This must be a valid .Net Replacement Pattern.
• options A Regex Options String.

Regex Match

The regexMatch helper returns either true or false and like the Logical Boolean Helpers can be useful in conjunction with the built-in #if and #unless helpers.

I.e.

Raw: {{Signal.Description}}
{{#if (regexMatch Signal.Description 'sba' 'i')}}
This is a Late To Close Alarm
{{/if}}
{{#if (regexMatch Signal.Description 'sbd' 'i')}}
This is a Late To Open Alarm
{{/if}}

Would produce a result as below:

Raw: SBA - High Priority
This is a Late To Close Alarm

Available Parameters:

• value The text to search. This accepts only string inputs.
• pattern The Regex pattern to use. This must be a valid .Net Regex Pattern.
• options A Regex Options String.

Regex Options

RegexOptions are passed a string containing one or more of the following characters:

• i - IgnoreCase
• m - Multiline
• n - ExplicitCapture
• s - Singleline
• x - IgnorePatternWhitespace
• r - RightToLeft
• e - ECMAScript
• c - CultureInvariant

See here for more info

Including Map locations

You can include a link to the location of the site in HTML email messages by using including the following details within anchor tags

<a
  href='https://www.google.com/maps/place/{{Dispatch.Client.AddressLine1}},{{Dispatch.Client.CityName}}'
>
  Show Location On Map
</a>

Including Images

If the template is being used as an html template, it can also contain images. These are included using the src property of appropriate tags, for example

<img src="..." alt="Alarm Header Image" />

The image used needs to be copied onto a publicly accessible webserver, and the src property updated to use a url of the image location. So, a complete example would be

<img src="https://www.yourwebserver.com/image.png" alt="Alarm Header Image" />

Example Templates

Response Plan task assignment examples

An example of a Text version of a template is

Hi {{User.Name}},

The following alarm has occurred at site '{{Signal.Client.Name}}':

{{format Signal.Activation.DateTime 'g'}}
{{Signal.Activation.Description}}
{{Signal.Description}}

Regards,
Alarm Monitoring Company

More examples for download:

• Signal Html Email
• Signal Html Email - Variation 2 with header image and font colours
• Signal Text Message
• Signal Text Message - Variation 2
• Signal Text Message for First Response Notification

Web Dispatch examples

An example of a Text version of a template is

Hi {{User.Name}},

Please respond to the following {{MessageType}}:

{{format Dispatch.DispatchDateTime 'f'}}
{{Dispatch.Description}}
Zone No: {{Dispatch.Activation.ZoneUser}}

{{Dispatch.Client.Name}}
{{Dispatch.Client.AddressLine1}}
{{Dispatch.Client.AddressLine2}}

Regards,
Alarm Monitoring Company

For Web Dispatch, the format should be in html format, to allow for the inclusion of the DispatchURL to link to the responding web page. The above example is only intended to show examples of the fields available.

More examples for download

• Dispatch Html Email
• Dispatch Html Email - Variation 2 with header image, colour & Respond button

Character Encoding

Template files are expected to be in UTF-8 character encoding. This is the default encoding used by most modern operating systems and text editors. However, some international customers may still be using software which saves template files in older ANSI character encodings. e.g. Windows-1253 / ISO 8859-7 (Greek)

To support this scenario Patriot will attempt to read the template files as UTF-8 but if that fails it will fallback to the locale specified in the regional settings of the user's PC. This locale setting can be found in Windows under Control Panel > Region > Administrative > Language for non-Unicode programs

note

Handlebars automatically escapes special characters returned by a {{expression}}. If you wish to prevent Handlebars from escaping a value, use the "triple-stash" syntax, {{{.

Special characters include: & < > ' ` =