In addition to piping for participant fields, MyDataHelps supports an expression language in 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.
While Piping is available to all projects, Expressions are not enabled by default. If you would like to use Expressions in your project, please contact us.
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. As with piping, expressions must start with <%= and end with %>, like this:
<%= CustomField.SurgeryDate.ToString("MMMM dd, yyyy") %>
If the participant’s surgery custom field is 6/10/2025, this format string will output “June 10, 2025.”
Expressions, like piping, 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.
You can use expressions anywhere piping is accepted in a survey, including step contents, default values, consent forms, and web view steps.
Expressions in Schedules
Expressions can give you the ultimate flexibility when it comes to updating custom fields via schedules.
The syntax is different for using expressions in schedules (as opposed to surveys and notifications). When using these inside a schedule, drop the <%= and %>. The custom field will not update if you use that syntax inside of a schedule.
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.
Available Expression Variables
The following variables are available for use in Expressions, and match the variables available for Piping. Expression variables should normally not be null, but should be defaulted to empty string values when possible.
| 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. Can be null. |
| 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 %> |
The demographic fields supported are:
|
| Project | <%= Project.Description %> |
Information about the project. Supported fields are:
|
| Organization | <%= Organization.Name %> |
Information about the workspace. Supported fields are:
|
Variable Types
All expression variables are presented as .NET string types, except for some Custom Field types. Specifically:
| Custom Field Type | .NET Type |
|---|---|
| Date | DateTime |
| Decimal | decimal |
| Integer | int |
| Timestamp | DateTimeOffset |
Demographic Fields are all presented as strings, even if they contain data like Date Of Birth.
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. |
Displaying Previous Survey Results
For more information on how to use this type of expression, see Displaying Previous Survey Results.
| Result Type | Example Expression | Description |
|---|---|---|
| Last Result | <%= SA.Last("ResultIdentifier") %> <%= SA.Last("ResultIdentifier", "SurveyName") %> <%= SA.L("ResultIdentifier") %> <%= SA.L("ResultIdentifier", "SurveyName") %> |
This format will give you the last survey result. You can use any of the formats listed in the middle column. For Question Steps, |
| All Results | <%= SA.All("ResultIdentifier") %> <%= SA.All("ResultIdentifier", "SurveyName") %> <%= SA.A("ResultIdentifier") %> <%= SA.A("ResultIdentifier", "SurveyName") %> |
This format will allow you to select from all previous survey responses. You can use any of the formats listed in the middle column. For Question Steps, |
You only need to include the Survey Name in the expression if there are multiple surveys with the same Result Identifier.
If using the All Results format, <%= SA.A("RESULT_IDENTIFIER")[0]%> or <%= SA.All("RESULT_IDENTIFIER")[0]%> would display the participant's first/oldest response; whereas, <%= SA.A("RESULT_IDENTIFIER")[1]%> or <%= SA.All("RESULT_IDENTIFIER")[1]%> would display the participant's second response.
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. If you need to calculate a score within a survey, you should consider using a web view step.
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."
Converting Integers to Strings
If you have an integer custom field, but you want to concatenate that value with some other text, you can do so by first converting the integer custom field value to a string, and then adding the other text.
<%= CustomField.IntegerField.ToString() + "SomeMoreText" %>