REDCap: Automated Survey Invitation Tips and Tricks

Automated Survey Invitations (ASIs): Tips & Tricks

If you have one or more survey-enabled instruments in your REDCap project, you can configure automated invitations to go out to your project participants via email (or, if you have a Twilio account, via SMS).

The ASI configuration dialog gives you a lot of control over if and when an invitation will be generated, scheduled and sent. Here are some tips to get the most of out it!

Use Piping to "Mail-Merge" Participant Details

You can pipe data from any field in your project into your email message. For example, if you store each participant's name in one of your instruments, then you could pipe that in so that the invitation is addressed to the participant personally:

Remember that if your project is longitudinal, you must reference the name of the event where the relevant field data is saved:

Linking to your Survey

By default, the invitation text includes the [survey-link] and [survey-url] smart variables. Each participant's unique link to the survey that this is an invitation for will be "merged" in when the ASI is generated.

The difference between these two variables is that [survey-link] attempts to create a clickable HTML link with the survey's title as the link text, whereas [survey-url] just puts the raw survey URL (e.g. https://redcap.unimelb.edu.au/surveys/?s=XXXXXX) in as plain text.

If you only want to have one of the two variables, generally it's better to use [survey-url] for maximum accessibility.

If you do use [survey-link] , you can also manually specify your link text like so: [survey-link:follow-up survey] :

Linking to Multiple Surveys

Sometimes, you might want to include links to other surveys (such as a withdrawal survey, or an optional bonus survey) within your ASI, and you can have REDCap include those via variations of the same smart variables:

[survey-url:instrument_name]

[survey-link:instrument_name:link text]

The instrument_name portion must be the id that REDCap has assigned to the relevant instrument, which is typically just the human-readable name but all in lowercase and with underscores replacing spaces.

You can find a list of your instrument names in the codebook (Project Home and Design > Codebook):

If your project is longitudinal, don't forget to prefix the smart variable with the relevant event name e.g.

[3month_arm_1][survey-url:survey_a]

[3month_arm_1][survey-link:survey_a:Group A additional feedback survey]

Linking to the Survey Queue

If you are using the Survey Queue to provide a landing page for your participants (common if you have a lot of different surveys, some/all of which are optional, and you don't particularly care about the order they are completed in), then instead of including the [survey-url] / [survey-link] smart variables you can instead use [survey-queue-url] / [survey-queue-link] .

(Note that REDCap will throw up a warning if you don't have either [survey-url] or [survey-link] in your message text but you can ignore it as long as you have another means of accessing the survey, like the Survey Queue.)

Include a "Withdrawn" Flag in your Trigger Logic

It's a good idea to have a yes/no variable somewhere in an admin form that tracks whether each participant is withdrawn or still active (defaulting to active).

It's an even better idea to include a clause in your trigger logic that means the ASI will only be triggered for active participants e.g.

[admin_arm_1][consent] = 1 AND [admin_arm_1][withdrawn] <> 1

(In this example, the trigger logic will only evaluate to true once the enrolment survey has been completed, AND the participant consented, AND they are not withdrawn.)

Confirming Trigger Logic Just Before Invitations are Sent

For any invitations that are sent after a delay, we strongly recommend ticking the "Ensure logic is still true before sending invitation" checkbox (as in the example above).

This means that REDCap will check the trigger a logic a second time right before the invitation is due to be sent, so if for example the participant was withdrawn at some point between when the invitation was first created, and when it actually fell due, this additional check would see this and prevent the invitation from being sent.

Using Explicit, Static Anchor Dates

By default, REDCap uses the date and time the ASI is triggered as the "anchor date" for any invitations that will be sent out on a relative delay (e.g. 30 days later).

This default behaviour has a couple of downsides:

1. If you ever need to reschedule your ASIs, you don't have an explicit anchor date you can refer back to - the original trigger date isn't saved anywhere in your REDCap project and is lost when you delete and regenerate a given ASI.
2. If the trigger criteria first become true at e.g. 2AM, then that's typically the time when the invitation will be sent, however many days later. Particularly for non-international studies, your participants may ignore or even be slightly offended at receiving invitations outside of business hours.

Furthermore, if your project is longitudinal and has discrete time-points (e.g. baseline, 3-month, 6-month) etc, it's often better to specify an explicit anchor date that has been recorded against the participant record. This anchor date can be either manually supplied by study staff or automatically populated via a (potentially hidden) survey variable, as is appropriate for your project.

(The @HIDDEN-SURVEY action-tag means this field will be hidden when the instrument is filled in as a survey, and the @TODAY-SERVER action-tag means it will be auto-filled with today's date the first time the form loads).

(Because we're using a short text field with the date validation type for the anchor (NOT a date + time validation type), we can ensure the invitations are always sent at 10AM, 181 days after the date the participant was enrolled. Also note that as this project is longitudinal, we have to make sure we pick up the enrolment date from the correct event, which is Baseline in this case.)

Explicit anchor dates also let you send out an ASI some number of days before the date actually occurs, which is otherwise impossible, unless you use the datediff() function in your trigger logic as discussed below.

Static Anchor Dates vs a datediff() Trigger Clause

When you use an explicit anchor date in step 3 of your ASI configuration, and the value of that date changes after the ASI it anchors has already been triggered, then you will need to delete and regenerate any such ASIs as per the relevant how-to, so that the invitations pick up the anchor date's new value.

This is a tedious process, and one where it's easy to make mistakes that result in your participants either never receiving the ASI or receiving it an improper time.

SO, if your anchor date values are likely to change at least occasionally - perhaps because they are attached to appointment times, and your participants will obviously need the ability to change these appointment times when life gets in the way - using a datediff() trigger clause is typically better.

(In my experience, it is more common for an anchor date to be fixed and unchangeable, typically the date the baseline survey(s) are filled in, but there have been several projects where anchor dates were changeable or unknown ahead of time, and for those a datediff() clause proved ideal.)

When using a datediff() clause, you set your ASI to send immediately and add some logic to the trigger so that it only evaluates as true at the appropriate time:

AND datediff([baseline_arm_1][enrol_date], "today", "d", true) = 90

REDCap checks the trigger logic of each unscheduled ASI every couple of hours, so, in this example, 90 days (and up to ~2 hours) after the participant's enrolment date, the trigger logic will evaluate to true and the invite will be scheduled and sent out at once.

(To overcome the issue where the invitation then goes out at 2AM, you can change the datediff() clause to trigger a day earlier (day 89 in the example above), and have the invitation scheduled to go out at e.g. 10AM the next day).

This gives you maximum flexibility, allowing the anchor date to change freely up until the moment the datediff() clause evaluates as true.