Triggering Logic, or TL for short, for an activity specifies when the activity should be prompted to the participant. Ethica supports 5 types of triggering logics:
- Eligibility TL specifies that the activity is intended to be presented to prospective participants.
- User TL specifies the participant decides when and how often to start the activity and respond to it.
- Time TL specifies the activity should be prompted based on a certain time schedule.
- Proximity TL specifies data from Bluetooth Beacons to determine when the activity should be prompted.
- Dropout TL specifies the activity should be prompted when the participant decides to drop out of the study.
Not all activities support all of the above triggering logics. For example, while survey activities can have any of the above TLs, cognitive tasks or time-use diaries cannot be prompted via an Eligibility or Dropout TL.
A given activity can have one or more TLs of any type, with a few exceptions. For example, you can have an activity with the following combinations:
- One User TL and one Time TL. This activity will be prompted at certain times, and also participants can start the activity anytime they want.
- One User TL and multiple Time TL. This activity will be prompted on the union of all the times specified by all the Time TLs, and also participants can start the activity anytime they want.
- One Proximity TL and one Time TL. This activity will be prompted when a specific Beacon contact is detected, and also at certain times specified by the Time TL.
- One Eligibility TL. This is only possible for survey activities. This survey activity will be prompted when a prospective participant tries to join the study. Eligibility screening surveys are described in more detail here.
Each Triggering Logic operates fully independently from all other Triggering Logics in the same activity. For each activity, Ethica processes each of its Triggering Logics and prompts the activity to the participant as requested by each Triggering Logic. Not all combinations of the Triggering Logic types are allowed:
- If you add an Eligibility TL to your survey activity, you cannot add any other Triggering Logic to it.
- Survey activities with a Dropout TL cannot have any other Triggering Logic.
- Your study can have only 1 survey activity with Eligibility TL.
- Your study can have only 1 survey activity with Dropout TL.
In the Criteria section, we described how
each activity can have a criteria which specifies whether the activity is
enabled or disabled. Further, Ethica allows you to specify a Criteria for each
Triggering Logic. You can think of the Activity Criteria as the main switch
which enables or disables the survey for a given participant, while the TL
Criteria is the switch that enables or disables that particular Triggering
Logic. For an activity to be prompted via a given TL, both the Activity Criteria
and the TL Criteria should be evaluated to
For example, assume you have an activity with an activity criteria which is
referred to as
AC. This activity has two Triggering Logics as follow:
- User TL with a TL criteria referred to as
- Time TL with a TL criteria referred to as
Further, assume you enroll three participants in your study. For the first one,
AC is evaluated to
False. Therefore, this activity will not be prompted to
this participant, regardless of the evaluation result of
Time_TLC. This participant will not be able to respond to this activity.
For the second participant,
AC is evaluated to
User_TLC is also
Time_TLC is evaluated to
False. In this case, the
participant will be able to open the Ethica app and complete the activity
anytime they want (as defined in the behavior of the Time TL), but
the Ethica app will not prompt the activity to them at the times specified by
the Time TL.
For the third participant, all three criteria, i.e.
User_TLC, are evaluated to
True. Therefore, the participant can complete the
activity anytime they want, and also the Ethica app will prompt the activity to
the participant at the specified times.
While you can use Triggering Logics to specify when Ethica should allow the participant to complete an activity, there might be times that you want to prompt the activity right away to one or more participants. Ethica allows you to manually trigger an activity when necessary. In this case, Ethica will send a message to the participant's app using Cloud Messaging, asking the app to prompt the activity to the participant right away. In order to do this:
- Go to the Researcher Dashboard.
- Select your study, and then from the left panel select
- Here you can see all activities defined for your study. You can click on any activity to see the related actions.
- Click on the
Releasebutton on the right side to open the Release Activity dialog.
- Pick the participants you want to send the activity to, and press
Note that you can only prompt an activity to participants who are currently active in your study. The list will show all the participants, but the participants who have finished their participation will be disabled and have a finished status and cannot be selected.
The above steps show a notification on the participant's phone to let them know they have an activity to complete. If they are not currently online, the message will be delivered as soon as they are online. Additionally, if the participant opens the Ethica app, the app always first checks if there are any prompted activities en-route, and if yes, prompts them immediately.
When an activity is prompted to the participant, regardless of which of the above Triggering Logics prompted it, the Ethica app will create a Session for it. This session will hold the information about the prompted activity, responses provided by the participant so far, and other related metadata.
Each session contains a status, which can be one of the following:
- Unknown (ID 0) indicates the session is not prompted to the participant yet, but it's waiting for its scheduled time to arrive. When the scheduled time arrives, depending on the criteria of the session (if any), this session can be prompted.
- Completed (ID 1) indicates the participant completed the activity and submitted it.
- Canceled (ID 2) indicates the participant did not want to complete the activity and explicitly canceled it.
- Expired (ID 3) indicates the activity was not responded to in time, so Ethica automatically closed the session and uploaded it to the server.
- Blocked (ID 4) indicates the session was blocked by another active session from the same activity and could not be prompted (more details below).
- Invalid Criteria (ID 5) indicates that based on the responses the participant has provided so far, this session's criteria is invalid and will not be presented. Note that the participant might submit more responses before the scheduled time of this session and those responses may change the status of this session and cause it to be prompted.
- In Progress (ID 6) indicates the session is started by the participant but it's not completed yet.
A given activity session contains 2 time values in its metadata: Scheduled Time, and Record Time. Scheduled Time specifies the time that the activity was scheduled to be prompted. This time is known in advance for activities scheduled via Time TL. For sessions that are prompted via other Triggering Logic types, this is set to the time the Ethica app starts the session. For example, if the activity contains a User TL, and the participant starts the activity by tapping on its button on the app's homepage, the time of tapping is the time the session is created, and is used as the Scheduled Time.
Record Time specifies the time the activity session was concluded and queued to be uploaded to the Ethica server. An activity session can be concluded with one of the following states:
When a session is marked as Completed, it means the participant has responded to all mandatory steps of the activity. For example, in the case of survey activities, Completed sessions will definitely contain responses to all mandatory questions, and may have responses to optional questions as well. For Expired and Canceled sessions, any data collected up to the time of expiration or cancellation will be uploaded to Ethica servers. Blocked sessions indicate the activity was not even prompted to the participant, and therefore, there is no response available for it.
Each activity can have an Expiry Time, which specifies how long after the Scheduled Time Ethica should wait for the participant to complete the activity and submit it. If you set the activity to never expire, Ethica will keep the activity session open indefinitely until the participant either completes the activity or cancels it. If you set the activity to expire after a certain duration, Ethica will wait for that duration after the Scheduled Time. If the participant does not complete the activity nor cancels it within this period, Ethica will close the session as Expired and upload it to the server.
At any given time, an activity can only have one open session. You cannot prompt an activity multiple times to a participant and wait for her/him to complete them one by one. If there is already an open session for a given activity, and the activity tries to open another session, the second session will be closed immediately and marked as Blocked. For example, assume you define an activity with a Time TL and configure it to be prompted at 8 am and 9 am. At 8 am Ethica will prompt the activity to the participant, opens a new session, and waits for the participant to complete the activity. At 9 am, Ethica tries to prompt the activity again. If the participant has completed or canceled the activity before 9 am, Ethica will prompt the activity again at 9 am as expected, and opens a new session for it.
If the participant does not respond or cancel the activity by 9 am, and the expiry time of the activity is 30 minutes, the session scheduled at 8 am will be marked as Expired by 8:30 am. Therefore, the Ethica app can prompt the activity again at 9 am and open a new session for it. But if the expiry time of the activity is set to 2 hours, the activity cannot be prompted at 9 am, as there is already an active session started at 8 am. In this case, Ethica will create a new session with the Scheduled Time set to 9 am, and immediately closes it without prompting it to the participant, and marks it as Blocked.
Note that if you have multiple activities in your study, each can have up to one open session. Therefore, at any given time the participant can have multiple open sessions to respond to.
If you intend to ask this survey activity from prospective participants and use their responses to determine whether they are eligible to join this study or not, you can use Eligibility TL. This Triggering Logic has a few differences with others:
- Only survey activities may have Eligibility TL. Other activities such as cognitive tasks or time-use diaries cannot.
- You can have only one survey activity with this type of Triggering Logic in your study.
- If you have a survey activity with this type of TL, you cannot add other TLs to it. Similarly, if you have other TLs added to your survey activity, you cannot also add Eligibility TL to it.
- You can not add notifications to surveys activity with Eligibility TL, as you don't need to notify people about the survey. This survey activity is presented when the participant is actively working with the Ethica app.
- You cannot define a TL Criteria for Eligibility TL.
When adding Eligibility TL to your survey activity, you need to specify an eligibility criteria which is used to determine whether the prospective participant is eligible to join your study or not:
If the criteria is evaluated to
True, the individual proceeds to the next step
and is presented with the consent form. Otherwise, she/he is shown a message
indicating they are not eligible for that study.
A User TL instructs Ethica to add a button to the study's homepage with the
specified title. Every time the participant taps on that button, a new session
for the activity is started and presented to the participant. In order to add a
User TL, you only need to specify a caption and an icon for the button. You also
can specify the TL Criteria, in which case the criteria should be evaluated to
True in order for Ethica to show the button. If you specify the TL Criteria
and it evaluates to
False, the given participant will not see the button
related to this Triggering Logic.
The following image shows how activity with User TL are presented on the study homepage in the Ethica app:
Note that Ethica will not notify participants when the activity is launched via User TL, as the participant is actively interacting with the app.
A Time TL specifies a time schedule based on which the activity is prompted to the participant. The following image shows the dialog for adding a new Time TL to your activity:
While the dialog may seem long and complex, you basically only need to specify when should be the first prompt, if/how the TL should be repeated subsequently, and when these repetitions should end.
Like other triggering logics, here you can specify a Criteria. You also can set a caption and an icon for the button which Ethica shows on the participant homepage to access the session created by this TL.
The first configuration for Time TL, Time Format, specifies whether you want to configure the time schedule in Absolute or Relative terms. If you choose Absolute, all time values you set will point to an absolute time, e.g. 2020-12-04 12:22:00. In this case, the activity will be prompted exactly on these times.
If you choose Relative, you will specify the time in terms of a duration. Ethica then adds duration to the participant's registration date or time in order to calculate the absolute time that the activity should be prompted. For example, you can specify the time as 1 day 2 hours and 30 minutes, which means the activity should be prompted 26 hours and 30 minutes after the registration. Therefore, the exact prompt time will vary depending on the registration time.
If you choose the Relative Time Format, you also have to set the Base Time to one of the following values:
- Study Registration Time refers to the exact date and time when a given participant joined your study.
- Study Registration Date refers to the beginning of the date on which the participant joined your study.
Following this, you specify whether you want to prompt the activity at a certain time, or at a time randomly chosen from a time window. If former, enable the Period option. If you leave the Period unchecked, you can specify the absolute or relative time that this activity should be prompted for the first time.
If you check the Period option, you will be asked to enter the lower bound and
upper bound of the time window from which a random time should be selected. You
can specify the lower and upper bound values as days, hours, minutes, and
seconds past the
Base Time. Ethica will add the relative lower and upper bound
to the base time to calculate the calendar date and time for the lower and upper
bound, and then uses the specified randomization method to draw an exact time
within that period.
For example, assume you set the following values:
Time Formatis set to
Base Timeis set to
Study Registration Time.
- Lower and upper bound of the
First Triggeris set to
If your participant joins on June 1st 1:30 pm. Ethica will prompt the activity at a random time from June 1st 3:30 pm to 5:00 pm.
Alternatively, assume you set the following values:
Time Formatis set to
Base Timeis set to
Study Registration Date.
Periodis not checked.
First Triggeris set to
If your participant joins on June 1st 1:30 pm. Ethica will prompt the activity exactly at June 3rd 9:00 am.
Note that if you set the
Base Time to
Study Registration Date, the first
date on which the participant joins your study is considered day 0 and is not a
complete date as you cannot prompt activities at any hour of the day during that
date. For example, consider a Time TL where the
Base Time is set to
Registration Date, and the lower and upper bound of the
First Trigger are set
0d 17:00:00 and
0d 18:30:00, respectively. The following list describes
when the participant should expect to receive the activity depending on their
participation date and time:
- If the participant joins on Jun. 1st before 5 pm, they will receive the activity at some point between Jun. 1st 5 pm and Jun. 1st 6:30 pm.
- If the participant joins on Jun. 1st after 5 pm but before 6:30 pm, they will receive the activity at some point in the time they have joined (e.g. 5:30 pm) and Jun. 1st 6:30 pm.
- If the participant joins on Jun. 1st between 6:30 pm to Jun. 2nd midnight, they will not receive the first trigger of the activity. They still can receive the subsequent repetitions, if the activity is expected to be repeated. This is because the time window specified for this activity is already passed (5 pm to 6:30 pm of the participation date).
After defining the time of the first prompt, you can decide whether your Time TL should be repeated or not. A Time TL can be repeated daily, weekly, monthly, or annually. You also need to specify when the repetition should end. You can choose to never end the repetition, end it after a certain number of occurrences, or end it after a certain number of days. Note that the number of days you choose for the last option is relative to the base time you have chosen above.
In the end, you can choose how the participant should be notified when the
activity is prompted via this Time TL. By default, Ethica will notify the
participant using all the
Notifications currently defined for
this activity. You can choose to only use a subset of the notifications by
Use only a subset of notifications check box.
You can add one or more Time TL to your activity. If you add more than one, Ethica will prompt the activity based on the union of all schedules defined for that activity.
When a new participant joins your study, for each Time-Triggered TL of each of your study's activities, Ethica creates the sessions they are expected to receive. Therefore, you can see ahead of time when a given participant is prompted with which activity. For longer studies, the number of sessions generated this way can be very large. To manage this, Ethica generates these sessions in batches following the logic explained below.
- When a participant joins your study, for each Time-Triggered TL, Ethica generates up to 50 sessions.
- If the TL requires more sessions, Ethica marks it as such.
- Everytime the number of sessions for such TLs drops below 25, Ethica generates another 50 sessions.
- The session generation happens when the participant's app reloads the study,
either by the researcher reloading the study on the participant's device, or
by participant pressing the
Reload Studiesbutton in the app.
- If the study reload does not happen one week before the last scheduled session, Ethica automatically reloads the study on the participant's device, and generates more sesessions for such TLs.
Assuming your study is already configured to record participants' interactions with each other or with other physical objects using Bluetooth Beacons, the Proximity TL allows you to prompt a given activity when a proximity with certain attributes has started or has ended. Please refer to the Bluetooth Beacon page for the definition and details on some of the terminologies used below.
The following image shows the dialog for adding a new Proximity TL to your activity:
The first few fields of this dialog is the same as other triggering logics: Criteria, Button Caption, and Button Icon. Further in this dialog you can specify what should be the team and role ID of the visiting beacon which is related to this Proximity TL. You can also specify whether the activity should be prompted when the beacon of interest is visited, or after it's departed given a minimum contact duration. You also can specify how long apart should be two sessions from this Triggering Logic.
The Received Signal Strength Indicator filter, or RSSI filter, allows you to specify how strong should be the signal of a visiting beacon in order to be considered for this Proximity TL. As the signal strength is commonly used as an indicator of the distance, you can use this option to specify how far the participant should be from the visiting beacon.
The Dropout TL specifies that the survey activity should be prompted when the participant decides to drop out of the study. Similar to the Eligibility TL:
- Only survey activities may have Dropout TL.
- You can have only one survey activity with Dropout TL in your study.
- If you have a survey activity with this type of TL, you cannot add other TLs to it. Similarly, if you have other TLs added to your survey activity, you cannot also add Dropout TL to it.
- You can not add notifications to survey activities with Dropout TL, as you don't need to notify people about the survey. This survey is presented when the participant is actively working with the Ethica app.
You can define Dropout surveys to understand what made participants decide to drop out of the study, e.g. the study was too much of a burden, they were concerned about their privacy, etc. More details on the Dropout process and surveys can be found in the Study Dropout section.