Notifications

Avicenna’s Notifications functionality allows you to create and send customized notifications, whether automated or manually, to the researchers in your team or the participants. Before sending a notification, you need to specify the recipients, set the notification trigger, define when the notification should be sent, and a few other settings. All of these are combined into a notification template, which Avicenna uses to send one or more notifications. In this article, we will explore this functionality in depth.

Currently, Avicenna supports two types of notifications:

1. Participation Notifications: These notifications are related to the study's participation events. At the moment, they can be configured to be sent when a participant is invited to the study, or when they join the study.
2. Activity Notifications: These notifications are related to the activities of your study. They are triggered when an activity session is released, completed, canceled, or expired.

Notification Templates

A notification template, as the name suggests, outlines when to send notifications, their content, recipients, and other configurations. In most scenarios, you'll need a notification template to send any notification. The only exception is sending one-off notifications.

Creating Notification Templates

There are two ways to create a notification template. First, you can go to the Notifications page on your researcher dashboard and click on the Notification Templates tab. There, you can create, edit, and delete the notification templates in your study.

Alternatively, you can go to the Activities page, choose an activity, and then click on the Notification Templates tab. There, you can create, edit, link, and unlink only the notification templates related to the current activity. This makes it simpler for you to configure notifications when you are creating your activity.

note

Notification templates created on the Activity Editor can be used for activity-related events only. This means that you cannot use them for participation-related events. This may limit your options when choosing what should trigger the notification. On the other hand, you can use Notifications page to create a notification template for both types of events.

Using the Notifications Page

Navigate to the Notifications page on your dashboard and select the Notification Templates tab. Here you can create and manage all the notification templates of your study:

Clicking on the Create Template button shows you a dialog similar to the following. This dialog contains the parameters needed to create a notification template:

We explain each parameter in depth below.

Label:

You can assign a label to each template. The labels are only used to better identify the templates on the list.

Recipients:

You can specify who will receive the notifications. The recipients can be either Participant or Researchers. If you choose the Participant, the notification will be sent to the relevant participant. If you choose the Researchers, you will need to specify the researchers.

Notify On:

Here you need to set what will trigger the notification. The available options include:

• Study Invitation: This template will be used when you invite a new participant to the study. If you have not defined a Study Invitation notification template for your study when inviting participants, Avicenna creates one by default. Note that this notification can be only sent via email. That’s because, at the time of inviting a participant to your study, the email address is the only information Avicenna has from the invited participants.

  info

  While all email notifications require participants to verify their email addresses first, Study Invitation templates are an exception. Here we assume the participant's email address entered by the researcher is a valid address.

• Participant Joined: The template is used when a new participant enrolls in the study. This can be used to either send a welcome email to the participants, or to send a notification to the research staff and let them know that a new participant joined the study. Similar to Study Invitation, Participant Joined notifications can only be sent through email.

• Session Released: The template is used when a new activity session is prompted to a participant.

• Session Completed: The template is used when the prompted session is completed. For example, in case of survey activities, a survey session is completed when the participant responds to all of the questions and submits the answers.

• Session Expired: The template is used when the prompted session expires. If a participant does not complete the session within the allowed time window, the session will be considered an Expired Session.

• Session Canceled: The template is used when the prompted session is canceled. A session is marked as canceled when a participant explicitly indicates that they do not want to continue responding to a given session from a given activity.

Offset:

Offset allows you to set how long before or after the event the notification must be sent.

note

Only Session Released and Session Expired events can have negative offset values. This is because Avicenna can send notifications before an event only if it knows when the event will happen beforehand.

Criteria:

You can define criteria that, when met, will trigger the notification. Consider a mental health study where participants are required to fill out daily mood logs through the Avicenna application. You want to ensure that the participants are not experiencing severe emotional distress, and if they are, you want to provide additional resources or support promptly.

In this scenario, you can use criteria to monitor participants' responses and send notifications based on their input. This way you can customize your notifications and increase the compliance among your participants.

For more information on how to use criteria in Avicenna, check here.

Language:

This field is only available if you have more than one language added to your study in the Basics page. You can specify the language of the notification. This is useful when you want to send notifications in different languages. For example, you can send the notification in English to those participants who chose English as their main language, and send the same notification in French to French-speaking participants.

Medium Contents:

In this field, you can specify the mediums through which Avicenna should send the notifications. We currently support three mediums:

• Email: Recipients, whether participants or researchers, need to verify their email address before they can receive email notifications.
• SMS: Recipients need to verify their phone numbers to receive SMS notifications. Also, this will incur additional cost on your study, and may incur additional charges on the recipient as well. To enable this medium for your notifications, please contact Avicenna Support.
• In-App: Recipients should have the Avicenna app installed on their phone to get the In-App notifications. As the Avicenna app is only designed for participants, this notification medium is used for the study participants and cannot be used for the research staff.

For each of the selected mediums, you also need to write the content of the notification. For email, this will be a subject and a body of the mail. For in-app, this will be a title and a description. For SMS, this will be the content of the message.

In case you want to inform the recipients about the ID and the name of the study or the activity they are participating in, you can use placeholders by clicking on the Add Placeholder drop-down menu on the top right of your text editor. For example, if you want to add the name of the study to the email body or description of your in-app notification, you can click on Add Placeholder and choose Study Name. This will add the placeholder to the body field. When the notification is sent, the placeholder will be replaced with the actual name of the study.

info

Notify On options have different placeholders. For example, the Session URL and its placeholder are available for Session Released, but it will not work for Participant Joined. The reason is there is no session URL for a participant that has just joined and using it here is meaningless.

In this case, you will see an error message that this placeholder is not supported.

Error message for not supported placeholders

To make it easier, Avicenna will provide you with pre-created placeholders for the body or description of your notification according to what you choose for Notify On field. You can see how the placeholders may differ in the images below:

Placeholders for notify on participant joined	Placeholders for notify on session released

After taking care of the fields above, press Create and your Notification Template will be created and immediately becomes active.

Using the Activity Editor

In the Activity Editor, you can create notification templates that belong to activity-related events (Session Released, Session Completed, Session Expired, and Session Canceled). To do this, after navigating to the Activity Editor, on the Notification Template page, click on the Create Template button at the top-right corner to create a new notification template. The process of creating a notification template here is similar to the one we already explained for the Notifications page. You should keep in mind that creating a template in the Activity Editor will immediately link it to the current activity. This will be explained in more detail in the next section.

Creating Notification Template in the Activity Editor

Linking and Unlinking Templates to Activities

By default, activities in Avicenna have no notifications linked to them. So the participants do not know whether they have a new activity unless they happen to open the Avicenna app at the right time. This is of course not ideal, and in almost all cases, you want to notify your participants to complete the activity.

To do so, you must create a notification template and then link that to your activity in your study. This can help you manage your notifications among different activities and avoid having identical notification templates.

To give you an example, let's say that you have four surveys in your study. You want your participants to be notified whenever a new survey is released. In such a case, instead of making a Session Released notification template for each one of the surveys, you can simply create one notification template and link it to all the surveys in your study.

There are two ways to link a notification template to a given activity. First, if you create your notification template using the Activity Editor, the template will be linked to that activity by default.

Linking and unlinking a notification template

Alternatively, you can manually link an already-created notification template to an activity. In the Notification Templates page of the Activity Editor, you will see two tables: one for the templates already linked to the current activity, and another one for potential templates that can be linked. By clicking the link button on each row of the second table, as shown in the above image, that particular notification template gets linked to your activity. Doing so will move the template to the first table. Similarly, you can unlink a notification template from your activity by clicking on the unlink icon.

Editing and Deleting Notification Templates

You can edit or delete the notification templates in your study as needed. While editing a notification template can be done on both the Notifications page and the Activity Editor, you can only delete notification templates on the Notifications page. This is because each notification template may be linked to multiple activities, and deleting it from the Activity Editor for one activity can accidentally modify other activities in your study.

The following table can further clarify what operations are accessible at what part of the researcher dashboard:

	Notifications page	Activity Editor
Create a NT*	Possible	Possible
Edit a NT	Possible	Possible
Delete a NT	Possible	Not Possible
Link a NT	Not Possible	Possible

* NT stands for Notification Templates.

To delete or edit a notification template on the Notifications page:

• Go to the Notifications page and choose the Notification Templates tab.
• Click on the 3-dot button that you see on the right side of the table.
• Choose the Edit or Delete options to initiate the related operation.

Editing and deleting a notification template in the Notifications page

To edit a notification template in the Activity Editor:

• Go to the Activities page, choose an activity, open the Activity Editor, and then go to the Notification Templates page.
• Click on the Edit button from the Actions column.

caution

Keep in mind that you need to be careful when making changes to a notification template via the Activity Editor. Since a notification template might be linked to several activities within the same study, the modifications that you make to a linked template will affect the other activities as well. When you make changes to a linked template, the changes will be applied to all activities immediately.

Notifications Log

If you open the Notifications page on your researcher dashboard, and click on the Notifications tab, you can see the list of all notifications Avicenna has sent to your study participant, and the list of notifications that are scheduled to be sent in the future, based on your notification template configurations. As you can see in the image below, for each notification, you can see:

Notifications Log

• The notification ID
• The intended recipient
• The notification sender (this will be Avicenna System in almost all cases)
• The unique identifier of the related activity session (session UUID)
• The scheduled time of the notification which tells you when the notification was sent or will be sent
• The activity name that the notification belongs to
• The notification mediums that tells you through which medium a given notification is sent
• The notification status, which can be one of the following:
  • Pending: The notification is scheduled to be sent in the future.
  • Partially Failed: The notification was sent through some mediums, but it failed to be sent through one or more mediums. For example, the in-app medium was sent, but the email failed due to the participant’s email address not being verified.
  • Failed: This happens when a notification cannot be sent through any of the mediums. Also, if Avicenna fails to process a notification and send it due to technical reasons, the notification will be marked as Failed.
  • Success: The notification was sent successfully through all the mediums.
  • Stale: This means Avicenna could not send the notification on time due to technical reasons, and decided to skip it.

info

It's worth noting that when a session is blocked, expired, canceled, or completed, the associated upcoming Session Release notifications will be automatically deleted and will not be displayed. For further information on the session's status, please refer to the Triggering Logics.

As an example, let's say a researcher wants a participant to complete two sessions of one activity, one at 8 am and the other at 9 am. If the expiry time of the first session is set to 2 hours and the participant does not complete it before 9 am, the session scheduled for 9 am will be marked as "blocked" and the associated upcoming Session Release notifications will not be triggered for that session.

In another example, A researcher has set up a notification template for a study. This notification template is designed to remind participants about a session 20 hours after it begins.

Imagine a participant starts one of these sessions. If they finish it quickly, say within 10 hours, Avicenna understands that this participant has already completed the session, so they don't need a notification.

As a result, if a participant completes the session in less than the 20-hour reminder window, they won't get the reminder notification.

One-Off Notifications

Avicenna allows you to send custom, one-off notifications to participants and other researchers of your study via In-App, Email, and SMS mediums. We refer to this as manually triggering a notification. Note that these notifications do not use a template. To create a one-off notification:

• On your researcher dashboard, click on the Notifications page, and then the Notifications tab.
• Click on the Send Notification button.
• Specify the recipients, the mediums, and the content for each medium. (If you have more than one language added to your study, you should specify the language field too)
• Hit the Send button.

One-Off Notification

note

Keep in mind that since the Avicenna app is only used for participants, you cannot use the in-app medium to send notifications to other researchers of the study.

Data Filtering

To filter your data, you can set conditions, sort, and select the columns to be shown for Notifications as necessary. If you want to learn more about this feature and how it works, please refer to the Data Filtering page.

Notification Settings in Avicenna

Avicenna offers various notification settings to ensure both researchers and participants stay informed. Here's a breakdown of these settings:

For Participants

• Participants receive in-app notifications by default. Upon verifying their email addresses or phone numbers, they can add these additional notification methods. However, they retain the option to disable email and SMS notifications within the app.
• Avicenna ensures that the in-app notification setting remains always on, but participants can adjust their other preferences:
  • Launch the Avicenna app.
  • Navigate to Settings.
  • Access Notifications.
  • Under Mediums, participants can specify their notification preferences.

For Researchers

• Researchers have the flexibility to disable either the Email or SMS notification channels.
• As a researcher, you can choose which notifications you'd like to receive:
  • Click on your avatar located on the top right.
  • Select Notification Settings and change the settings.

How researchers can change notifications settings

Avicenna's Notifications ensures an easy communication process between researchers and participants. By utilizing customizable templates and various settings, researchers can keep participants informed and engaged throughout the course of a study. Whether it's automating notifications based on activity sessions or manually sending one-off notifications, Avicenna equips researchers with the tools needed for effective participant interaction. Both researchers and participants benefit from the diverse notification mediums, enhancing study compliance and fostering a more connected research environment. As you continue using Avicenna, make the most of these features to optimize communication and enhance your research outcomes.