Automated Invitations Lessons Learned

Owned by maxx.somers@cchmc.org (Unlicensed)
Last updated: Apr 26, 2023 by Madison Lethebe
5 min read


As a Review: 

Automated Invitations are configured in the Online Designer and are set by Event:  

You can use a combination of tools to set Conditions, and define when to send a survey invitation: 


Automated Invitations can be straight forward or more advanced.  They can be a nice tool to ensure that a small number of invitations go out as needed, or they can help a study manage thousands of automated invitations. 


Automated Invitation Syntax Examples

There are several different things you can do with the automated survey invitation.  Here is an example of a complex automated survey invitation syntax with explanations of each part.  

Full syntax

contains([event_1][variable_ID], 'n') and [event_here][Form_complete]="2" and [event_here][followup_complete]<>"2" and datediff([event_1][visit_date], "today", "m")= 0   


contains([event_1][variable_ID], 'n') 

The contains command looks for an n in the defined field, Variable_ID, in the defined event, Event 1.  If the value the question variable_ID contains an n, that record will be eligible to qualify for an outgoing automated survey invitation. If there is not an n in the variable,  variable_ID, the automated invitation will not send for that record. 


[event_here][Form_complete]="2" 

This syntax looks for the answer to the variable form_complete.  If the value is 2 then that record will be eligible to qualify for an outgoing automated survey invitation. If the answer is not 2 an automated survey invitation will not send. 


[event_here][followup_complete]<>"2"

This is the 'does not equal' syntax. The record will be eligible to qualify for an outgoing automated survey invitation if the value for variable complete does not equal 2.  This syntax is useful for situations in which and responses can be "anything but" a particular answer. 


datediff(event_1][visit_date], "today", "m")= 0   

The date difference function allows the user to set rules about when an automated invitation will be sent based on the difference between two events. When the difference between the visit_date variable and 'today' meaning the date on the server is 0, that automated survey invitation will schedule on a record by record basis (assuming all of the previous conditions listed in the syntax are also true). 


Automated Invitation Lessons Learned

 1: Automated Invitations will not over write existing invitations which have been scheduled via any REDCap tool (manage survey participants, Record Survey functions, Previous Automated Invitations, etc). Therefore, if you would like automated invitations to re-schedule a set of invitations, you would need to go to manage survey participants → survey invitation log → future invitations --> and then delete each future invitation individually. If scheduled invitations remain for that event and record, the automated invitations will not trigger or reschedule an existing invitation. If an invitation has already gone out for a particular event and record, the automated invitation will not trigger an invitation to go out again.   

2: Automated invitations will trigger out going invitations under certain conditions.  First, when a record is saved or created, the automated invitation will be reviewed, scheduled or sent, after the save action.  Second, a date difference function will trigger REDCap to evaluate the automated invitation and send or schedule a set of invitations.  Date Difference functions are evaluated by a Cron Job (a function that periodically evaluates date difference for all records as true or false a few times a day). Date Difference functions are also evaluated and the automated invitation is sent or scheduled when a record is saved. 

One common date difference functions would be:  datediff("today", "today", "m")= 0  This is used to trigger outgoing invitations for cases in which the user has several records that already exist, and they would like to trigger the Cron Job in REDCap to evaluate the event and record as 'True' and send out invitations based on the additional scheduling logic shown in STEP 4. This method saves the users from needing to save or manipulate each record to trigger the automated invitation logic.  Users who use  datediff("today", "today", "m")= 0  should be aware that outgoing invitations will not schedule immediately (unless you re-save each individual record) as the Cron Job in RedCap only evaluates datediff functions a few times per day. Users can review scheduled invitations via manage survey participants → survey invitation log → future invitations.  Users can review past invitations via manage survey participants → survey invitation log → toggle the tool to past invitations. 

Another common date different function would be:  datediff([event_name][variable_name], 'today','d', true) ="10"  This is used to trigger outgoing invitations when the difference between two dates is equal to 'ten'.  An example would be needing to send to visit reminder 10 days after a scheduled visit for follow-up.  When the visit date - 'today' (the day on the server) = 10 REDCap will send the a follow-up survey.  If the study needed to send before a visit date, as a reminder, they could create a reminder event and then add the automated invitation logic datediff([event_name][variable_name], 'today','d', true) ="-10"  This would trigger outgoing invitations when the difference between two dates is equal to 'negative ten'.  

Users can review scheduled invitations via manage survey participants → survey invitation log → future invitations.  The Cron Job in RedCap only evaluates datediff functions a couple of times per day, currently REDCap will check the datediff at 4:20 am, so that  any additional scheduling logic selected is STEP 4 will be applied first thing in the morning. If you save a record, you should see the automated invitation load (assuming the logic is marked as true).  

3: The 'Ensure logic is still true before sending invitation?' logic is very important. It should likely be unchecked if you are using a datediff([event_name][variable_name], 'today','d', true) ="10"  type logic as a scheduling tool and then using STEP 4  to hold the invitation from going out for a few days. As REDCap will re-evaluate the logic against the record's data values whenever the record values are changed AFTER the invitation has been scheduled but BEFORE it has been sent to the respondent. And if the logic is no longer true (i.e., if the data values have changed during the time after the survey invitation was scheduled), it will not send the invitation to the respondent but will instead delete it (as if it had never been scheduled). 

However, if you have a key variable like [finalelig_eligible] = "1"  in your automated survey invitation logic, and you need to confirm that the record is still marked as eligible before sending, then the 'Ensure logic is still true before sending invitation?' should be selected. 

4. In the automated invitations other studies have found it helpful to use a DateDiff function that triggers early combined with Step 4 logic  “When to send invitations AFTER conditions are met” as a way to load the outgoing surveys. This is advantageous because they appear in Manage Survey Participants--> Survey Invitations Log --> Future Invitations before they are sent out.  Because invitations load before they are sent, staff can review outgoing invitations and make sure what is expected to go out is going out. Staff can also stop outgoing invitations as well, if needed.