Creating and Using Custom Fields

Custom Fields allow you to make the MyDataHelps experience more dynamic for your participants by allowing you to save specific information about participants and use that information later in the participant journey. For example, you could save a participant's smoking status to a custom field, and only send a specific survey to participants that smoke. Additionally, you could display the value from a custom field, such as an important upcoming date for that participant within a notification.

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

Each of these tasks are expanded upon in subsequent sections.

Creating Custom Fields

Before you can use custom fields, you must create them either in your project settings or the survey editor. 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. The steps below outline how to create custom fields in your project settings; for more information on creating custom fields within the survey editor, see Custom Fields in Survey Answers. 

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. Update the custom field type, if necessary. By default, the custom field will have a type of "Text." 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.
5. Uncheck the "Editable?" box if you wish to make the field read-only. Read-only fields cannot be changed in the participant viewer or populated by surveys.
6. Click "Save Custom Field Settings" when you're done adding or 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.

To delete a custom field, click the trash icon on the far right side of the editor. Deleting custom fields will not affect previously collected survey data.

Setting Custom Fields

RKStudio provides several ways to set the values of custom fields for each participant. You can set them manually, either when inviting a participant or later in the participant viewer. You can also automatically save survey responses into a custom field or create schedules to populate custom fields at a specific time. 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, which can either be completed by the participant directly, or using coordinator surveys. Question steps and form steps have a "Populate Custom Field" setting under the Properties tab on the right side of the editor that lets you select where to save the answer to. Additionally, you can use WebView steps to populate custom fields.

For example, you could include a survey question about smoking status and store the participant's response in a custom field.

If your custom field doesn't show up in the drop-down list, it means that the custom field's data type is incompatible with the answer format. For example, you can't update a date field from a weight answer.

Alternatively, if you did not already have a custom field for "Smoker" created, you could select "New Custom Field" under the "Populate Custom Field" dropdown menu to create one. You will be prompted to create the field, as shown below. If you have multiple projects associated with your organization, select all that apply.

The Type dropdown in the Create Custom Field window above will only show data types that can be used in the existing survey step, based on the answer format chosen. For example, if the answer format is Numeric, the data types available would be Text and Integer.

Custom Fields in Schedules

You can automatically update a custom field based on a specified date or participant event by creating a schedule. For example, you could create a custom field for the participant's last day in the study and set it to 6 months after enrollment. For more information on how to use schedules to update custom fields, see Scheduling Survey and Notification Delivery and Custom Field Updates.

Using 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. 

Making Surveys and Notifications Dynamic

You can use custom fields to personalize surveys and notifications. Custom fields can be used to set a survey answer's default value, display personalized information in a notification, and control navigation logic within surveys.

Use the following format to reference custom fields: <%CustomField.FieldName%>

The field name must exactly match the name of your custom field, including capitalization.

Additionally, you can use custom fields to set an answer's default value based on a participant's previous answer. For example, you could ask a participant to confirm their date of surgery (based on the date you already have in the system):

Additionally, you can display this custom date in a reminder notification to participants.

Additionally, you can use custom fields in the survey Navigation tab to skip steps based on the participant's response. For example, if you want to ask a follow up question only for participants that smoke, you could include the following rule. 

For more information, see Using Dynamic Fields.

Scheduling Survey and Notification Delivery

You can use custom fields to define groups of participants (segments), and then use those segments to schedule survey and notification delivery.

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

Finally, create a survey schedule that delivers a survey only to participants in that segment:

For more information, see Filtering With Participant Segments and Scheduling Survey and Notification Delivery and Custom Field Updates.