Configuring Surveys

We recommend checking the Veeva Library or your customer library to use an existing survey before you configure a new one. If you want to create a survey that isn’t already in a library, you can configure it using the JSON editor in Veeva ePRO Studio. The JSON editor uses line-by-line error messages to guide you in configuring the survey.

See Sample JSON Survey, Schedule, and Notification Templates for for Veeva’s sample templates that you can use as a reference to configure your own surveys using JSON.

Configuring a Survey Using the JSON Editor

To create a new survey using the JSON editor, complete the following steps:

1. Access a collection.
2. Select Edit.
3. In the Surveys tab, select Add Surveys.
4. From the drop-down menu, select Create New Survey.
5. When the Create New Survey page opens, use the Survey Configuration field to configure your survey using JSON.
6. You can select the Preview Survey icon () to preview your survey while you create it. See Previewing a Survey for more information.
7. Add information for the following fields next to the JSON editor.
• Display Name: This text is the name that respondents see when they receive the survey.
• As-Needed Display Name: This field is only available when you add an as-needed schedule to the survey. As-needed surveys may be completed as many times as needed when they are available. The As-Needed Display Name can be configured to indicate a repetitive task such as “Log Exercise” or “Log Food Intake”. You are required to specify an As-Needed Display Name if one or more schedules for this survey has an available type of “asNeeded”. See Configuring Schedules and Notifications for more information.
• Add to Library: This section indicates whether the survey will be added to your customer library as a reusable survey. Select Yes or No.
• Selecting Yes adds the survey to your customer library for future reuse once this collection is approved.
• Selecting No won't add the survey to your customer library.
• This field is only available when creating a survey. After a survey is created, you cannot change the selection.
• Reviewed: Select Yes, No, or N/A. See Tracking Reviewed Surveys for more information.
• Licensed: Select Yes, No, or N/A. See Tracking Licensed Surveys for more information.
• Respondent: This field is only available if you are creating an ePRO survey, which is defined in the Survey JSON. Select Participant or Caregiver, to indicate who should receive and respond to the survey. You can’t change the respondent after the collection is approved.
• Respondent Burden: Select a value to represent the burden of the survey. The respondent burden is the perceived difficulty of the survey from a respondent perspective. Options include Very Easy, Easy, Moderate, Hard, and Very Hard.
• Survey Sequence: The survey sequence represents the order in which surveys are required to be completed. For example, when a respondent receives surveys with the sequence values 1 and 2, they must complete the survey with a sequence value of 1 before the survey with a sequence value of 2. This field is only available when you include schedules that do not include an as-needed schedule to the survey. Additionally, the following parameters apply to survey sequence:
• You can leave the field empty if the survey doesn’t have to be completed in a certain order.
• You can apply the same sequence value to multiple surveys.
• The sequence value must be greater than 0 and less than or equal to 1000. You can enter up to four decimal places.
8. Select Save.

Studio JSON Resources

See the following resources for more information on the JSON:

• Universal Survey Parameters
• Universal Survey Block Parameters
• Available Block Types
• Configuring Conditions

Configuring As-Needed Display Name

As-needed surveys may be completed multiple times throughout a study. The As-Needed Display Name can be configured to indicate a repetitive task such as “Log Exercise” or “Log Food Intake”. You are required to specify an As-Needed Display Name if one or more schedules for this survey has an available type of “asNeeded”. See Configuration Parameters for Schedules for more information.

Uploading Images to Surveys

You can upload .JPG, .PNG, or .GIF images to display in a survey. Images you upload are saved to the survey’s image library. Survey images adapt to the size of a respondent’s device. Images can be used in the following contexts:

• Above license text
• Above question or instruction heading text
• Above numeric rating scales
• As answers to single- or multiple-choice questions

To upload an image, complete the following steps:

1. When creating or editing a survey, select the Add Image icon () above the Survey Configuration field.
2. Drag-and-drop an image or select Browse to select a file from your computer. For optimal display, we recommend that images in these contexts have the following dimensions (in pixels):
   • License Images: At least 90px height
   • Heading Images: At least 600px height
   • Numeric Rating Scale Images: At least 2350px width
   • Answer Images with Answer Text: At least 300px height
   • Answer Images without Answer Text: At least 450px height
3. Select Upload.

4. In the Image Library tab, select the Copy URL icon () beneath the image. The image’s unique URL is copied to your clipboard, and you can paste it into the survey JSON configuration. For more context about which images can be displayed, see the following sections:

   • Universal Survey Parameters
   • Universal Survey Block Parameters
   • Configuring a Numeric Rating Scale (NRS) Question Type
   • Configuring a Single-Choice/Verbal Rating Scale (VRS) Question Type
   • Configuring a Multiple-Choice Question Type

Configuring Survey Conditions

Conditions show or hide controlled questions based on the response a respondent provides to one or more controlling questions. See Configuring Conditions for more information.

Configuring Scores

Survey scoring is configured within the survey JSON. See Configuring Scores for more information.

Questions of the following types can be used in scoring calculations:

• Single Choice
• Multiple Choice (all selected values will be added up)
• Number Entry (with a single entry)
• Numeric Rating Scale
• Visual Analog Scale

Supported HTML Tags

You can only use anchor links in license text and block headings, but all other HTML tags can be used in the following locations:

• License Text
• Block Headings
• Single Choice Answers
• Multiple Choice Answers
• Optional Answers
• VAS Minimum Label
• VAS Maximum Label

Previewing a Survey

To preview a survey from the respondent’s perspective, find the survey you want to previewand select the Preview Survey icon ().

To preview a survey in a different language (if translations have been uploaded), select the language from the Language drop-down menu.

To see how the survey is displayed on different devices, use the Preview Size menu to select a predetermined device size, enter the width and height for a custom device size, or rotate the preview device with the Rotate icon () in the Preview Size Settings.

While completing surveys in the preview, you can reset the survey to its original state by selecting the Reset button at any time. After submitting the survey, you will view a read-only version of the completed survey as a site staff member would see it. Any configured scores are displayed at the top of the survey. Select the Edit button to change the responses and re-submit the survey. Viewing the scores of survey submissions with various responses can help you validate scoring configuration.

Universal Survey Parameters

All surveys that you configure using JSON have universal parameters, which are described below.

Universal Survey Block Parameters

All blocks in a survey that you configure using JSON have universal parameters, which are described below.

Available Block Types

In the JSON editor, you can configure the following question types:

• Text block (instructional text)
• Single choice
• Multiple choice
• Numeric rating
• VAS
• Number entry
• Text entry
• Date
• Time
• Datetime

You can also configure a text block (instructional text). See below for more information about each block type.

All required parameters must be included in the JSON. Optional parameters can either be included with a value of null, or not included.

Configuring a Visual Analog Scale (VAS) Question Type

The following parameters apply for visual analog scale (VAS) question types:

Example Visual Analog Scale (VAS) JSON Configuration

The following JSON snippet illustrates the visualScale question parameters that are described above. The configuration below is not reviewed or licensed for use in collections.

{
  "type": "visualScale",
  "name": "q1",
  "questionNumber": "1",
  "heading": "Please tap on the scale to indicate how your health is TODAY.",
  "blockSettings": {
    "orientation": "vertical",
    "minNumber": 0,
    "maxNumber": 100,
    "minLabel": "The worst health you can imagine",
    "maxLabel": "The best health you can imagine",
    "markDisplayInterval": 10,
    "markNumberInterval": 100,
    "displayResult": false
  }
}

Configuring a Numeric Rating Scale (NRS) Question Type

The following parameters apply for numeric rating scale (NRS) question types:

Example Numeric Rating Scale (NRS) JSON Configuration

The following JSON snippet illustrates the numberScale question parameters that are described above. The configuration below is not reviewed or licensed for use in collections.

{
  "type": "numberScale",
  "name": "q2",
  "questionNumber": "2",
  "heading": "Please select on the scale how much pain you feel today.",
  "blockSettings": {
    "minNumber": 0,
    "maxNumber": 10,
    "answerImage": {
        "image": "https://patients.myveeva.com/assets/epro/12345-bc12-1234-a1f2-1a2e34fd5678/PainSurveyQ1ScaleImage.jpg",
        "description": "A range of emotional faces with an extremely sad face on the far left and an extremely happy face on the far right"
    },
    "customMarks": [
      {
        "positions":[0],
        "label": "No Pain"
      },
      {
        "positions":[10],
        "label": "Extreme Pain"
      }
    ]
  }
}

Configuring a Single-Choice/Verbal Rating Scale (VRS) Question Type

The following parameters exist for single-choice/verbal rating scale (VRS) question types:

Example Single-Choice/Verbal Rating Scale (VRS) JSON Configuration

The following JSON snippet illustrates the singleChoice question parameters that are described above. The configuration below is not reviewed or licensed for use in collections.

{
  "type": "singleChoice",
  "name": "q3",
  "questionNumber": "3",
  "heading": "How is your pain today?",
  "answerSet": {
    "answers": [
      {
        "name": "1",
        "answer": "",
        "score": 0,
        "answerImage": {
            "image": "https://patients.myveeva.com/assets/epro/12345-bc12-1234-a1f2-1a2e34fd5678/PainSurveyA1Image.jpg",
            "description": "An emotional face showing no pain"
            }
      },
      {
        "name": "2",
        "answer": "",
        "score": 1,
        "answerImage": {
            "image": "https://patients.myveeva.com/assets/epro/12345-bc12-1234-a1f2-1a2e34fd5678/PainSurveyA2Image.jpg",
            "description": "An emotional face showing slight pain"
            }
      },
      {
        "name": "3",
        "answer": "",
        "score": 2,
        "answerImage": {
            "image": "https://patients.myveeva.com/assets/epro/12345-bc12-1234-a1f2-1a2e34fd5678/PainSurveyA3Image.jpg",
            "description": "An emotional face showing moderate pain"
             }
      },
      {
        "name": "4",
        "answer": "",
        "score": 3,
        "answerImage": {
            "image": "https://patients.myveeva.com/assets/epro/12345-bc12-1234-a1f2-1a2e34fd5678/PainSurveyA4Image.jpg",
            "description": "An emotional face showing severe pain"
            }
      },
    ]
  }
}
{
  "type": "singleChoice",
  "name": "q4",
  "questionNumber": "4",
  "heading": "How much physical activity did you perform today?",
  "blockSettings": {
        "answerHeight": "constant",
        "displayAsDropdown": true
},
  "answerSet": {
    "answers": [
      {
        "name": "1",
        "answer": "No physical activity",
        "score": 10
      },
      {
        "name": "2",
        "answer": "Light physical activity",
        "score": 20
      },
      {
        "name": "3",
        "answer": "Moderate physical activity",
        "score": 30
      },
      {
        "name": "4",
        "answer": "A large amount of physical activity",
        "score": 40
      },
    ]
  }
}

Configuring a Multiple-Choice Question Type

The following parameters exist for multiple-choice question types:

Example Multiple-Choice JSON Configuration

The following JSON snippet illustrates the multipleChoice question parameters that are described above. The configuration below is not reviewed or licensed for use in collections.

{
         "type": "multipleChoice",
         "name": "q1",
         "questionNumber": "1",
         "heading": "Select all the over-the-counter pain medications you took this week.",
         "blockSettings": {
             "answerHeight": "variable"
            "displayAsDropdown": true
         },
         "answerSet": {
             "answers": [
                  {
                      "name": "q1-1",
                    "answer": "Acetaminophen",
                     "score": 8
                  },
                  {
                    "name": "q1-2",
                    "answer": "Naproxen sodium",
                     "score": 8
                  },
                  {
                    "name": "q1-3",
                    "answer": "Aspirin",
                     "score": 5
                  },
                  {
                    "name": "q1-4",
                    "answer": "Ibuprofen",
                     "score": 3
                  }
            ]
      }
},
 
{
       "type": "multipleChoice",
       "name": "q1",
       "questionNumber": "1",
       "heading": "Which physical activities did you perform today?",
       "answerSet": {
               "answers": [
                      {
                          "name": "q1-1",
                           "answer": "",
                           "score": 3,
                          "answerImage": {
                            "image": "https://patients.myveeva.com/assets/epro/12345-bc12-1234-a1f2-1a2e34fd5678/PainSurveyA1Image.jpg",
                            "description": "A person walking"
                                  }
                    },
                    {
                           "name": "q1-2",
                           "answer": "",
                           "score": 3,
                          "answerImage": {
                            "image": "https://patients.myveeva.com/assets/epro/12345-bc12-1234-a1f2-1a2e34fd5678/PainSurveyA2Image.jpg",
                            "description": "A person cooking"
                                  }
                    },
                    {
                           "name": "q1-3",
                           "answer": "",
                           "score": 3,
                          "answerImage": {
                            "image": "https://patients.myveeva.com/assets/epro/12345-bc12-1234-a1f2-1a2e34fd5678/PainSurveyA3Image.jpg",
                            "description": "A person doing light housekeeping"
                                  }
                    },
                    {
                           "name": "q1-4",
                           "answer": "",
                           "score": 3,
                          "answerImage": {
                            "image": "https://patients.myveeva.com/assets/epro/12345-bc12-1234-a1f2-1a2e34fd5678/PainSurveyA4Image.jpg",
                            "description": "A person swimming"
                                  }
                    }
               ]
        }
}

Configuring a Number Entry Question Type

The following parameters apply for number entry question types:

Example Number Entry JSON Configuration

The following JSON snippet illustrates the numberEntry question parameters that are described above. The configuration below is not reviewed or licensed for use in a collection.

{
  "type": "numberEntry",
  "name": "q1",
  "heading": "How long did you exercise today?",
  "questionNumber": "1",
  "answerSet": {
    "answers": [
      {
        "name": "hr",
        "label": "Hours",
        "placeholder": "Number of Hours",
        "minNumber": 0,
        "maxNumber": 24,
        "increment": 1
      },
      {
        "name": "min",
        "label": "Minutes",
        "placeholder": "Number of Minutes",
        "minNumber": 0,
        "maxNumber": 59,
        "increment": 1
      }
    ]
  }
}

Configuring a Text Entry Question Type

The following parameters apply for text entry question types:

Example Text Entry JSON Configuration

The following JSON snippet illustrates the textEntry question parameters that are described above. The configuration below is not reviewed or licensed for use in collections.

{
  "type": "textEntry",
  "heading": "What medications are you currently prescribed?",
  "questionNumber": "1",
  "blockSettings": 
  {
    "label": "Prescribed Medications",
    "placeholder": "Enter all medications that are currently prescribed to you. You may exclude over-the-counter medications such as vitamins.",
    "maxLength": 1000
  }
}

Configuring a Date Entry Question Type

A date entry question asks the respondent to respond by entering a date. To create a date entry question, you must configure a minimum and maximum valid date. You can optionally configure a default date that is displayed to respondents in the response field. Minimum, maximum, and default date parameters can be static or dynamic values.

Dynamic values are calculated from the point in time at which the respondent is responding to the question. For example, if the maximum date is dynamic with an offset of 3 days, the latest date in the future that a respondent can enter as a response is 3 days after the current date. If the respondent is responding on October 1, 2022, the latest date they can enter as a response is October 4, 2022.

Date Entry Question Universal Parameters

The following universal parameters apply for date entry question types:

The following tables describe how to configure the minimum, maximum, and default date parameters for date entry questions. All three parameters that are described below are contained in the blockSettings container that is described above.

Date Entry Question Minimum Value Parameters

Date Entry Question Maximum Value Parameters

Date Entry Question Default Value Parameters

Example Date JSON Configuration

The following JSON snippet illustrates the date entry question parameters that are described above. The configuration below is not reviewed or licensed for use in collections.

{
          "type": "date",
          "name": "q1",
          "heading": "When was your last injection?",
          "questionNumber": "1",
          "blockSettings": {
            "minValue": {
              "type": "static",
              "value": "2022-01-01"
            },
            "maxValue": {
              "type": "static",
              "value": "2022-12-31"
            },
            "default": null
          }
        },
{
          "type": "date",
          "name": "q2",
          "heading": "When was your last dose of the study drug?",
          "questionNumber": "2",
          "blockSettings": {
            "minValue": {
              "type": "dynamic",
           "offset": {
                "value": -1,
                "unit": "weeks"
              }
 
            },
            "maxValue": {
              "type": "dynamic",
              "value": "null"
            },
            "default": {
              "type": "dynamic",
              "offset": {
                "value": -1,
                "unit": "days"
              }
 
          }
        },

Configuring a Time Entry Question Type

A time entry question asks the respondent to respond by entering a time. You can optionally configure a minimum and maximum valid time. If you don’t configure a minimum or maximum time, the minimum defaults to 00:00 and the maximum defaults to 23:59, meaning all times are allowed. You can optionally configure a default time that is displayed to respondents in the response field. Minimum, maximum, and default time parameters can be static or dynamic values.

Dynamic values are calculated from the point in time at which the respondent is responding to the survey. For example, if the minimum time is dynamic with an offset of -30 minutes, the earliest time in the past that a respondent can enter as a response is 30 minutes before the current time. If the respondent is responding at 11:00, the earliest time they can enter is 10:30.

Time Entry Question Universal Parameters

The following universal parameters apply for time entry question types:

The following tables describe how to configure the minimum, maximum, and default time parameters for time entry questions. All three parameters that are described below are contained in the blockSettings container that is described above.

Time Entry Question Minimum Value Parameters

Time Entry Question Maximum Value Parameters

Time Entry Question Default Value Parameters

Example Time Entry JSON Configuration

The following JSON snippet illustrates the time entry question parameters that are described above. The configuration below is not reviewed or licensed for use in ePRO collections.

        {
          "type": "time",
          "name": "q1",
          "heading": "What time did you wake up today?",
          "questionNumber": "1",
          "blockSettings": {
            "minValue": {
              "type": "static",
              "value": "00:00"
            },
            "maxValue": {
              "type": "static",
              "value": "23:59"
            },
            "default": {
              "type": "static",
              "value": "07:00"
            }
          }
        },
        {
          "type": "time",
          "name": "q2",
          "heading": "What time was your last injection?",
          "questionNumber": "2",
          "blockSettings": {
            "minValue": {
              "type": "dynamic",
              "offset": {
                "value": -24,
                "unit": "hours"
              }
            },
            "maxValue": {
              "type": "dynamic",
              "offset": null
            },
            "default": null
          }
        },

Configuring a Datetime Entry Question Type

A datetime entry question asks the respondent to respond by entering a date and time. To configure a datetime entry question, you must configure a minimum and maximum valid datetime. You can optionally configure a default date, time, or datetime that is displayed to respondents in the response field. Minimum, maximum, and default datetime parameters can be static or dynamic values.

Dynamic values are calculated from the point in time at which the respondent is responding to the survey question. For example, if the minimum datetime is dynamic with an offset of -24 hours, the earliest datetime in the past that a respondent can enter as a response is 24 hours before the current datetime. If the respondent is responding at 11:00 on October 1, 2022, the earliest datetime they can enter is 11:00 on September 30, 2022.

Datetime Entry Question Universal Parameters

The following universal parameters apply for datetime entry question types:

The following tables describe how to configure the minimum, maximum, and default datetime parameters for datetime entry questions. All three parameters that are described below are contained in the blockSettings container that is described above

Datetime Entry Question Minimum Value Parameters

Datetime Entry Question Maximum Value Parameters

Datetime Entry Question Default Parameters

Additional Details

If a date unit is used as the offset unit (days, weeks, months, years), the resulting datetime depends on whether the value is a negative or positive number:

• If the offset value is negative, the resulting datetime is 00:00 on the day that’s [value] [units] from the datetime at which the respondent is answering the block.
  • Example: The minimum value is dynamic and -1 week. If the respondent is responding at 07:00 on October 20, 2022, the earliest datetime they can enter as a response is 00:00 on October 13, 2022.
• If the offset value is positive, the resulting datetime is 23:59 on the day that’s [value] [units] from the datetime at which the respondent is answering the block.
  • Example: The maximum value is dynamic and +3 days. If the respondent is responding at 07:00 on October 20, 2022, the latest datetime they can enter as a response is 23:59 on October 23, 2022.

Example Datetime JSON Configuration

The following JSON snippet illustrates the datetime entry question parameters that are described above. The configuration below is not reviewed or licensed for use in collections.

        {
          "type": "dateTime",
          "name": "q1",
          "heading": "When did you last eat a meal?",
          "questionNumber": "1",
          "blockSettings": {
            "minValue": {
              "type": "dynamic",
              "offset": {
                "value": -1,
                "unit": "days"
            },
            "maxValue": {
              "type": "dynamic",
              "offset": null
            },
            "default": {
              "type": "dynamic",
              "offset": null
              }
            }
          }
        },
        {
          "type": "dateTime",
          "name": "q2",
          "condition": "condition3",
          "heading": "When did you last visit your primary care physician?",
          "questionNumber": "2",
          "blockSettings": {
            "minValue": {
              "type": "static",
              "value": "2022-01-01T00:00"
            },
            "maxValue": {
              "type": "dynamic",
		          "offset": {
                "unit": 1,
                "value": "months"
              }
            },
            "default": {
              "type": "static",
              "value": "2023-01-01"
          }
        }

Configuring a Text Block

The following parameters exist for text/text blocks:

Example Text Block JSON Configuration

The following JSON snippet illustrates the text block parameters that are described above. The configuration below is not reviewed or licensed for use in collections.

{
  "type": "text",
  "name": "instruction",
  "heading": "This survey will ask you about your pain TODAY. Select OK to continue.",
}