Triggering Logics

Triggering Logics, 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 that 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 schedule.
Proximity TL specifies that data from Bluetooth Beacons determine when the Activity should be prompted.
Dropout TL specifies that the Activity should be prompted when the participant decides to drop out of the study.
Not all Activities support all different 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 TL 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 TLs. 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 Logics 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 Logics.
Note that not all combinations of the Triggering Logics types are allowed:
If you add an Eligibility TL to your Survey Activity, you cannot add any other Triggering Logics to it.
Survey Activities with a Dropout TL cannot have any other Triggering Logics.
Your study can have only one Survey Activity with Eligibility TL.
Your study can have only one Survey Activity with Dropout TL.
Criteria
The Activity Criteria is the primary control determining whether a participant can take the Activity. It can be thought of as a switch that turns the Activity on or off for each participant. If a participant meets the Criteria, they are allowed to take the Activity, but if they do not, they are excluded from taking the Activity.
The TL Criteria, on the other hand, controls a specific Triggering Logics that is used to initiate the Activity for a particular participant. TL Criteria can be thought of as a secondary switch that enables or disables an Activity for a given participant. For an Activity to be prompted via a given TLs, both the Activity Criteria and the TL Criteria should be evaluated to be True.
For example, assume you have an Activity with an Activity Criteria which is referred to as AC. This Activity has two Triggering Logics as follows:
User TL with a TL Criteria referred to as User_TLC.
Time TL with a TL Criteria referred to as Time_TLC.
Further, assume you enroll three participants in your study. For the first one, AC is evaluated as False. Therefore, this Activity will not be prompted to this participant, regardless of the evaluation result of User_TLC and Time_TLC. This participant will not be able to respond to this Activity.
For the second participant, AC is evaluated to True, User_TLC is also evaluated to True, but 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 User 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. AC, Time_TLC, and User_TLC, are evaluated to be 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.
To find the box for Activity Criteria:
1.Choose an Activity from the Activities page.
2.Click on the three dots at the end of the Activity's row.
3.Click on the Edit button.
4.Open the Settings tab from the right sidebar.
5.Scroll down to Criteria.
Manually Triggering an Activity
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 ignore the Activity Criteria (if any) and send a message to the participant's app using Cloud Messaging, asking the app to prompt the Activity to the participant right away. To do this:
1.Go to the Researcher Dashboard and then, the Basics page.
2.Select your study, and then from the left panel select Activities.
3.Here you can see all Activities defined for your study. You can click on the three dots at the end of each row to see the related actions.
4.Click on the Release button to open the Release Activity dialog.
5.Pick the participants you want to send the Activity to and then press Release.
Release Activity Dialog
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 checks if there are any prompted Activities en route, and if yes, prompts them immediately.
Activity Sessions
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 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:
Unanswered/Unknown (ID 0) indicates that a response to this particular session hasn't been registered or uploaded yet. This status doesn't necessarily mean the session hasn't been initiated; it might have been prompted, but the response is yet to be recorded.
Completed (ID 1) indicates the participant completed the session and submitted it.
Canceled (ID 2) indicates the participant did not want to complete the session and explicitly canceled it.
Expired (ID 3) indicates the session 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 the session 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, canceled, or expired 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 Logics 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:
Completed
Expired
Canceled
Blocked
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 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.
Expiry Time
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 complete the Activity or cancel 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 cancel it within this period, Ethica will close the session as Expired and upload it to the server.
Blocked Sessions
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 them 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, immediately closes it without prompting 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.
Bear in mind that once a session is canceled, expired, blocked, or completed, the corresponding upcoming Session Release Notifications will be automatically deleted by the system, and will not be triggered since there is no need to notify the recipient any more.
Eligibility TL
If you intend to ask the prospective participants to complete a Survey Activity and use their responses to determine whether they are eligible to join the study or not, you can use Eligibility TL. This Triggering Logic has a few differences from 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 Logics 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 link Notification Templates to the Survey 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 a Eligibility TL.
When adding Eligibility TL to your Survey Activity, you need a specific Eligibility Criteria which is used to determine whether the prospective participant is eligible to join your study or not:
Adding Eligibility Screening Triggering Logics to the Survey Activity
If an Eligibility Criteria is evaluated to be True, the individual proceeds to the next step and is presented with the consent form. Otherwise, they are shown a message indicating they are not eligible for that study.
User TL
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. 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 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.
Adding User Triggering Logics to the Activity
The following image shows how Activity with User TL is presented on the study homepage in the app:
​
​
User Triggering Logics Presentation in the 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.
Time TL
A Time TL specifies a 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:
Time Triggering Logics for Activity
While the form may seem long and complex, you only need to specify when should be the first prompt, if/how the TLs 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 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 duration. Ethica then adds duration to the participant's registration date or time 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.
In addition, after choosing the Relative, you 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 time randomly chosen from a time window or at a certain time. If the 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. For the Absolute time format, you need to specify the lower and upper bound values as days, hours, minutes, and seconds. On the other hand, in the Relative time format, you need to specify the relative lower and upper bound 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 relative lower and upper bound and then uses the specified randomization method (Uniform/Normal distribution) to draw an exact time within that period.
For example, assume you set the following values:
The Time Format is set to Relative.
The Base Time is set to Study Registration Time.
The Period is checked.
The lower and upper bound of the First Trigger is set to 0d 02:00:00 and 0d 03:30:00 respectively.
If your participant joins on June 1st at 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:
The Time Format is set to Relative.
The Base Time is set to Study Registration Date.
The Period is not checked.
The First Trigger is set to 2d 09:00:00.
If your participant joins on June 1st at 1:30 pm, Ethica will prompt the Activity exactly on June 3rd at 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 Study Registration Date, and the lower and upper bound of the First Trigger are set to 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 June 1st before 5 pm, they will receive the Activity at some point between Jun. 1st at 5 pm and Jun. 1st at 6:30 pm.
If the participant joins on June 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 on Jun. 1st at 6:30 pm.
If the participant joins on June 1st between 6:30 pm to Jun. 2nd at midnight, they will not receive the first trigger of the Activity. They still can receive 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 Notification Templates currently linked to this Activity.
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.
Future Session Generation
When a new participant joins your study, for each Time 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 TL, Ethica generates up to 50 sessions.
If the TL requires more sessions, Ethica marks it as such.
Every time 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 the participant pressing the Reload Studies button 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 sessions for such TLs.
Proximity TL
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 proximity with certain attributes has started or has ended. Note that only when you have created a Beacon-based study, the Proximity TL item on the TLs page gets enabled. 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:
Adding Proximity Triggering Logics to Your Activity
The first few fields of this dialog are 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 Logics.
The Received Signal Strength Indicator filter, or RSSI filter, allows you to specify how strong should be the signal of a visiting beacon 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.
Lastly, as described in the Time TL section, the Notification Templates allow you to determine how and when the participants should be notified or reminded when the Activity is prompted.
Dropout TL
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 notification templates 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 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.
Activities
Criteria
Last modified 11d ago