Email Template Design Guide
- Ben Worley
- Logan Korn
Overview
The nFORM system supports the ability to define custom content to be delivered via automated emails sent from the nFORM system. The content in the emails can be static or dynamically driven based on data provided in the submission. This capability allows agencies to provide a highly formatted and targeted emails to online submitters.
This document provides the details of the configuration options for these email messages.
Templates
In this section you will find a list all the templates that can be modified by to customize the email messages sent from nFORM to best suit the agency. Most of these templates have their content decided during the configuration of the system and do not ever need to be modified after initial deployment.
A compiled version of the current email content/attributes can be found in the nFORM Email Base Template Attributes document.
External User Emails
The following are system generated emails that are sent to external users.
Template Name | Recipient | Description |
|---|---|---|
ChangeEmailMessage.vm | User with Changed Email (old and new email addresses) | Message sent to submitter to have them confirm change of email. |
ChangePasswordMessage.vm | User with Changed Password | Message sent to submitter to have them confirm a change of password. |
FailedCopyOfRecordMessage.vm | All External Users Associated to the Submission | Message sent to the submitter when the COR creation fails for a submission. |
FailedSigningActivity.vm | User Who’s Submission Signature Failed | Message sent when a signature fails to complete. |
NewPassword.vm | User Changing/Receiving Password | Message sent to a user with a temporary password based on a password reset request from a user or an administrator. |
PendingDeleteMessage.vm | All External Users Associated to the Submission | Message sent to users who have draft submissions that are more than x days old, informing them that the draft submission will be deleted if they do not make a change to it. Number of days is configurable. |
RequestSubmissionInvitationMessage.vm | User Selected Authorized User | In some situations (e.g., authorization prefilled for a submission), when a user gets to the "Certify & Submit" step of the Submission Wizard, if he/she does not have rights to submit the form (for prefilled information - e.g., organization, permit, etc.) they will be presented with a list of users who are authorized to submit the form (for the prefilled information). That user will select an authorized user and click the "Email user" button next to their name. The user will be presented with the email message preview dialog and will click the "Send" button to send the email. |
ReviseApplicationUserMessage.vm | All External Users Associated to the Submission | Message sent when a submission begins the revision process (e.g., revision created). |
SigningCancellationMessage.vm | All Submission Signers (and invited to sign) | Message sent when a signing process is cancelled. |
SigningCompletionMessage.vm | All Submission Signers (and invited to sign) | Message sent when signing process is completed. |
SigningInvitationMessage.vm | User Invited to Sign | Message sent when an individual is invited to sign a submission. |
SigningInvitationRescindMessage.vm | All Submission Signers (and invited to sign) | Message sent when an individual’s invitation to sign a submission is rescinded. |
SigningSignatureReceivedMessage.vm | All Submission Signers (and invited to sign) | Message sent when a signature is received on a submission. |
SigningSignatureRemovalMessage.vm | All Submission Signers (and invited to sign) | Message sent when a signature is removed from a submission. |
SubmissionReviewCompleted.vm | All External Users Associated to the Submission | Message sent when a submission review is completed by a submission processor. |
SubmitApplicationUserMessage.vm | All External Users Associated to the Submission | Message sent when a submission is received by nFORM. |
UpdateAccountLockMessage.vm | Locked/Unlocked User | Message sent to user when their user account is locked or unlocked. |
UserAddedToSubmission.vm | Added User | Message sent when an additional submitter is invited to contribute on a submission by the submission's creator or users who have permissions to invite new users to work on the submission. |
UserRegMessage.vm | Registered User | Message sent when a new user successfully registers in nFORM. |
UserRoleAssignmentMessage.vm | User with Changed Role | Notifies user of changes to the authorization they have. |
Administrative Emails
The following email templates pertain to administrative tasks and are sent to the configured administrative email address.
Template Name | Recipient | Description |
|---|---|---|
FailedSubmissionPaymentCalculation.vm | Administrator | Message sent when a payment cannot be calculated. |
RequestAuthorizedUserMessage.vm | Administrator | Message sent when a user requests verified user rights to submit forms. |
RequestAuthorizedSubmitterMessage.vm | Administrator | Message sent when a user requests authorized submitter user rights to submit forms. |
RequestElectronicSignatorMessage.vm | Administrator | Message sent when a user requests electronic signatory rights to submit forms. |
Submission Processing Emails
The following email templates pertain to submission processing workflow steps. When and to whom these emails are sent is dictated by the way a form’s processing steps and notifications are set up by the form designer.
Template Name | Recipient | Description |
|---|---|---|
ActivateStepMessage.vm | Specified in Processing Step Manager | Message sent when a step is activated, and a notification is configured to be sent. |
CompleteStepMessage.vm | Specified in Processing Step Manager | Message sent when a step action of Send Email is attached to a workflow step with the activation of Step Completed and the step it is attached to is completed. |
StepApproachingTargetDateMessage.vm | Specified in Processing Step Manager (usually an internal user) | Message sent when a step action of Send Email is attached to a workflow step with the activation of Near Target Date and the step it is attached to is approaching its target date. |
StepFeeSatisfiedMessage.vm | Specified in Processing Step Manager | Message sent when a step action of Send Email is attached to a workflow step with the activation of Fee(s) Satisfied and this action occurs for a submission. |
StepPastTargetDateMessage.vm | Specified in Processing Step Manager (usually an internal user) | Message sent when a step action of Send Email is attached to a workflow step with the activation of Past Due and the step it is attached to has passed its completion date. |
Non-Email Documents
The following templates are not used for emails and SHOULD NOT BE CHANGED by customers.
Template Name | Description |
|---|---|
CustomLogoutMessage.vm | Message sent to user when logging out of system. Note: this is a custom template only used by a select few customers. |
FirstTimeLogin.vm | This is not an e-mail. A first login message in a popup that the user must read and can close. This message can be set to “do not show again”. |
FormVersion.vm | Template used for downloaded Submission PDF document. |
SubmissionVersionCOR.vm | Template used for downloaded Submission PDF document. |
Available Properties
Placeholders may be used in email templates to refer to specific data that can only be supplied by nFORM at the time of the email’s generation. Such properties include the name of the recipient of the email, the submission or form triggering the email, etc. Properties of this type can be identified in the templates as they are preceded by a dollar sign ($).
The following is a list of available properties that can be referenced by the email templates. Note: properties are only available if in the context of a particular dataset. For example, Submission Properties are available in the context of a submission email (e.g., submission received), but are not available in the context of a user management email (e.g., change password).
Submission Properties
Property | Description |
|---|---|
$Model.SubNumber | GUID Submission number in nFORM |
$Model.SubVersion | Model object for the current revision of the submission. |
$Model.SubVersion.Id | The ID for the current revision of the submission. |
$Model.FormattedSubmissionNumber | Formatted version of the submission number |
$Model.SubmissionVerison.Submission.CreatedOn | Date the draft submission was created. |
$Model.SubDate | Original Submission Date |
$Model.SubName | Submission Name assigned by submitter. |
$Model.SubmissionVersion.CreatedBy.FullName | Full name of user who created the submission. Not necessarily the submitter. |
$Model.SubSubmitter | Submitter Full Name. Not necessarily the same user who created the submission. |
$Model.SubStatus | Submission Status |
$Model.SubLockStatus | Submission Locked Status |
$Model.SubRefNumber | Internal Reference Number for submission. |
$Model.SubReason | Submission Reason |
$Model.SubmissionVerison.Submission.FinancialStatus.Description | Submission financial status description. |
$Model.SubmissionVerison.Submission.ProcessingFee | Submission Fee |
$Model.SubAltId | Alternate ID value for submission |
$Model.SubmissionVerison.Name | Name of form if not overridden by the submitter renaming the submission |
$Model.SubResponsibleStaff | Step Responsible Staff person’s full name. |
$Model.SubmissionVerison.SubmissionVersionCor.Id | The ID of the submissions COR document, if one exists. |
$!Model.SubmissionVerison.SubmissionVersionCertFile.Id | The ID of the submissions Hard Copy Signature document, if one exists. |
$!Model.SubmissionVerison.Submission.RemainingPaymentRequired | Indicates whether fee is still due. |
User Properties
Property | Description |
$Model.AppPrincipal.FullName | User receiving message's full name in nFORM. |
$Model.AppPrincipal.Login | User's login name. May be different from primary e-mail. |
$Model.AppPrincipal.PrimaryEmail | User's Primary Email. May be different from user's login. |
$Model.PhoneNumber | User's phone number as stored in the user profile. |
$Model.AppPrincipal.LockedDate | Date that a user was set to locked. |
$Model.ConfirmationURL | A temporary URL that can be used to automatically confirm a user account. |
$Model.ConfirmCode | The temporary user account registration confirmation code. |
$Model.TemporaryPassword | A temporary password value for a user which is provided during the password reset process. |
$Model.AppPrincipal.LockedDate | The date the user account was locked. |
Submission Processing Step Properties
Property | Description |
$Model.Step.Name | Processing Step Name |
$Model.Step.Days | The number of days after the prior “level” is completed that the current step is targeted for completion. |
$Model.FormVersion.SendReminderDays | The number of days prior to a step target completion date that an email will be sent to a user reminding them of the approaching target completion date. |
$Model.SubmissionVerison.NextStepTargetDate | Days to complete current processing step. |
$Model.EmailCustomText | The custom email text assigned to a process step action for inclusion in an email. |
$Model.AttachmentURL | URL to the associated document template. |
$Model.AttachmentDisplayName | Name of the associated document template. |
$Model.AttachmentDisplayName | The Name of a document generated during a submission step. |
${Model.AttachmentURL} | The URL for a generated document during a submission step. |
Administrative Properties
Property | Description |
$Model.AdminEmailAddress | Configured administrative email address. |
$Model.ReturnURL | Base install URL |
Form and Organization Properties
Property | Description |
$Model.SubmisionVerison.FormVersion.FormItem.Organization.LatestPublishedVersionName | The Organization published version name. |
$Model.SubmissionVerison.FormVersion.Name | The name of the form. |
$Model.SubmissionVersion.FormVersion.Addresses | List of all addresses associated with the form version. |
$Model.SubmissionVersion.FormVersion.FormItem.Organization.LatestPublishedVersion.Contacts | List of all contacts associated with the organization version. |
$Model.SubmissionVerison.FormVersion.FormItem.LatestPublishedVersion | The model object for the latest version of the current form. |
Other Properties
Property | Description |
$Model.Now | The current date and time. |
Configuration Properties
All properties available in the vars.config (or overrides) can be exposed to the email templates. These can be exposed by referencing the existing configuration properties in the email.template.config.settings attribute in the following format:
<add key="email.template.config.settings" value="
app.name,
app.organization.state,
app.organization.official,
app.organization,
email.admin.address,
email.support.address,
message.email.appBaseUrl,
security.externalLoginControllerName,
jobs.deleteOldDrafts.deleteDays
"/>Any attributes referenced here can be accessed from within the email by referencing the configuration value without periods and capitalizing secondary words. For example:
The app.name configuration setting will be referenced as:
“$!Model.Config.AppName”The security.externalLoginControllerName configuration setting will be referenced as:
“$!Model.Config.SecurityExternalLoginControllerName”Subject Line Properties
The following properties are generally available for the subject line for an email. Note: Not all properties are available for To Emails (e.g., Submission Number is not available to submissions unrelated to a submission).
Property Reference | Property Name | Description |
Misc. Configuration Property | Misc. Configuration Property | Can be included as described in Configuration Properties section above. |
{0} | Submission Number | Submission Number can be included for submission emails. |
{1} | Full User Name | Full User Name can be included for user emails. |
Template Design
Designing an email template can be as simple or as complex as the designer wants the email template to be. By default, some of the email templates employ complex conditionality and formatting to present a clear and concise message to internal and external emails receiving the messages. The vm files can employ a combination of HMTL markup and Velocity Template Language to produce complex styling and conditionality.
HTML
When utilizing HTML in your email templates, you can user header files and styling just like you do when designing web pages. However, image/style management can be a challenge. It is best to do inline styling and use image references that are well established. Use of absolute paths to images that you can directly link to and styles that are embedded in the template itself are recommended.
For an example of some basic HTML used in an email template, see the default template for the SubmissionReviewUnLock.vm template. This template uses the following HTML markup.
<br /> - creates a line break
<h3></h3> - assign a header 3 style to text
<div> - creates a div box
Velocity Template Language
Most of the syntax you will see in the default templates is Velocity Template Language (VTL). For additional reference about the velocity engine, see here.
The following are a list of a few common VTL constructs that can be used in your templates.
Setting a Variable
The syntax for setting a variable is as follows:
Example: I want to set a default value of false for showing internal notations, to be potentially overwritten later:
Comments
The syntax for a single line comment is:
The syntax for a multi-line comment is:
Conditional Logic
Example: I want to display the contact email address associated with a form, if it exists.
Loops
Example: I want to display each address item that is associated with a form.