How do I use the Notifications Area?

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. 

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##

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"]
    }]
  },