Versions Compared

Old Version 4

changes.mady.by.user Ben Worley

Saved on

compared with

New Version Current

changes.mady.by.user Logan Korn

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Updated for Version 4.16

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.

Included in this article

Templates

External User Emails

Administrative Emails

Submission Processing Emails

Non-Email Documents

Available Properties

Submission Properties

User Properties

Submission Processing Step Properties

Administrative Properties

Form and Organization Properties

Other Properties

Configuration Properties

Subject Line Properties

Template Design

HTML

Velocity Template Language

Anchor
Templates
Templates
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.

Anchor
ExtUserEmails
ExtUserEmails
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.

Anchor
AdminEmails
AdminEmails
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.

Anchor
SubProcEmails
SubProcEmails
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.

Anchor
NonEmail
NonEmail
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.

Anchor
AvailProp
AvailProp
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).

Anchor
SubProp
SubProp
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.

Anchor
UserProp
UserProp
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.

Anchor
SubProcStepProp
SubProcStepProp
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.

Anchor
AdminProp
AdminProp
Administrative Properties

Property

Description

$Model.AdminEmailAddress

Configured administrative email address.

$Model.ReturnURL

Base install URL

Anchor
FormOrgProp
FormOrgProp
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.

Anchor
OtherProp
OtherProp
Other Properties

Property

Description

$Model.Now

The current date and time.

Anchor
ConfigProp
ConfigProp
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:

...

Code Block
“$!Model.Config.SecurityExternalLoginControllerName”

Anchor
SubLineProp
SubLineProp
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.

Anchor
TemplateDesign
TemplateDesign
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.

Anchor
HTML
HTML
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.

...

<div>  - creates a div box

Anchor
VelocityTempLanguage
VelocityTempLanguage
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:

...

Code Block
#set($showInternalNotations=false)

Comments

The syntax for a single line comment is:

...

Code Block
#**

[comment]

*#

Conditional Logic

Code Block
#if( [condition] )

[first conditional output]

#elseif ( [condition] )

               [second conditional output]

#else

               [else outpul]

#end

...

Code Block
#if ($contactItem.ContactType == "EMAIL")

Email : $contactItem.Value

#end

Loops

Code Block
#foreach( [ref] in [array] )

[action to perform in loop]

#end

...