In addition to dynamic text replacement for participant fields, MyDataHelps supports an expression language inside both surveys and notifications. This enables you to do things like:
- Format a participant field or date a specific way.
- Calculate a score based on custom field values.
- Conditionally display some text based on a custom field value.
Additionally, you can use the expression language to update custom field values in schedules.
Expressions must be enabled by CareEvolution. Contact us if expressions are not working in your surveys or notifications.
Table of Contents
Intro to Expressions
Expressions are based on a simplified form of the C# programming language, and can be used to perform operations like addition or multiplication. You can also use conditional operators. See Dynamic LINQ expression language for more information.
Expressions in Surveys and Notifications
Expressions can be a powerful tool when used in surveys and notifications, expanding your ability to display information back to the participant, but you must ensure they are formatted correctly. Unlike dynamic text replacement, which starts with <%, expressions must start with <%=, but still end with %>.
Similar to dynamic text replacement for participant fields, you can use expressions like this:
<%= ParticipantIdentifier %>
However, you can also create advanced expressions like:
<%= CustomField.SurgeryDate.ToString("MMMM dd, yyyy") %>
If the participant’s surgery custom field is 6/10/2023, this format string will output “June 10, 2023”.
Expressions, like participant fields, are substituted when a survey is started or a notification is sent. They will not update if the value of a custom field or demographic field changes in the middle of a survey, for instance.
Expressions in Schedules
Expressions can give you the ultimate flexibility when it comes to updating custom fields via schedules.
For example, you may wish to implement a Counter custom field that tracks how many times a participant completes a specific task. Each time the task is completed, you can trigger a schedule that updates the Counter value to:
CustomField.Counter+1
Alternatively, you can also use expressions to update a date value, such as:
DateTime.Now.AddDays(90)
This expression will output a date that is 90 days in the future. For example, you could update the ParticipantEndDate to 90 days after the enrollment date by creating the following schedule.
When setting custom field values via schedules, the expression does not need to be contained within<%and%>.
Available Expression Variables
| Variable | Example Expression | Description |
|---|---|---|
| ParticipantID |
<%= ParticipantID %> |
The ID of the participant (internal to MyDataHelps, automatically assigned) |
|
ParticipantIdentifier |
<%= ParticipantIdentifier %> |
The participant identifier (can be viewed from the Participants tab) |
|
InvitationStatus |
<%= InvitationStatus %> |
The invitation status of the participant, e.g. "Pending", "Canceled", or "Declined" |
|
Enrolled |
<%= Enrolled %> |
Whether the participant has created an account and has enrolled in the project via MyDataHelps (True or False) |
|
EnrollmentDate |
<%= EnrollmentDate %> |
The enrollment date of the participant |
|
InsertedDate |
<%= InsertedDate %> |
The date the participant was first created in your project |
|
ExcludeFromExport |
<%= ExcludeFromExport %> |
Whether the participant is excluded from export |
|
CustomField |
<%= CustomField.MyCustomField %> |
Any custom field in your project - just change “MyCustomField” to your custom field name. For instance, <%=CustomField.SurgeryDate%> |
|
DemographicField |
<%= DemographicField.FirstName %> or <%= DemographicField.DateOfBirth %> |
Demographic fields supported are:
|
|
Project |
<%= Project.Description %> |
Information about the project. Supported fields are:
|
|
Organization |
<%= Organization.Name %> |
Information about the organization. Supported fields are:
|
Generating Survey & Tab Links with Expressions
| Link | Example Expression | Description |
|---|---|---|
|
DeepSurveyLink |
<%= DeepSurveyLink("SurveyName") %> |
A deep survey link refers to a link that, when clicked, opens the participant’s survey within the app. See Completing Surveys with Survey Links for more information. |
|
DeepTabLink |
<%= DeepTabLink("TabName") %> |
A deep tab link refers to a link that, when clicked, takes the participant directly to a tab within the app. See Completing Surveys with Survey Links for more information. |
|
WebSurveyLink |
<%= WebSurveyLink("SurveyName") %> |
A web survey link refers to a link that, when clicked, opens the participant’s survey on the web, without requiring the participant to login to the app. See Completing Surveys with Survey Links for more information. |
Expression Examples
The following examples review how to format strings, format dates, and calculate scores using some of expression variables from the table above.
Formatting Strings
You can use various substring and concatenation methods to format strings in expressions.
For instance, if you would like to display just the participant's initials:
Your initials are <%= DemographicField.FirstName.Substring(0,1) + DemographicField.LastName.Substring(0,1)%>
For a participant named "John Doe", this would display:
Your initials are JD
Formatting Dates
Any date or timestamp custom fields, or the participant’s EnrollmentDate, can be formatted using the ToString method. More information on custom C# date format strings can be found here:
For instance, if the value of my custom field “SurgeryDate” is June 12, 2022, you can have a survey question like:
How did you feel after your surgery in <%= CustomField.SurgeryDate.ToString("MMMM") %>?
This would output:
How did you feel after your surgery in June?
You can also use the global DateTime.Now variable to display a relative date. You can have a survey question like:
How did you feel after your surgery <%= (DateTime.Now - CustomField.SurgeryDate).Days %> days ago
Assuming SurgeryDate was 30 days ago, this would display:
How did you feel after your surgery 30 days ago?
Calculating Scores
You can use basic math in expressions to calculate scores based on the available variables, for instance:
Your score is <%= (CustomField.Question1 + CustomField.Question2) - CustomField.Question3 %>
This cannot be used to calculate a score based on answers inside the same survey as the expression, as custom fields are only updated when a survey is fully submitted.
Conditionally Displaying Text
Conditional expressions can control whether certain text is displayed to a user at all, for instance:
<%= DemographicField.State == "MI" ? "You are in Michigan" :"You are not in Michigan" %>
If the "State" field for the participant is "MI" it will display "You are in Michigan", but if it is not, it will display "You are not in Michigan".