Invite Notification Message Templates

Overview

Helium provides built-in functionality for sending invitation messages to users that are newly invited to the platform, or to a new application role. A new feature since Helium 1.6.0 allows users to specify custom invite message templates for Helium apps. These templates can be specified as follows:

• As part of the app source code which will result in it being associated with the app release
• On the Helium core web app which will result in it being associated with the app itself

If no invite message templates are specified for the app, the templates for the app release will be used. If no templates are specified for the app release, the system default invite messages will be used.

Custom Message Fields

The invite message content is specified using message templates. These templates allow for the use of variables that are associated with the Helium app. The following variables are available:

• appUrl
• heliumUrl
• roleName
• appName
• userName
• password

These variables are referenced in message templates using $ and curly brackets as shown below:

You have been invited to the ${appName} app. Please log in at ${appUrl} using the username ${userName} and password ${password}.

In addition to the message content, the message subject can also be specified for e-mail invite messages. See the list below for all fields that can be specified for custom invite messages:

• New user invite SMS message template
• New role invite SMS message template
• New user invite e-mail message subject
• New user invite e-mail message template
• New role invite e-mail message subject
• New role invite e-mail message template

Specifying Custom Invite Message Templates for App Releases

The custom invite message templates can be specified per app release by including a json representation of the relevant fields as part of the application source code. This will result in all apps for the release using these templates given that no templates have been set for the app itself. If custom invite message templates have been set on the app itself these will be used instead.

Invite message templates for app releases should be located in files place directly in a "notification-templates" folder in the application root directory. Each file in this folder, represents invite message templates for a specific locale and as such the file name should reflect this. This is similar to how properties files are specified for DSL apps in the lang folder.

The example below shows the content of such a file placed in the "notification-templates" folder with en.json used as file name. Note the available json fields:

{
    "newUserSmsMessage": "Welcome to Helium. To start using ${appName} log in at ${appUrl}. Please use username ${userName} and password ${password}.",
    "newRoleSmsMessage": "Welcome to ${appName}. Your user with username ${userName} has been invited as a ${roleName}. Log in at ${appUrl}",
    "newUserEmailSubject": "New user invitation for ${appName}",
    "newUserEmailMessage": "Welcome. To start using ${appName} log in at ${appUrl}. Please use username ${userName} and password ${password}.",
    "newRoleEmailSubject": "New role invitation for ${appName}",
    "newRoleEmailMessage": "Welcome to ${appName}. Your user with userName ${userName} has been invited as a ${roleName}. Log in at ${appUrl}"
}

Specifying Custom Invite Message Templates for Apps

In addition to specifying custom invite message templates for app releases, they can also be specified for the app itself. If set, Helium will use app specific templates even if app release specific templates have been specified. App specific invite message templates can be specified using the Helium core app when creating an app or when updating an app. These values can be specified and edited by selecting the "Template" tab from the app create and update views:

Note the place marker text in the text areas above to list the available parameters and to show an example of their usage. 

Triggering Use of Templates

Usage of the templates is triggered by simply inviting a user from the context of an app using the invite built-in function or by inviting users for a specific app from the Helium core app. Note that signing up from the Helium login page is not within the context of an app and will thus not use any app specific templates. In that case the system default invite messages will be sent.

All invitations for new users and app roles will result in invite notifications using SMS. In the case of an invitation triggered using the new invite built-in function, which takes both mobile number and e-mail address as arguments, an e-mail will be sent in addition to the SMS.