How do I use the Notifications Area?

Modified on Fri, 16 Feb at 12:08 PM

In the code editor Notifications area, you can create custom assignment emails that can go out in place of a default assignment email if someone needs to receive more information about the submission they need to take action on. Custom assignment emails will always be sent at the entrance to a step. 


You can also set up notification emails that will be sent when a submission enters or leaves a particular step.


Steps can have only one custom assignment email but as many notification emails as needed. 

As of 7-5-2023


Notifications no longer use submission.data for recipients, hidden, or if. Instead, reference the component ID directly or use the helper function getSubmittedBy()


Custom Assignment Emails

Custom assignment emails can only be sent to the step assignee so you can't define the email address here. Instead, you will use "type":"assignment" and the email will be sent to the email address defined in the workflow step assignment.

Since you are overriding the normal assignment notification it is imperative that a link to the assignment is provided which you can include by using the variable ##submission.assignmentUrl## or ##link##. This link allows the recipient to open the assignment and complete their step of the workflow. The builder will provide a warning for you in the side panel if a link is missing from a custom assignment email.

 "thirdStep" : {
    "onEnter": [{
      "type": "assignment",
      "template": {
        "subject": "A form needs your signature",
        "body": "<p>Hello,</p><p>A new submission  has been filed. You can view and approve this submission by using the following link:</p><p>##submission.assignmentUrl##</p><p>Thank you</p>"
      },
    }]
  },


Notification Emails

In notification emails, the recipients field is used to indicate who should be notified instead of "type":"assignment".

Recipients will accept an array of email strings or a string that is evaluated as an expression. The code snippet below shows a notification that will send when the start step is exited to the email address from the component with the ID "assistantEmail" and a static email address.

 "start" : {
    "onExit": [{
      "recipients": "[assistantEmail, '[email protected]']",
      "template": {
        "subject": "A new submission has been started",
        "body": "<p>Hello,</p><p>A new submission has been initiated. You can view a copy by using the following link:</p><p>##link##</p><p>Thank you</p>"
      }
    }]
  },

If you would like to send a notification to the submitter, you can use the new sendToSubmitter property to indicate this. This accepts either true or false and can be used with the recipients property or in place of it. The code snippet below shows a notification that is only sent to the submitter.

"completed" : {
    "onEnter": [{
      "sendToSubmitter": true,
      "template": {
        "subject": "Your Form has been Processed",
        "body": "<p>Hello,</p><p>Your request has been completed. You can view a copy by using the following link:</p><p>##link##</p><p>Thank you</p>"
      }
    }]
  },

Notifications can optionally include a read-only link to a submission. Sometimes this isn't necessary, and an email alone is all the recipient would need but it is available to include using ##link## or ## submission.notificationUrl##.


Notification and Assignment Email Subject and Body Text

The actual message is defined in template which is broken down into a subject and body that are composed of strings of HTML. Since the body information is HTML within a JSON file, it is important to note that any styling can be accomplished by using the bracketed formatting inside the string associated with the "body" key. Links and other HTML items requiring double quotes will use single quotes instead. You can read more here if you would like a crash course in HTML. 

Items from the form can be called by using double hashtag formatted variables, such as:

  • ##submission.submittedBy.email##
  • ##submission.submittedBy.name##
  • ##submission.data.id##


List of Variables

NOTE: variables still use submission.data even though this has been removed from all other code notification code schema.


For Custom Assignment Emails
----------------------------
##recipientFirstName## - email recipient and also the submission assignee
##recipientLastName##
##recipientFullName##
##initiatedByFirstName## - individual that submitted the submission
##initiatedByLastName##
##initiatedByFullName##
##submissionId## - id of the submission, same as ##submission.id##
##formName## - name of the form
##formId## - id of the form
##submissionUrl## - url to the given submission (will include token for non-account users)
##allAssignedSubmissionsUrl## - url to the home page of the application (while include token for non-account users)
##link## - the url to the given submission within an anchor tag
##submission.id## - id of the submission, same as ##submissionId##
##submission.data.[path]## - data from the submission
##submission.assignedTo.name## - submission assignee name
##submission.assignedTo.email## - submission assignee email
##submission.submittedBy.name## - individual that submitted the submission name
##submission.submittedBy.email## - individual that submitted the submission email
##submission.assignmentUrl## - url to the given submission (will include token for non-account users)

For Custom Notification Emails
----------------------------
##assignedToFirstName## - submission assignee
##assignedToLastName##
##assignedToFullName##
##initiatedByFirstName## - individual that submitted the submission
##initiatedByLastName##
##initiatedByFullName##
##submissionId## - id of the submission, same as ##submission.id##
##formName## - name of the form
##formId## - id of the form
##submissionUrl## - url to the given submission (while include token for non-account users)
##link## - the url to the given submission within an anchor tag
##submission.id## - id of the submission, same as ##submissionId##
##submission.data.[fieldId]## - data from the submission
##submission.assignedTo.name## - submission assignee name
##submission.assignedTo.email## - submission assignee email
##submission.submittedBy.name## - individual that submitted the submission name
##submission.submittedBy.email## - individual that submitted the submission email
##submission.notificationUrl## - url to the given submission (will include token for non-account users)


Optional Definitions for Notification Emails

The following sections define optional fields you can include when you create a notification email. These are not available for custom assignment emails.


Conditionally Sent Notifications

Sometimes you only need a notification sent out under certain conditions. You can define these conditions in the optional if section of notifications. Here, you can write a formula or reference a component ID. If the expression in if is true, the email will be sent and when false it will be skipped. The code snippet below modifies the email notification that would get sent on the second step to only send if the boolean component with the ID of "needsSupport" on the submission is true.

"secondStep" : {
    "onEnter": [{
      "recipients": [
          "[email protected]",
          "[email protected]"
        ],
      "template": {
        "subject": "A user needs technical support",
        "body": "<p>Hello,</p><p>A new support ticket has been filed. You can view a copy by using the following link:</p><p>##link##</p><p>Thank you</p>"
      },
      "if": "needSupport"
    }]
  },


Hiding Notification Fields

Sometimes, certain fields should not display to the recipient of a notification. In this case, you can hide those fields using the optional hidden section of notifications. In hidden, you can define an array of component IDs that should not be displayed in the link with this email. The code snippet below modifies the notification sent when the start step is exited so the link included in this notification will not include the "ssn" or "lastName" components.

  "start" : {
    "onExit": [{
      "formula": "['[email protected]',assistantEmail]",
      "template": {
        "subject": "A new submission has been started",
        "body": "<p>Hello,</p><p>A new submission has been initiated. You can view a copy by using the following link:</p><p>##link##</p><p>Thank you</p>"
      },
      "hidden": ["ssn","lastName"]
    }]
  },



Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article