Email Templates for Notifications

Uncountable has a new method for sending email and in-platform notifications using triggers. Previously, notification templates were created through the “Add Template” button on the Templates page within Form Admin.

Now, notification templates can be created using the new “Add for Notification” button at the top of the Templates listing page. This updated method simplifies the process by allowing you to format both the header and body text without value spec and also supports the use of template variables.

Template Variables

When formatting the body of your email, users can now use template variables for parts of the message that are subject to change.

Template variables do not rely on standard value spec. Instead, they use the format ${ref:variable}, where “variable” represents a placeholder that links to value spec configured on the trigger initiating the notification. In this case, the entity reference is not required within the variable since it is stored in the value spec on the trigger.

Template Variables Example

To include a recipe name in the message body, use ${ref:recipeName} in the template. On the trigger, you would add a variable called “recipeName,” which corresponds to the value spec ref:recipe.name.

Note that variables, in this case “recipeName”, can be anything so long as it matches what is added on the trigger.

Configuring Notifications

Step 1: Creating the Notification Template

First, create a new notification template by taking the following steps:

1. Navigate to the Templates page in the Form Admin page.
2. Click the “+ Add for Notification” button.
3. Configure the Template by filling out the following:
   • Template Ref Name: Assign a reference name for the template (i.e. reminder_notice).
   • Header: Enter the subject line of the email or notification.
   • Body: Format the message body. Use template variables in the format ${ref:variable} for any dynamic content (i.e. ${ref:code} and ${ref:code2}).

Step 2: Creating a Trigger

Next, create the trigger that will send the notification using the following method:

1. Go to the relevant entity’s trigger set.
2. Add a new trigger and set the following:
   • Name: Assign a name for the trigger.
   • When: Specify when you want the trigger to fire (i.e. Explicit, Create, Complete Draft).
3. Add a new Trigger Action and select the type “TriggerActionEmail.”

Step 3: Configuring the Trigger

Configure the Trigger by filling out the following:

• Template: Select the template you created using its reference name (i.e. reminder_notice).
• Recipient Users: Use value spec to define recipients. This can be done by calling on a specific entity field or user ID. To send to a user list, you’ll need to use Recipient Specs. For more information, refer to the sections below.
• Skip Current User: Check this box if you don’t want the trigger creator to receive the email.
• Send Time: Use value spec to define when the notification should be sent in relation to the trigger’s “When” field. For example, sending it 3 days after the draft is marked as complete instead of immediately. For more information, refer to the example below.
• Subscriptions: Select a subscription list to notify all users subscribed to that list.
• Display Notice: Check this box if you want to send the notification as an in-platform notification in addition to email.

Recipient Users

Sending to an Individual User

Enter their user ID in the Recipient Users field using the format: json:____ . For example, to send a notification to a user with ID “4502”, enter: “json:4502”.

Sending to a Specific Entity Field

Enter the field reference name into the Recipient Users field using the format ref:field.____. For example, to notify a Product Steward for an approval, use: “ref:field.ProductSteward”.

Recipient Specs

Sending to a User List

To send to a user list, select the Recipient Specs button at the bottom of the modal. Use the format: user_list:____. For example, to notify all Formula Managers, use: “user_list:formulaManagers” where “formulaManagers” is that user group’s reference name.

Step 4: Adding Template Variables

If your template contained variables, add and define them on the trigger action.

1. On the Trigger Action, select the Template Variables button at the bottom of the modal.
2. Click “Add” to add and associate all template variables used in the email template with value spec.

In this example, since we used the variables “code” and “code2” in the notification template, they both must be added and defined using value spec.

Step 5: Adding Constraints

Last, add optional constraints by following these steps:

1. On the Trigger Action, enable:
   • Action Constraints: Constraints that must be met when the trigger’s “When” conditions are met. If Action Constraint conditions are not met, the trigger will not run at all.
   • Notification Constraints: If the trigger action has additional “Send Time” conditions, this constraint is checked when those conditions are met. If Notification Constraint conditions are not met, the trigger will not run. Consider the example below.
2. Click “Add” and add constraints.

Notification Constraints Example

Consider the example where you have scheduled a reminder email to send three days after an approval draft is completed. However, you only want that reminder to send if the approval is still in the “Review” phase. If that condition isn’t met, the notification won’t be sent.

Configuration:

1. Set the Trigger’s “When” field to “Complete Draft”.
2. Configure the TriggerActionEmail’s “Send Time” field to 3 days after the draft is completed using the value spec: (date_add_workday (datetime) 3)) .
3. Add a “Phase Match” Notification Constraint for the “Review” phase.

Step 6: Adding the Trigger to a Definition

In the example below, the trigger type is set to “Explicit” and is added to a Lab Request definition as an action. This is just one approach—there are multiple ways to configure triggers depending on your needs.

1. Add the email notification trigger set to a definition within the definition’s Triggers tab.
2. On the Trigger Set page, select the trigger sending the notification, access the Advanced tab and fill out the following:
   • Reference: Add a reference name for the trigger (i.e. emailReminder).
   • In Status: If the definition is a lab request or approval, select which stages (Draft, Open, and Terminal) should include the action.
3. On the definition, access the Actions tab and add a new action. Fill out the following:
   • Label: Set the text for the trigger action button (i.e. “Email Reminder”).
   • Trigger Reference: Add the trigger’s reference name (i.e. emailReminder).

Once configured, an action button will be visible on any lab request created using that definition. Clicking the button will trigger the action and send the email and notification, with variable values properly defined.