Triggering Logic

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.

Criteria

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 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 follow:

  • 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 to 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 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. AC, Time_TLC, and 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.

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 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:

  1. Go to the Researcher Dashboard.
  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 any activity to see the related actions.
  4. Click on the Release button on the right side to open the Release Activity dialog.

Release Activity
Dialog

  1. Pick the participants you want to send the activity to, and press Release.

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.

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 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:

  • 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 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.

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 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.

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 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.

Eligibility TL

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:

Adding Eligibility Screening Triggering Logic to the Survey
Activity

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.

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. 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.

Adding User Triggering Logic to the
Activity

The following image shows how activity with User TL are presented on the study homepage in the Ethica app:

User Triggering Logic Presentation 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.

Time TL

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:

Time Triggering Logic for Ethica
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 Format is set to Relative.
  • Base Time is set to Study Registration Time.
  • Period is checked.
  • 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 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 Format is set to Relative.
  • Base Time is set to Study Registration Date.
  • Period is not checked.
  • First Trigger is set to 2d 09:00:00.

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 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 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 selecting the 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.

Future Session Generation

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 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 sesessions 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 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:

Adding Proximity Triggering Logic 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.

Lastly, as described in the Time TL section, the Notifications 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 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.