Version: v5.0

Templates

Overview#

A template is an outline of the email notification which is sent out to invite people to subscribe to a group. This is similar to how templates are used in the Passport Service.

Velocity templates#

In a template object, the subject and body properties are Velocity templates. Velocity is a Java-based template engine. For more information on Velocity, visit Apache Velocity Project.

Template properties#

General template properties#

When you create a template, the following properties are supported:

_namespaces: A string array, which must contain a single item, which is the owning namespace for this template. The user must have the create permissions in this namespace for the IRN notificationsvc:template:*.
_name: An immutable user-friendly name that must be unique within the namespace.
_description: An optional description.
_format: Currently, only VELOCITY is supported.
_transport: Currently, only EMAIL is supported.
_locale: The locale of the template, must be a standard IETF language tag.

The rest of the properties available for a template depend on the value of the _transport property which currently can only be EMAIL. When transport is EMAIL the following properties are supported:

_email.subject: A Velocity template for the email subject.
_email.body: A Velocity template for the email body.

Velocity templates parameters#

In a Velocity template the following parameters are available:

Parameter	Type	Description
`cancelAllLink`	String	URL to block the device from receiving notifications. Should always be included in a normal email template.
`cancelLink`	String	URL to cancel the subscription. Should always be included in a normal email template.
`acceptLink`	String	URL to confirm the subscription. Should only be included in emails associated with the `SUBSCRIBE_VERIFY` action in a sender.
`request`	Object	The request payload (for an EVENT trigger, this is the body of the event).
`device`	Device	The device object (fields are those on the Device object: email, id, owner, etc.).
`sender`	Sender	The sender object (fields are those on the Sender object: id, email, displayName, etc.).
`group`	Group	The group object, if present. Fields are those on the Group object.

Template guidelines#

Some general guidelines for using templates, include:

Always include cancelLink and cancelAllLink in your email templates to allow user control.
Include the acceptLink only for emails related to the SUBSCRIBE_VERIFY action in a sender.

Velocity template examples#

Standard Notification Email (Velocity syntax)#

<html>  <body>    <h2>Hello from $applicationName!</h2>    <p>Your device: $device.email.address</p>    <p>      <a href="$cancelLink">Cancel Subscription</a> |      <a href="$cancelAllLink">Block Device</a>    </p>    <p>Request details: $request</p>    #if($group)      <p>Group: $group.name</p>    #end  </body></html>

SUBSCRIBE_VERIFY Email (Velocity syntax)#

<html>  <body>    <h2>Subscription Verification - $applicationName</h2>    <p>Your device: $device.email.address</p>    <p>      <a href="$acceptLink">Confirm Subscription</a>    </p>    <p>Request details: $request</p>    #if($group)      <p>Group: $group.name</p>    #end  </body></html>

Using the Template API#

This section lists some useful examples of using the Notification Service API to perform operations with templates.

For a full reference to the Template API, refer to the Template Rest API page.

How to create a template#

To create an EMAIL type template, refer to the sample code below.

const template = await IafNotification.createTemplate({    _namespaces: project._namespaces,    _transport: "EMAIL",    _name: "template_name",    _format: "VELOCITY",    _locale: "en-GB",    _email: {        _body: "template body"    }}, ctx);

How to update a template#

To update the body of an email type template, refer to the code below.

const template = await IafNotification.updateTemplate(template._id, {    _email: {        _body: "new template body"    }}, ctx);

How to list templates#

To list templates, you must provide a query. The query must include at a minimum, a set of namespaces for which the calling user has READ permissions.

To query for templates in your project, refer to the sample code below.

const templates = await IafNotification.listTemplates({    namespaces: project._namespaces}, ctx);

The following query properties are supported:

namespaces
name
locale
transport

Note: These query properties map to the same properties used when creating or updating templates.

How to delete a template#

To delete a given template, refer to the sample code below.

await IafNotification.deleteTemplate(template._id, ctx);