Configure Notifications on a Form
| Table of Contents |
Overview
Notifications are parts of a form that can send emails to specified recipients. A notification can be set up using the custom type “Email: Notifications”. They can either be very simple, needing only a small amount of JavaScript or more complex with the use of additional data fields.
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 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. |
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.
Custom 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.
| 1 | Add an id to the send notification section. This id should be unique/different for each notification on the form. This document will use “notificationSection” as the id.
 |
| 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.
Copy to Clipboard 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”.  |
Creating the Notification Call
This part of creating a form notification is more complex and requires the modification of one of a selection of notification types.
There are 3 main types of notifications, however, the 3rd type can be completed and/or applied in multiple ways. The three types include: user-based notifications, role-based notifications, and person-override notifications.
For all the notification types, an attribute of onclick is required with the value being the code for the notification. Templates of the code required can be found in the “User-Based Notifications”, “Role-Based Notifications”, and “Person-Override Notifications” sections later on in this document. There will be a simplified template, that can be used when the notification custom type is only going to be sending one notification, as well as a complex template that should be used if the notification custom type will be sending multiple notifications.
There are a few elements to this code that are outlined in the following table:
| Code Element | Description |
|---|---|
| School Name |
For all notifications, update the id in the location selector from “school” to the id used on the location drop-down on the form. Below is an image of a user-based notification’s code with the location selector outlined in white:  |
| Notification Name |
For simple notifications, using the simplified notification template, update “NOTIFICATION NAME” (keep the quotes) to be the name you would like for the notification. This name will have to match the notification name in form management in order for the notification to be sent properly. Below is an image of a simple user-based notification’s code with the notification name outlined in white:  For complex notifications, using the complex notification template, this element can be found within the notification sender call. The exact function used will be different based on the type of notification, however, the second parameter will always be the notification name. This should be updated to the desired notification name. Below is an example of a complex user-based notification’s code with the notification name outline in white:  It is important to note that every notification should have a unique name across all forms. No two forms should have notifications with the same name. |
| Warning Message |
This element of the notification will be the alert given to the user if they try to send a notification without haven’t selected a location yet. For simple notifications, using the simplified notification template, update “WARNING MESSAGE” with the desired warning message. Below is an image of a simple user-based notification’s code with the warning message outlined in white:  For complex notifications, using the complex notification template, this element can be found within the “player.callDialogMessage()” function. It will be the third parameter. Below is an example of a complex user-based notification’s code with the warning message outlined in white:  An example warning message could be: “There was no school selected. Please ensure a school has been set before sending this notification”. Make sure the message is surrounded by quotation marks. |
| Button ID |
*Only for role-based notifications. The button id element will have the same value as an id given to the “Send Notification” button. Below is an image of a simple role-based notification’s code with the button id outlined in white:  Below is an example of a complex role-based notification’s code with the button id outlined in white:  |
|
Person Override |
*Only for person-override notifications. The person override parameter is an optional element to the the role-based and user-based notifications. This parameter will override the default recipient of the notification, and instead send it to the email address assisciated with the user id used as the person override. Below is an image of a simple user-based, person-override notification’s code with the person override parameter outlined in white:  Below is an image of a complex user-based, person-override notification’s code with the person override parameter outlined in white:  The user ID should be aquired dynamically from other elements on the form, and not hard-coded into the notification code. |
|
Notification Sender |
This line of code is what will send the notification so long as the location drop-down has a value. For user-based notifications the notification sender is the following: Copy to Clipboard For role-based notifications the notification sender is the following: Copy to Clipboard For person-override notifications the notification sender is the following: Copy to Clipboard |
|
Date Setter |
The date setter will set the date field of the notification custom type to the date that the notification was sent. This is set up but updating the numbers in the $.setTodayDate() function to the elementId of the date field. This elementId can be found in the options accordion after selecting the date field.
 |
| User Recorder | This is an optional notification element used to store the name of the user who sent the notification. This is useful for adding a “Submitted By” field to the notification element, so as to create a record of who has sent what notification. User recorders are often used in return-to-sender notifications. The process of adding a user recorder is covered under “User Recorders”. |
|
User ID Recorder |
*Only for return-to-sender notifications This is an optional notification element used to store the user id of the person who sent a notification. It works in tandem with data fields and is generally only used when a following notification is to be sent to the user who sent the primary notification. More details can be found under “Person-Override Notifications”. |
User-Based Notification Templates
User-based notifications are used to send a notification to a specific person or persons based on a provided email address. This type of notification is often used for the purpose of sending emails to people who do not have accounts within the clevr system, or when the notification should go to a specific person when there are many users with the same role as said person. User-based notifications are also used when setting up a direct supervisor notification, even though “direct supervisor” will be selected as a role in form management.
Simplified User-Based Notification Template
Complex User-Based Notification Template
Creating a User-Based Notification
| 1 | Follow the steps under “Adding The Notification To The Form”. |
| 2 |
Locate the “School” or “Location” drop-down on the form and add and id of “school”. Considerations: If this id is already on the element, do not add it again. If this id is used somewhere else on the form, change it so that it is unique. Be sure to update all further references to the id “school” with whatever it has been changed to here. If the “School” or “Location” drop-down is on a dynamic tab, then follow the steps under “Tracked School Field”.  |
| 3 |
Copy either the complex or simplified notification template into a code/text editor. |
| 4 |
Update “NOTIFICATION NAME” to the desired notification name (Maintian Quotations). ex: “ELL – Notifiy Principal” |
| 5 |
Update “WARNING MESSAGE” to the desired warning message (Maintian Quotations). ex: “There was no school selected. Please ensure a school has been set before sending this notification” |
| 6 | Update the date setter to use the correct elementId. This can be found in the options table of the date field.
 |
| 7 | On the “Send Notification” button, add the attribute onclick with the value set to the updated code.
 Reminder: Press the “enter” key to save values in the values column of the Options Table. |
Role-Based Notification Templates
A Role-Based notification is used to send a notification to all users who have the specified role at a specified location. The location is generally selected via a “School” or “Location” drop-down on the form.
Simplified Role-Based Notification Template
Complex Role-Based Notification Template
Creating a Role-Based Notification
| 1 | Follow the steps under “Adding The Notification To The Form”. |
| 2 |
Select the “Send Notification” button and give it the attribute id with a unique value. ex: principalNotificationButton  |
| 3 |
Copy either the complex or simplified notification template into a code/text editor. |
| 4 | Locate the “School” or “Location” drop-down on the form and copy the elementId.
 Update “LOCATION ELEMENT ID” to this value. ex: “638138778670654142” |
| 5 |
Update “NOTIFICATION NAME” to the desired notification name (Maintian Quotations). ex: “ELL – Notifiy Principal” |
| 6 |
Update “WARNING MESSAGE” to the desired warning message (Maintian Quotations). ex: “There was no school selected. Please ensure a school has been set before sending this notification” |
| 7 | Update the date setter to use the correct elementId. This can be found in the options table of the date field.
 |
| 8 | On the “Send Notification” button, add the attribute onclick with the value set to the updated code.
 Reminder: Press the “enter” key to save values in the values column of the Options Table. |
Person-Override Notification Templates
Person-override notifications are any notifications that utilize the person-override parameter. This includes notifications that are to be sent to the subject of the record, return-to-sender notifications, and notifications to be sent to a person who has applied their digital signature, among others. This type of notification requires a default notification that can be either role-based or user-based. These default notifications are important to set up so that if the person override fails, or if certain conditions are not met, then the default notification will be sent instead.
The user id used in these notifications should be acquired dynamically. How to do this can be found below the templates in the “Getting The User ID” section.
Below are the templates for person-override notifications. Generally, person-override notifications will have a user-based notification as the default with the user being “support@clevr.ca”. This will send clevr a notification in the event that the person override fails, allowing for prompt investigation.
If the default notification is to be role-based, these templates should still be used, but a default role or roles should be selected when setting up the notification in form management.
Simplified Person-Override Notification Template
Complex Person-Override Notification Template
Getting The User ID
There are 3 main ways to dynamically acquire a user id; getting the user id of the subject of the record, getting the user id from a digital signature, and getting the user id from a previously sent notification (if it was set up with a return-to-sender notification in mind) are all valid methods of dynamically acquiring a user’s id for a person-override notification.
The Subject of The Record’s ID
This is the simplest form of a person-override notification. The only work to be done is within the notification code itself.
| 1 | When updating the notification template, replace “USER ID” with “{personId}” (no quotes). |
Digital Signature ID
In order to get an id from a digital signature, some work must be done to the signature id field as well as the notification code.
| 1 |
In the digital signature custom type, select the id field.  |
| 2 | Give this field a unique id. This example will use “principalSignature”.
 |
| 3 | When updating the notification template, replace “USER ID” with “$(“#principalSignature”).val()” (no surrounding quotes). Update “principalSignature” with the id you set on the signature id field. |
Return-To-Sender ID
A return-to-sender notification requires some data fields to be set up in order to store the user id of the person who sent the original notification. It is standard to add a “Submitted By” field to the original notification, and both the original notification and the return-to-sender notification will require some updates to the code as well.
| 1 |
On the original notification, add the custom type “Common: Label Textbox” into the send notification section. Update the label with a content attribute and resize all aspects as desired. ex:  |
| 2 |
Select the “Submitted By” textbox field and give it an id with a unique value. This example will use the id “submittedByName”. This id will be referred to as the “submitter name id”.  |
| 3 |
Next, a data field needs to be added outside of the tabset in order to properly query the current user’s name. Start by adding a container outside of the tabset and selecting it. |
| 4 |
Give this container the attribute style with a value of “visibility:hidden;background:aliceBlue;border:1px solid steelBlue;”  |
| 5 |
Add the custom type “Common: Label Textbox” into this container. This will be the queried user’s name data field. Update the label with a content attribute, and resize all elements as desired. ex:  |
| 6 |
Select the “Queried Name” textbox, and give it an id. This example will use “currUser”. This id will be referred to as the “queried name id”.  |
| 7 |
With the “Queried Name” field still selected, add the attribute data-source and from the resulting drop-down select “Textbox: User’s Name”.  |
| 8 |
The last bit of form work before updating the notification code is to add a data field to store the user id of the person who submitted the original notification. Within the original notification container, add a textbox.  |
| 9 |
Select this new textbox and give it an id. This example will use “submittedById”. This id will be referred to as the “submitter user id”.  |
| 10 |
Next, with the textbox still selected add the attribute style with a value of “visibility:hidden;background:aliceBlue;”  |
| 11 |
With the form work out of the way, the original notification will require some work in order to properly set the “Submitted By” field and collect the submitter’s user id. With any of the notification templates, add the following lines after the date setter line. Copy to Clipboard Replace “submittedByName” with the previously set submitter name id. Replace “currUser” with the previously set queried name id. Replace “submittedById” with the previously set submitter user id. An example full original notification: Copy to Clipboard |
| 12 |
The only item left is to update the return-to-sender notification in order to utilize the submitter user id. When updating the notification template, replace “USER ID” with “$(“#submittedById”).val()” (no surrounding quotes). Replace “submittedById” with the previously set submitter user id. |
Creating a Person-Override Notification
| 1 | Follow the steps under “Adding The Notification To The Form”. |
| 2 |
Locate the “School” or “Location” drop-down on the form and add and id of “school”. Considerations: If this id is already on the element, do not add it again. If this id is used somewhere else on the form, change it so that it is unique. Be sure to update all further references to the id “school” with whatever it has been changed to here. If the “School” or “Location” drop-down is on a dynamic tab, then follow the steps under “Tracked School Field”.  |
| 3 |
Copy either the complex or simplified notification template into a code/text editor. |
| 4 |
Update “NOTIFICATION NAME” to the desired notification name (Maintian Quotations). ex: “ELL – Notifiy Principal” |
| 5 |
Update “WARNING MESSAGE” to the desired warning message (Maintian Quotations). ex: “There was no school selected. Please ensure a school has been set before sending this notification” |
| 6 | Update “USER ID” to dynamically aquire a user id. |
| 7 | Update the date setter to use the correct elementId. This can be found in the options table of the date field.
 |
| 8 | On the “Send Notification” button, add the attribute onclick with the value set to the updated code.
 Reminder: Press the “enter” key to save values in the values column of the Options Table. |
Drop-Down Based Notification
On occasion, a drop-down may be required to control what notification is sent, or to who a notification is sent. This is a simple setup that will require small changes to the form and notification code. A drop-down notification works by dynamically changing the notification name based on the value of the drop-down.
| 1 | Navigate to the drop-down that will control the notification, or add one to the form. |
| 2 | Select the drop-down and give it an id if it doesn’t already have one. This example will use the id “principalSelection” |
| 3 | Navigate to the notification and select the “Send Notification” button. Copy the value from the onclick attribute. If the notification has not been set up yet create one using the given example or one of the previous notification templates. This example will use the simplified person-override notification template as a base. |
| 4 | With the notification code copied, paste it into a text or code editor. |
| 5 | Update the “school” in “$(“#school”).val()” to be the id that is found on the school/location field on the form. If that field does not have an id, give it the id “school”. |
| 6 |
Update “NOTIFICATION NAME” to include a prefix that will be applied to all notification names, and an addition of a selector that references the drop-down. In the following example, simply update “Principal Notification: “ to the desired prefix, and “principalSelection” with the id given to the drop-down. ex: “Principal Notification: “ + $(“#principalSelection”).val() |
| 7 | Update “LOCATION WARNING MESSAGE” to the error message that will be displayed when a user attempts to send the notification without selecting a school. |
| 8 | Update “USER ID WARNING MESSAGE“ or “DROPDOWN WARNING MESSAGE” (depending on the template) to the error message that will be displayed when a user attempts to send the notification without selecting a recipient from the drop-down. |
| 9 | Update the date setter to use the element id of the date picker attached to this notification. |
| 10 |
If using the person-override notification template, all references to “userID” must be removed. i. Remove the line “const userID = “USER ID”;” |
| 11 | Use the updated code as the value on the onclick of the notification button. |
| 12 | An example full notification may look like this: Copy to Clipboard |
Autocomplete Notifications
One of the more complex person-override notifications is the autocomplete notification. This notification type allows users to input the recipient’s name and select them from a queried list. The personId of the chosen person will be used in the person-override parameter to define the recipient of said notification. The process of creating this notification begins by creating the autocomplete field.
Autocomplete Notification – Part 1
| 1 | Add the custom type: “Common: Label | Textbox” to the form. |
| 2 | On the label, add the content attribute with a desired value. |
| 3 | On the textbox, add the attribute description with a desired value. |
| 4 | The query must be completed by clevr at this time. |
| 5 | On the textbox, add the class “isAutocompleteFromServer” and “unhook”. |
| 6 |
On the textbox, add a unique id. ex: studentAuto |
| 7 | On the textbox, add the attribute setOtherFields with a value of true. |
Autocomplete Notification – Part 2
| 1 | Add the base type: “Textbox” to the form. |
| 2 | On the textbox, add the attribute id with a unique value. This example will use “autocompleteID”. |
| 3 | On the textbox, add the attribute “acQueryFieldName” with a value of “autoCPID”. |
| 4 | On the textbox, add the attribute “acQuerySource”. The value for this will be the ElementID of the textbox used in part 1. |
| 6 | On the textbox, add the attribute style with a value of “visibility:hidden;background:aliceBlue;border:1px solid steelBlue;” |
Autocomplete Notification – Part 3
| 1 | In the notification code, change “USER ID” to $(“#autocompleteID”).val(); (if a different id was used in part 2, use that in place of “autocompleteID” in the selector). |
| 2 |
The final notification code may look similar to this: Copy to Clipboard |
Tracked School Field
Issues may arise in user-based notifications if the school or location field that is referenced in the notification is on a dynamically loaded tab. If this is the case, then tracked fields will have to be used in order to reference the school or location field.
| 1 | Select the Type 0 container and add the attribute trackFormFields with a value of “true”.
 |
| 2 | Navigate to the school or location 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 template to replace “$(“#school”).val();” with “player.tracked[‘637713750695814176 1’].value;” where “637713750695814176” needs to be changed to the elementId of the school or location drop-down. ex: Copy to Clipboard |