Understanding Schedule and Notification Parameters

This page includes extended descriptions for schedule and notification parameters. To see information about how to configure schedules and notifications, see Configuring Schedules and Notifications.

Configuration Parameters for Schedules

A survey can be made available by one or many schedules. The Schedule Configuration field contains an array of these schedules.

Configuring “For” Schedules

For schedules make surveys available to respondents for a specified duration of time.

A delay can be configured to offset the beginning of the schedule to a specified amount of time before or after the start event.
Recurrence rules can be configured to make the survey available to respondents at a specified frequency.

Parameter	JSON Code Example	Description	Requiredness
Name	`"name": "avail_6_hours"`	The unique name of the schedule within this survey.	Required
Description	`"description": "Available for 6 hours"`	The description of the schedule, if applicable. The description is only displayed in the schedule's JSON and isn't shown to respondents.	Optional
Additional Schedule Details	`"exportDetails": "10 hour post visit 1"`	Additional details about the survey schedule that are included in Survey Data and Adherence exports For example, if the survey has multiple schedules that start from the same event, you can use this to add details that are relevant to all of the schedules to the report.	Optional
Groups	`"groups": [ "youth" ],`	If the collection has groups, a schedule can be assigned to a subset of groups so that during the study the schedule is only applied to participants in those groups. By default, a schedule applies to participants in all groups. If a schedule is assigned to multiple groups, then a participant must be in all groups to trigger this schedule. For example: An event is related to the "Age Range" group "5 to 10 years of age" and the "Cohort" group "Cohort A". For a participant to receive this schedule, they must be in the "5 to 10 years of age" and "Cohort A" groups. To refer to a group, use the unique name of the group. You can position your pointer over the information icon next to the group name to see the group label and verify that you selected the correct group name. The system will validate that the groups selected are also related groups on the Events selected as Start Events or End Events.	Optional
Start	`"start": {...}`	The container for the schedule's start configuration. Contains the Start Events and Delay Value/Unit parameters below.	Required
Start Events	`"startEvents": ["visit_1"]`	One or more events that triggers the start of the schedule for respondents during the study. The value entered here is the event name. You can position your pointer over the information icon next to the event name to see the event label and verify that you selected the correct event.	Required
Delay Value and Unit	`"delay": { "value": 10, "unit": "hours" }`	The amount of time that the schedule is offset from the Start Event by. When the Start Event has a date and time, the offset is calculated from that to get the starting time for the schedule. Value can be any whole numeric value, including negative numbers. The following units are supported: minutes hours days weeks months years If you don't include a delay, during the study the schedule will start immediately at the date and time of any of its Start Events. When calculating a date from a schedule, delays with a unit of days, weeks, months, or years automatically “round down” to the beginning of the calculated day. For example, if a delay of 2 days is added to a start date of January 2 at 2:00pm, the delayed survey will become available on January 4 at 12:00am.	Optional
Available Type, Duration Value and Unit	`"available": { "type": "for", "duration": { "value": 6, "unit": "hours" } ... }`	The availability type and duration of the schedule. For schedules must use a type of for. Value can be any positive whole numeric value. The following units are supported: minutes hours days weeks months years When calculating a due date from a schedule, durations with a unit of days, weeks, months, or years automatically “round up” to the end of the calculated day. For example, if a duration of 2 days is added to a start event date of January 2 at 2:00pm, the survey will be available from January 2 at 2:00pm until January 4 at 11:59pm. Be careful when combining delays (especially negative delays) and durations in the same FOR schedule, particularly a schedule with units in days. Because delays “round down,” and durations “round up,” the actual date calculations may result in an availability window that is longer than you intend. For example, consider a schedule with a negative delay of -3 days and a duration of 7 days. When you enter a start event date of January 10 at 2:00pm, the negative delay counts backward 3 days to January 7, rounding down to 12:00 am. Then the duration counts forward 7 days to January 14 and rounds up to 11:59pm. January 7-14, inclusive, is a total of 8 calendar days, not 7. In this situation, if your intention is for the survey availability to expire at the end of the day on January 13, you should use a duration of 6 days, not 7.	Required
Recurrence Rule	`"recurrenceRule": "INTERVAL=1;FREQ=WEEKLY;COUNT=52"`	The recurrence rule parameter is included in the available container, if applicable. The rate at which the schedule recurs. INTERVAL can be any whole numeric value. The following FREQ units are supported: MINUTELY HOURLY DAILY WEEKLY MONTHLY YEARLY COUNT indicates how many times that recurrence rule is repeated. In the example shown on the left, the survey recurs once a week for 52 weeks.	Optional
End Events	`"end": { "endEvents": ["study_complete"] }`	One or more events that triggers the end of the schedule for respondents during the study. The value entered here is the event name. End Events may not be needed in the instance where a survey occurs only a set number of times.	Optional
Location	`"location": "home"`	Location where a participant or caregiver survey should be completed. This is displayed to site users. Only available when surveyType is ePRO. When the surveyType is eClinRO, the value is defaulted to "clinic" and does not need to be populated. The following values are supported: clinic home	Optional

Example “For” Schedule JSON Configuration

The following JSON snippet shows the For schedule parameters. The schedule behavior for the ePRO in this example is: “The avail_6_hours schedule starts immediately after the Dose 1 (E268D7C7-8A9C-4B7C-9FF5-2251727339EA) participant event datetime and is available for 6 hours every week until ended by either the entry of the Study Withdrawal participant event datetime (29DEEA8F-B757-4F82-95CA-676315EE66AA) or the entry of the Study Completion participant event datetime (29905D1D-967E-47DE-9700-84DFBA9DED48) by a site user.”

[
  {
    "name": "avail_6_hours",
    "description": "Available for 6 hours",
    "groups": ["youth"
    ],
    "start": {
      "startEvents": ["epro_assigned"]
    },
    "available": {
      "type": "for",
      "duration":
        {
          "value": 6,
          "unit": "hours"
        },
      "recurrenceRule": "INTERVAL=1;FREQ=WEEKLY"
    },
    "end": {
      "endEvents":["study_complete"]
    }
  }
]

Configuring “Between” Schedules

Between schedules make surveys available to respondents for a specified amount of time during the day.

A delay can be configured to offset the beginning of the schedule to a specified amount of time before or after the start event.
Recurrence rules can be configured to make the survey available to respondents at a specified frequency.

Parameter	JSON Code Example	Description	Requiredness
Name	`"name": "between_8am_and_noon"`	The unique name of the schedule within this survey.	Required
Description	`"description": "Available between 8AM and noon in the participant's local time"`	The description of the schedule within this survey, if applicable. The description is only displayed within the schedule's JSON and isn't shown to participants, caregivers, or site users.	Optional
Groups	`"groups": [ "youth" ],`	One or more groups that, when added, limit the number of people who this schedule will apply to. If groups are added across multiple group types, then a group from both group types must be selected to trigger this schedule. For example: A schedule has the "Age Range" group "5 to 10 years of age" and the "Cohort" group "Cohort A". For a participant to receive this schedule, the site must select both "5 to 10 years of age" and "Cohort A" groups when enabling eCOA for the participant. The value entered here is the unique name of the group. Use the group icon above the Schedule Configuration field to view groups and copy a group's unique name. You can position your pointer over the information icon next to the group name to see the group label and verify that you selected the correct group. The system will validate that the groups selected are also available groups on the Events selected as Start Events or End Events. If no groups are selected on a schedule and the collection has groups, then the system assigns all groups to the schedule.	Optional
Start	`"start": {...}`	The container for the schedule's start configuration. Contains the Start Events and Delay Value/Unit parameters below.	Required
Start Events	`"startEvents": ["visit_1"]`	One or more events that, when entered by a site user, triggers the start of the schedule. The value entered here is the event name. Use the calendar icon above the Schedule Configuration field to view events and copy their names. To view the event label, position your pointer over the information icon next to the row.	Required
Delay Value and Unit	`"delay": { "value": 10, "unit": "hours" }`	The amount of time that the schedule is offset from the Start Event by. When the Start Event has a datetime, the offset is calculated from that datetime to get the starting time for the schedule. Value can be any whole numeric value. The following units are supported: minutes hours days weeks months years	Optional
Available Type, Start/End Times	`"available": { "type": "between", "startTime": "08:00", "endTime": "12:00" }`	The availability type and window of duration of the schedule. Between schedules must use a type of between. startTime is the time of day at which the schedule begins, in the respondent's local time time zone. It must be entered in 24-hour time format (00:00 to 23:59). endTime is the time of day at which the schedule ends, in the respondent's local time time zone. It must be entered in 24-hour time format (00:00 to 23:59).	Required
Recurrent Rule	`"recurrenceRule": "INTERVAL=1;FREQ=WEEKLY;COUNT=52"`	The rate at which the schedule recurs. INTERVAL can be any whole numeric value. The following FREQ units are supported: MINUTELY HOURLY DAILY WEEKLY MONTHLY YEARLY COUNT indicates how many times that recurrence rule is repeated. In the example shown at the left, the survey recurs once a week for 52 weeks.	Optional
End Events	`"end": { "endEvents": ["study_complete"] }`	One or more events that, when entered by a site user, ends the schedule. The value entered here is the event name. Use the calendar icon above the Schedule Configuration field to view events and copy their names. End Events may not be needed in the instance where a survey occurs only a limited number of times or is ended by the End Time. You can position your pointer over the information icon next to the event name to see the event label and verify that you selected the correct event.	Optional
Location	`"location": "home"`	Location where a participant or caregiver survey should be completed. This is displayed to site users. Only available when surveyType is ePRO. The following values are supported: clinic home	Optional

Example “Between” Schedule JSON Configuration

The following JSON snippet shows the Between schedule parameters. The schedule behavior for an ePRO in the example below is: “The between_8_and_noon schedule starts 1 hour after the Visit 1 (visit_1) participant event datetime is entered by a site user and is available between 08:00am and 12:00pm every day for 7 days. No participant event ends this schedule.”

[
  {
    "name": "between_8_and_noon",
    "description": "Available between 8am and noon in the participant's local time",
    "location": "home",
    "groups": ["youth"
    ],
    "start": {
      "delay": {
        "value": 1,
        "unit": "hours"
      },
      "startEvents": ["visit_1"]
    },
    "available": {
      "type": "between",
      "startTime": "08:00",
      "endTime": "12:00",
      "recurrenceRule": "INTERVAL=1;FREQ=DAILY;COUNT=7"
    },
    "end": {
        "endEvents": []
    }
  }
]

Configuring “As Needed” Schedules

As Needed schedules make surveys available for respondents to complete as many times as they need. After a respondent submits the survey, it’s immediately available again.

Delays can be configured to offset the beginning of the schedule to a specified amount of time before or after the start event.
Because As Needed surveys can be completed multiple times by respondents, recurrence rules aren’t supported.

</tr>

Parameter	JSON Code Example	Description	Requiredness
Name	`"name": "as_needed"`	The unique name of the schedule.	Required
Description	`"description": "Available for the participant to take as many times as they want"`	The description of the schedule within this survey, if applicable. The description is only displayed in the schedule's JSON and isn't shown to participants, caregivers, or site users.	Optional
Groups	`"groups": [ "youth" ],`	One or more groups that, when added, limit the number of people who this schedule will apply to. If groups are added across multiple group types, then a group from both group types must be selected to trigger this schedule. For example: A schedule has the "Age Range" group "5 to 10 years of age" and the "Cohort" group "Cohort A". For a participant to receive this schedule, the site must select both "5 to 10 years of age" and "Cohort A" groups when enabling eCOA for the participant. The value entered here is the group name. Use the group icon above the Schedule Configuration field to view groups and copy their names. You can position your pointer over the information icon next to the group name to see the group label and verify that you selected the correct group. The system will validate that the groups selected are also available groups on the Events selected as Start Events or End Events. If no groups are selected on a schedule and the collection has groups, then the system assigns all groups to the schedule.	Optional
Start	`"start": {...}`	The container for the schedule's start configuration. Contains the Start Events and Delay Value/Unit parameters below.	Required
Start Events	`"startEvents": ["visit_1"]`	One or more events that, when entered by a site user, triggers the start of the schedule. The value entered here is the event name. Use the calendar icon above the Schedule Configuration field to view events and copy their names. You can position your pointer over the information icon next to the event name to see the event label and verify that you selected the correct event.	Required
Delay Value and Unit	`"delay": { "value": 10, "unit": "hours" }`	The amount of time that the schedule is offset from the Start Event by. When the Start Event has a datetime, the offset is calculated from that datetime to get the starting time for the schedule. Value can be any whole numeric value. The following units are supported: minutes hours days weeks months years	Optional
Available Type	`"available": { "type": "asNeeded" }`	The availability type of the schedule. As Needed schedules must use a type of asNeeded. The available container can contain the Available Start/End Time parameters below if needed.	Required
Available Start/End Times	`"startTime": "08:00", "endTime": "12:00"`	The Start and End times of an As Needed schedule are optional, but can be configured to make a survey available as needed at certain times of day. In the example at left, the As Needed schedule makes the survey available as needed to a respondent from 08:00 to 12:00. It's unavailable before or after that window. If a survey should be available as needed at all times, Start/End Times aren't necessary.	Optional
End Events	`"end": { "endEvents": ["study_complete"] }`	One or more events that, when entered by a site user, ends the schedule. The value entered here is the event name. Use the Calendar icon above the Schedule Configuration field to view the events and copy their names. End Events may not be needed in the instance where a survey occurs only a limited number of times or is ended by the End Time.	Optional
Location	`"location": "home"`	Location where a participant or caregiver survey should be completed. This is displayed to site users. Only available when surveyType is ePRO. The following values are supported clinic home	Optional

Example “As Needed” Schedule JSON Configuration

The following JSON snippet shows the As Needed schedule parameters described above. The schedule behavior of the ePRO in the example below is: “The as_needed schedule starts 1 week after the Dose 1 (F4E61AFF-9C71-49BD-B74D-4D44DD0E2A46) participant event datetime is entered by a site user, and it’s available as needed until the Dose 2 (4C8F4009-24B8-4BF4-B35F-B98B731B5EE0) participant event datetime is entered by a site user.”

[
  {
    "name": "as_needed",
    "description": "Available for the participant to take as many times as they want",
    "groups": ["youth"
    ],
    "start": {
      "delay": {
        "value": 1,
        "unit": "weeks"
      },
      "startEvents": ["epro_assigned"]
    },
    "available": {
      "type": "asNeeded",
    },
    "end": {
        "endEvents": ["study_complete"]
    }
  }
]

Configuration Parameters for Notifications

Notifications are configured within the schedule where you want the notification to be sent.

Notifications are included as an additional parameter in the schedule JSON, which is an array that contains one or multiple notifications.
Notifications are available for ePRO surveys. Notifications configured in ePRO survey schedules are expected to include the following information:
- Participant or caregiver notifications regarding their ePRO activity
- Site notifications regarding participant or caregiver ePRO activity
Participant and caregiver notifications are not available for eClinRO surveys.
If you configure any notifications for surveys in your collection, the notification text in each language is included in your study’s collection document. This can aid your study’s IRB/EC approvals, if applicable.
The Veeva notification templates are not pre-approved by IRBs/ECs for use in studies.

The following JSON snippet shows how notifications can be configured in the schedule JSON. The notification behavior of the ePRO in the example below is: “The participant or caregiver receives notification1 immediately when the survey becomes available, and they also receive notification2 one hour before the survey is due.”

[
  {
    "name": "as_needed",
    "start": {
      "startEvents": ["epro_assigned"]
    },
    "available": {
      "type": "asNeeded",
    },
    "end": {
        "endEvents": ["study_complete"]
    }
    "notifications": [
      {
        "name": "notification1",
        "template": "veeva_epro_participant_reminder_survey_available",
        "type": "available",
      },
      {
        "name": "notification2",
        "template": "veeva_epro_participant_reminder_survey_due",
        "type": "due",
        "offset": {
          "value": -1,
          "unit": "hours"
        }
      }
    ]
  }
]

Configuring New Survey Available Notifications

New Survey Available notifications alert a respondent when a new survey is available to them as configured by the survey’s schedule. The notification includes the display name of the survey. The content of the notification isn’t otherwise configurable.

Parameter	JSON Code Example	Description	Requiredness
Name	`"name": "on_avail"`	The name of the notification schedule. Must be unique within the schedule.	Required
Template	`"template": "veeva_epro_participant_new_survey"`	The notification template that the participant or caregiver receives. Only Veeva's standard notification templates are currently supported.	Required
Type	`"type": "available"`	The type of notification. New Survey Available notifications must use a type of available.	Required

Example New Survey Available Notification JSON Configuration

The following JSON snippet shows the New Survey Available notification parameters. The notification behavior of the ePRO in the example below is: “The user receives notification1 immediately when the survey becomes available.”

"notifications": [
  {
    "name": "notification1",
    "template": "veeva_epro_participant_reminder_survey_available",
    "type": "available",
  }
]

Configuring Survey Due Notifications

Survey Due notifications alert a participant, caregiver, or site user when a survey is approaching its due date as determined by the survey’s schedule. The notification includes the display name of the survey and the amount of time before it’s due. The content of the notification isn’t otherwise configurable. If the site survey due notification is configured, the site user will receive a compliance warning for the participant.

Parameter	JSON Code Example	Description	Requiredness
Name	`"name": "30_mins_before_due"`	The name of the notification schedule. Must be unique within the schedule.	Required
Template	`"template": "veeva_epro_participant_new_survey"` `"template": "veeva_epro_site_not_completed_survey"`	The notification template that the participant, caregiver, or site user receives. Only Veeva's standard notification templates are currently supported. Participant and caregiver due notifications should use the veeva_epro_participant_reminder_survey_due template. Site user due notifications should use the veeva_epro_site_not_completed_survey template.	Required
Type	`"type": "due"`	The type of notification. Survey Due notifications must use a type of due.	Required
Offset Value and Unit	`"offset": { "value": -30, "unit": "minutes" }`	The amount of time prior to the due date and time when the notification should be sent. Value must be any negative whole number. The following units are supported: minutes hours days weeks months years	Optional

Example Survey Due Notification JSON Configuration

The following JSON snippet shows the Survey Due notification parameters. The notification behavior of the ePRO in the example below is: “The participant or caregiver receives notification1 1 hour before the survey is due, and the site user receives notification2 30 minutes before the survey is due.”

"notifications": [
  {
    "name": "notification1",
    "template": "veeva_epro_participant_reminder_survey_due",
    "type": "due",
    "offset": {
      "value": -1,
      "unit": "hours"
    }
  },
  {
    "name": "notification2",
    "template": "veeva_epro_site_not_completed_survey",
    "type": "due",
    "offset": {
      "value": -30,
      "unit": "minutes"
    }
  }
]

Configuring Survey Complete Notifications

Survey Complete notifications alert a site user when a respondent completes a survey. The notification includes the display name of the survey. The content of the notification isn’t otherwise configurable. Delays aren’t supported for Survey Complete notifications.

Parameter	JSON Code Example	Description	Requiredness
Name	`"name": "notification1"`	The unique name of the notification schedule. Must be unique within the schedule.	Required
Template	`"template": "veeva_epro_site_completed_survey"`	The notification template the site user receives. Only Veeva's standard notification templates are currently supported.	Required
Type	`"type": "complete"`	The type of notification. Survey Complete notifications must use a type of complete.	Required

Example Survey Complete Notification JSON Configuration

The following JSON snippet shows the Survey Complete notification parameters described above. The notification behavior of the ePRO in the example below is: “The site user receives notification1 when this survey is completed by a participant or caregiver.

"notifications": [
            {
                "name": "notification1",
                "type": "complete",
                "template": "veeva_epro_site_completed_survey"
            }
        ]

Configuring Missed Notifications

Missed notifications alert a participant, caregiver, or site user when a participant or caregiver misses one or more surveys that are assigned to them. The notification includes the display name of the survey and how many surveys of that type the participant or caregiver missed. The content of the notification isn’t otherwise configurable. Delays aren’t supported for Missed notifications.

Parameter	JSON Code Example	Description	Requiredness
Name	`"name": "survey_missed_mv_notification"`	The unique name of the notification schedule.	Required
Template	`"template": "veeva_epro_participant_missed_survey"` `"template": "veeva_epro_participant_missed_surveys"` `"template": "veeva_epro_site_missed_survey"` `"template": "veeva_epro_site_missed_surveys"`	The notification template that the participant, caregiver, or site user receives. Only Veeva's standard notification templates are currently supported. Participant or caregiver missed notifications should use the veeva_epro_participant_missed_survey or veeva_epro_participant_missed_surveys templates. Site user missed notifications should use the veeva_epro_site_missed_survey or veeva_epro_site_missed_surveys templates.	Required
Type	`"type": "missed"`	The type of notification. Missed notifications must use a type of missed.	Required
numMissed	`"numMissed": 1`	The number of surveys that must be missed before the notification is sent. Note: If numMissed is 1, you must use the templates that end with survey. If numMissed is greater than 1, you must use the templates that end with surveys.	Required

Example Missed Notification JSON Configuration

The following JSON snippet shows the Missed notification parameters. The notification behavior of the ePRO in the example below is: “The participant or caregiver receives notification1 after they miss this survey 3 times, and the site user receives notification2 each time this survey is missed.”

"notifications": [
  {
    "name": "notification1",
    "template": "veeva_epro_participant_missed_surveys",
    "type": "missed",
    "numMissed": 3
  },
  {
    "name": "notification2",
    "template": "veeva_epro_site_missed_survey",
    "type": "missed",
    "numMissed": 1
  }
]

Complete List of Standard Notifications

Below is the complete list of standard notifications that can be included within your eCOA schedule. The table includes the exact template ID that you can copy and paste in your schedule configuration, the recipient of that notification (Participant, Caregiver, or Site), and the Title and Message content of the notification sent to the users. Variables within [brackets] in the Titles and Messages columns are replaced by information related to the study, participant, caregiver, or notification.

Template ID	Recipient	Title	Message	Example Title and Message
veeva_epro_participant_new_survey	Participant or Caregiver	New Survey Available	Your [Display Name] is now available.	New Survey Available Your Wellness Survey is now available.
veeva_epro_participant_reminder_survey_available	Participant or Caregiver	Reminder: Survey Available	Complete your [Display Name] as needed.	Reminder: Survey Available Complete your Wellness Survey as needed.
veeva_epro_participant_reminder_survey_due	Participant or Caregiver	Reminder: Survey Due	Your [Display Name] is due in [Notification Value] [Notification Unit].	Reminder: Survey Due Your Wellness Survey is due in 5 days.
veeva_epro_participant_missed_survey	Participant or Caregiver	Missed Survey	You missed your [Display Name]. Contact your study team if you're having trouble completing surveys.	Missed Survey You missed your Wellness Survey. Contact your study team if you're having trouble completing surveys.
veeva_epro_participant_missed_surveys	Participant or Caregiver	Missed Surveys	You missed your [Display Name] [Number Missed] times. Contact your study team if you're having trouble completing surveys.	Missed Surveys You missed your Wellness Survey 3 times. Contact your study team if you're having trouble completing surveys.
veeva_epro_site_completed_survey	Site	[Study Name] Participant Completed a Survey	[Study Name] participant [Participant ID] has completed [Display Name]. Note: This notification does not support caregiver surveys.	FEZZIK-07 Participant Completed Survey FEZZIK-07 participant 5551212 has completed Wellness Survey.
veeva_epro_site_not_completed_survey	Site	[Study Name] [User Role] Has Not Completed a Survey	[Study Name] [User Role] [Respondent ID] has not yet completed their [Display Name], which is due in [Notification Value] [Notification Unit].	FEZZIK-07 Caregiver for Participant 008 Has Not Completed a Survey FEZZIK-07 caregiver for participant 008 has not yet completed their Daily Morning Diary, which is due in 24 hours.
veeva_epro_site_missed_survey	Site	[Study Name] [User Role] Missed a Survey	[Study Name] [User Role] [Respondent ID] missed their [Display Name] today.	FEZZIK-07 Caregiver for Participant 008 Missed a Survey FEZZIK-07 caregiver for participant 008 missed their Daily Morning Diary today.
veeva_epro_site_missed_surveys	Site	[Study Name] [User Role] Missed Multiple Surveys	[Study Name] [User Role] [Respondent ID] missed their last [Number Missed] [Display Name] surveys.	FEZZIK-07 Caregiver for Participant 008 Missed Multiple Surveys FEZZIK-07 caregiver for participant 008 missed their last 7 Daily Morning Diary surveys.