Configuring Email Alerts

When Default Email Alerts Occur

• When a draft is saved, the user saving the draft receives an email alert

• When a form is initially submitted (the first section is approved), the user submitting the form receives an email alert

• When the last section of the form is approved, the user who submitted the first section receives an email alert

• When a form is rejected, the user who submitted the first section receives an email alert

• When a form is ready for approval by an individual user, that user receives an email alert (unless that user assigned themselves that section)

• When a form is ready for approval by a specific group, all members of that group receive an email alert

• When a form is ready for approval by set of groups, all members of all groups receive an email alert

• When a form is returned to a user, that user receives an email alert

• When a form is returned to a group, all members of that group receive an email alert

• When a form is returned to a group of groups, all members of all groups receive an email alert

Default Email Alerts

Existing Default Templates

• approved: sent to the user of the first section when they initially submit a form

• draft_saved: sent when a draft is saved

• final_approved: sent to the submitter of the first section when the final section approves

• ready_user: sent to the user assigned to a section of the form once that section is ready

• ready_group: sent to the group assigned to a section of the form once that section is ready (only sent when there is not an assigned user)

• ready_group_access: sent to all groups with access to a section of the form once that section is read (only sent when there is not an assigned user or group)

• rejected: sent to the user of the first section any time the form is rejected

• return_to_section_user: sent to the user assigned to a section once the form is returned to that section

• return_to_section_group: sent to the group assigned to a section once the form is returned to that section (only sent when there is not an assigned user)

• return_to_section_group_access: sent to all groups with access to a section once the form is returned to that section (only sent when there is not an assigned user or group)

• connfail: sent to form template owners if a web service fails to connect

• servicesectionerror: sent to form template owners if a web service returns an error

Creating New Email Alerts

Defining New Notification Templates

Notification templates can be declared anywhere inside of the form-container.  A div with class of form-notification creates a notification template, with the id being the name of the notification template.  Each notification template must contain a tag with class form-notification-subject, and a div with class form-notification-body.  An example notification template is shown below.  Note that declaring a notification template only creates that notification template, it does not tie it to a form section or an action.  Tying form sections, notification templates, and actions together is done using notification hooks explained later.

Using Variables in Notification Templates 

Many variables are available in the notification templates.  These are indicated with double curly braces.  Example {{name_of_variable}}.  In addition to specific variables available, you can also access any submitted data from any form section visible to the section your custom notification template is associated with via a notification hook. Example: {{section_data.SECTIONNAME.FIELDNAME}}.

Available variables:

• {{form_name}}

• {{form_version}}

• {{section_name}}

• {{current_section_instance_url}}

• {{original_section_instance_url}}

• {{app_url}}

• {{my_forms_url}}

• {{active_form_queue_url}}

• {{section_user.netid}}

• {{section_user.firstname}}

• {{section_user.lastname}}

• {{section_user.displayname}}

• {{section_last_saved_by_user.netid}}

• {{section_last_saved_by_user.firstname}}

• {{section_last_saved_by_user.lastname}}

• {{section_last_saved_by_user.displayname}}

• {{original_submitter.netid}}

• {{original_submitter.firstname}}

• {{original_submitter.lastname}}
  
  

• {{original_submitter.displayname}}

• {{return_reason}}  (Only available when action is return or returnpast)

• {{reject_reason}}  (Only available when action is reject)

• {{section_data.SECTIONNAME.FIELDNAME}}  (Section referenced in section_data variable must be visible to section attached to notification template)

Actions

• save: occurs when the user saves without approving (saves as draft)

• approve:  occurs any time an interactive section is approved by a person and passes validation, or if a service section is approved via a web service call and passes validation

• ready: occurs on a section as a previous section is approved, and this section is the next non-skipped section in the order to be ready

• reject:  occurs on the section that is currently ready when the rejection occurs

• return: occurs on the section that a form is returned to

• returnpast: occurs on any sections already approved, that are unapproved as a form submission is returned to an earlier section

Recipients

• last_saved_by_user: last user to save the form section

• assignees: assigned user if there is one, otherwise members of the assigned group if there is one, otherwise all members of all available groups

• form_template_owners: members of the group that own the form template.

Sending Notifications (hooking templates to sections, actions, and recipients)

Creating notification hooks ties together form sections, actions, and notification templates.  The notification template in a notification hook can either be a custom notification template included in the form document, or one of the default system notification templates.  The notification will occur when the specified action triggers on the section containing the notification hook in its' class attribute.  When declaring a notification hook to replace a default notification be sure to suppress the default notification hook for that action on the section.  Notification hook syntax:

• notify-ACTION-NOTIFICATIONTARGET-NOTIFICATIONTARGETSECTION-default_template

• notify-ACTION-NOTIFICATIONTARGET-NOTIFICATIONTARGETSECTION-template-CUSTOMTEMPLATE

An example notification hook, which causes a notification to be sent to the last person to save the "Student" section, when the "Second_Reviewer" section is approved.  The custom template "Second_Approval_Notice" is used for this email.  Note that if this "Second_Reviewer" section is the last section in the workflow, then by default it will send an approval notice to the submitter of the first section.  If we want to suppress this default notice, then "supress-notify-approve" is needed.

Suppressing Default Email Alerts

1. You may suppress a default email alert adding a special class to the section you want to suppress

2. The format of that class should be “suppress-notify-ACTION” where ACTION is an action from the list above (under Actions)

3. Check the table above (under Default Email Alerts) to see which email alerts are sent for various actions

For example adding “suppress-notify-ready” to a section would prevent any assignees from getting an email notification that the section is ready.

Below is an example where the default approve notification on a form section is suppressed, and replaced with a custom notification hook using a custom notification template (Approval_Notice).  The last user to save the section with id "Student" receives this notification.

Sample Notification Template

Customizing "From" Address

By default an email alert with be from the user that initiated the previous action (based on LDAP full name and email address).  E.g., if you reject a form the email alert to the original submitter will be from you so that user can use the reply button.  The exceptions to this are when a draft is saved or the user causing the action is not visible in LDAP.

To customize the from address of a form section, add a "formcycle-from-email-address" attribute to that section's form element with the value set to the address you want the email to be from.  If you'd also like to set the name on the from address (which may help avoid being marked as spam), add a "formcycle-from-name" attribute to that section's form element with the value set to the name you want the email to be from.

Example: