Configuring a Notification on a Form

Configuring a Notification on a Form

Notifications are a custom type that can be added to a form, that are used to send notifications and emails to specified recipients or roles. A notification can be configured using the custom type “Email: Notifications”.

Terms

#
Term
Description
1
Content Attribute
This will refer to one of the following attributes based on the desired language. English: content_en-CA, French: content_fr-CA, Spanish: content_es-US.
2
Custom Types
The Custom Types menu can be found in the options accordion. It contains more advanced groupings of elements that are used most frequently on forms, some of which include pre-applied functionality.
3
Data Field
Data fields are hidden from view, store information, and may be referred to by form functions. They will be created outside of the main tabset so that they are always initialized
4
Dynamic Tab(s)
Dynamic tabs are tabs that are not initialized when the tabset is initialized, but when they are opened. All tabs but the first tab of a tabset are dynamic tabs.
5

Field
A Field is a type of element that users are able to input data into. Examples include textboxes, drop-downs, and checkboxes.
6
Id
This is a common form attribute. When an id is used in the example, an alternative id may be used, however, make sure that when replacing the example’s id with a custom one, the change is consistent throughout.

When quotation marks are used to describe the value of an attribute, selector, etc. assume the quotes are not part of that value itself. When replacing ids or classes, maintain the quotation structure of the original/provided code.

Adding The Notification To The Form

First of all, navigate to the location on the form the notification should be placed. Then, click somewhere in the editor in order to bring up the options accordion and navigate to the Custom Types menu. Find the custom type “Email: Notifications”, click and hold on it before dragging it to the desired location on the form.

Cutsom Types Menu:


Default Appearance of “Email: Notifications”:


Adding Standard Functionality

A notification has a few standard pieces of functionality. The first piece is to add the attribute DoNotClone with a value of “true” onto the outside container of the notification.


The second piece of standard functionality is to add a clevrShowHide() function to the checkbox that will control if the send notification section within the custom type is shown or hidden.

#
Step
1

Add an id to the send notification section. This document will use “notificationSection” as the id.


Note: This id should be unique/different for each notification on the form.


2
On the checkbox of this custome type, add the attribute onchange with a value as the following code. Remember to update “notificationSection” with the id used in the previous step.

$(this).is(":checked") ?
$.clevrShowHide("notificationSection:show"):
$.clevrShowHide("notificationSection:hide");


This code works by checking if the checkbox is checked; If the checkbox is checked, then the second line will trigger - showing the section with an id of “notificationSection”, otherwise the third line will trigger - hiding the section with an id of “notificationSection”.

3
Next, the attributes class and order are required to complete the clevrShowHide(). A class of “sliderControl” should be added, and an order with a value being the id used in step one. In this example the id and value is “notificationSection”.

The Notification Call

Creating notifications requires an understanding of the pieces of the notification call. Each parameter, its function, and possible use cases are outlined in the table below. The general form of the notification call is sendMessage(notification, location, {options} ).

An example of a notification call with all provided options is as follows:
sendMessage(['Clevr Notification 1', 'Clevr Notification 2' + $("#drop-downID").val()], $("#school").val(), {
  overrideId: [$("#signatureID").val(), $("#otherId").val()],
  includeRecipients: true,
  scheduledDate: $(".datePickerClass").val(),
  scheduledCorrelationId: "remindPrincipalNotification"
})

#
Parameter
Description
1
notification
This parameter houses the notification name. The value provided to this parameter must match a notification name in form management. Either a single name, or an array of names can be given. When the notification is triggered, all provided notification names will be sent.

For drop-down notifications, a selector referencing an id given to the drop-down should be utilised in the notification name.

EX:
"Submit to Principal"
["Submit to Teacher","Submit to Principal"]
"Submit Form to" +  " " + $("#id").val()
2
location
The location parameter must be either a selector that references the location drop-down on the form, unprovided, or "null". The parameter should only be "null" if the notification is purely user-based and additional options are provided. Unless the notification contains role-based recipients, if there are not additional options provided this parameter does not need to be provided either. If there are role-based recipients then a location must be provided.

The best way to provide a location value is to give the location drop-down on the form an id. Then in the notification call, place $("#id") in the location parameter. Make sure the id on the location drop-down is the exact same as the id given in the selector.
3

options
There are multiple addition options that can be applied to the notification. These options must be provided in the form of a JavaScript object. The possible options are: overrideId, includeRecipients, scheduledDate, and scheduledCorrelationId.

EX:
{overrideId:$("#signatureID").val()}
{overrideId:$("#signatureID").val(),includeRecipients:true}
4
overrideId
This option will override the default recipient of the notification, and instead send it to the account/email address assisciated with the user id used as the person override. Multiple overrideIds can be used if provided in the form of an array. To send the notification to both the override recipients and the regular recipients, the includeRecipients option will be required.

Some use cases for this option would be autocomplete notifications, return to sender notifications, sending notifications to users who have signed a form, and notifications to the subject of the form.

EX:
overrideId:$("#signatureID").val()
overrideId:[$("#signatureID").val(),$("#otherId")]
5
includeRecipients
If the regular recipients of a notification need to recieve the notification along with provided override recipients, this option must be provided with a value of true. If this behaviour is not desired, the option does not need to be provided.

EX:
includeRecipients:true
6
scheduledDate
The scheduledDate option allows for notifications to be sent on a specific date. A date value must be provided if this option is being used. The date value can be aquired by referencing a datepicker on the form using a selector, or by calculating it programtically. If the scheduledDate option is provided, the scheduledCorrelationId option must also be provided.

This option could be used to send notifications from multiple records on the same date, to send time-based reminder notifications, or to delay a notification being sent for any reason.

The value provided should be in a Javascript date object, or text in the form of YYYY-MM-DD.

EX:
scheduledDate:$(".datePickerClass").val()
7
scheduledCorrelationId
If the scheduledDate option is used, then this option must also be provided. The scheduledCorrelationId option provides a name for a specific notification call for a specified date. This ensures that if the date is changed and the notification is sent again, the scheduled date for the notification is updated thereby changing the date it will send instead of sending a notification on both dates. This option must be provided in the format of a string.

EX:
scheduledCorrelationId:"remindPrincipalNotification"

Tracked Fields

If a field being referenced in the notification call is not on the same tab as the notification, or on the the first tab of a form, a tracked field will be required.

#
Step
1
Select the Type 0 container and add the attribute trackFormFields with a value of “true”.

2
Navigate to the referenced field, select it, and add the attribute trackField with a value equal to the form id.


3
Next, the notification code must be updated.  Update the code to replace selector with “player.tracked['XXXXXXXX|1'].value;” where “XXXXXXXX” needs to be changed to the elementId of the referenced field.

EX:
$("#school").val() might become player.tracked['638138778670654142|1'].value; where 638138778670654142 is the element id of the school field.




    • Related Articles

    • Configure Notifications in Form Management

      Overview A notification is a configurable workflow item that is sent to one or more specified users and/or roles when it is triggered. The notifications card and the notifications editor in form management is used to configure notifications. Common ...
    • Best Practices for Secure Messaging: Email vs. In-App Notifications

      In an ever-evolving landscape of privacy and security, ensuring the proper handling of sensitive information should be a top priority for anyone configuring notifications and communications on the platform. Each region and country has its own laws ...
    • Threshold Notifications

      Introduction to Threshold Notifications Threshold Notifications are a powerful feature within Clevr that allow you to set specific triggers based on the data input in your forms. When thresholds are met, custom notifications are sent to the ...
    • Using Notification Variables

      The "Notifications" feature allows users to send in-app messages and emails directly from a form. When composing the subject and body of these messages, you can insert dynamic variables, which are automatically replaced with relevant data when the ...
    • Notification - Administrative Board

      The Notification Administrative Board is a module within Clevr that you can use to review all notification activity within your organization. The Notification Administrative Board has a brand-new look and feel, and was overhauled in April of 2024. ...