Skip to main content
Version: v5.1

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:

ParameterTypeDescription
cancelAllLinkStringURL to block the device from receiving notifications. Should always be included in a normal email template.
cancelLinkStringURL to cancel the subscription. Should always be included in a normal email template.
acceptLinkStringURL to confirm the subscription. Should only be included in emails associated with the SUBSCRIBE_VERIFY action in a sender.
requestObjectThe request payload (for an EVENT trigger, this is the body of the event).
deviceDeviceThe device object (fields are those on the Device object: email, id, owner, etc.).
senderSenderThe sender object (fields are those on the Sender object: id, email, displayName, etc.).
groupGroupThe 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);