Using Custom Fields

Custom Fields allow you to make the MyDataHelps experience more dynamic for your participants. You can save information from participants and then use those fields in your surveys.

Custom Field Overview

There are three basic tasks needed to utilize custom fields successfully:

1. Create the custom fields for your project.
2. Set the custom field values for each participant.
3. Use the data.

This section gives an overview of the three tasks, which are expanded upon in subsequent sections.

Before you can use custom fields, you must create them in your project settings. Each field is assigned a name and a data type. You may use the same custom fields in multiple projects within your organization, but you must define them in each project that wishes to use them.  For more information, see Creating Custom Fields.

RKStudio provides several ways to set the values of those fields for each participant. You can set custom fields manually, either when inviting a participant or later in the participant viewer. You can also automatically save survey responses into a custom field. For more information, see Setting Custom Fields.

Finally, you will want to use the data from your custom fields to make the RKStudio experience more dynamic for your participants. You can tailor survey questions, answers, and messages based on a participant's prior answers, and also use custom fields to control survey delivery schedules. For more information, see Using Custom Fields.

Creating Custom Fields

To set up a custom field for your project:

1. Open your project and go to the "Project Settings" tab.
2. Select "Custom Fields."
   
3. Enter a name for the field, then click "Add."
   
4. Click "Save" when you're done adding/editing fields.

If you have multiple projects under one organization, you must create the custom field in the settings for each project that wants to use that field. Projects that do not have the field defined will not be able to set data for that field.

By default, custom fields store plain text. Once a field is added, you can change its data type to integer, decimal, or date. The system will ensure that any values entered match the selected type. For example, if the type is set to "integer", the system will reject decimal numbers or letters.

The "Editable?" check-box may be deselected to make the field read-only. Read-only fields cannot be changed in the participant viewer or populated by surveys. This is normally used only for fields created and managed by CareEvolution.

Be sure to click "Save" after adding, editing, or deleting custom fields.

Click the trash icon next to a custom field to delete it. Deleting custom fields will not affect previously collected survey data.

Setting Custom Fields

You can set custom fields manually in invitations or the participant viewer, or automatically based on a participant's survey answers. You may use any combination of these tools in your project.

Custom Fields in Invitations

If you know a participant's custom field value before they join, you can set that value when you invite them to your project. Custom fields are set like any other field in the invitation data. For example, if you have a custom field for SurgeryDate, you could set it in the invitation data like so:

Email,LastName,SurgeryDate,Gender
test@example.com,Smith,6/1/2020,Male
test3@example.com,Williams,8/15/2020,Female

Be sure that the name in the title row exactly matches the name of your custom field.

For more information about sending invitations, see Inviting Participants.

Custom Fields in the Participant Viewer

You can also set participant data manually in the participant viewer.

1. Open your project and go to the "Participants" tab.
2. Select a participant you wish to edit.
3. Select the "Participant Info" tab. Custom fields will be located below the basic demographic data.
4. If you need to edit a field, just change the value and click "Save."

For more information about using the participant viewer, see Viewing and Editing Participant Information.

Custom Fields in Survey Answers

You can save data from a participant's survey response into a custom field.  Steps like questions and forms have a "Populate Custom Field" setting that lets you select where to save the answer.  For example, you might want to store the answer to "How much do you weigh?" in a custom field for the participant's weight. 

For more information, see Setting Custom Fields from Survey Answers.

Using Custom Fields

Custom fields can be used to make your surveys more dynamic, or to control your survey delivery schedules.

Making Surveys Dynamic

You can use custom field data in your surveys to replace text in questions (steps), answers (value choices), and other messages. It can also control step and form navigation.

You reference a custom field in a survey like this: <%CustomField.FieldName%>

Be sure that the field name exactly matches the name of your custom field, including capitalization. 

For example, you can use custom fields to set an answer's default value based on a participant's previous answer:

Or to skip or show steps and form items based on the value of a custom field:

For more information, see Using Dynamic Fields.

Controlling Survey Schedules

You can use custom fields to define groups of participants ("segments"), and then use those segments in your survey scheduling.

For example, if you have a custom field tracking whether the participant is a smoker, you can create a participant segment including only smokers:

Then create a survey schedule that delivers surveys to only participants in that segment:

For more information, see Filtering With Participant Segments and Setting Project Survey Schedules.