Configuring Surveys

If you would like to include a survey that isn’t already in the Veeva Library or your customer library, you can configure it using the JSON editor in MyVeeva Studio. The JSON editor uses line-by-line error messages to guide you while you design a survey using JSON. See Sample JSON Survey, Schedule, and Notification Templates for Veeva 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 respondent or site survey using the JSON editor, complete the following steps:

1. Navigate to 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. Populate the following fields to the left of the JSON editor.
• Display Name: This is the name that respondents see when they receive the survey.
• Add to Library: 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.
• 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 Burden: Select a value for 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.
• Note that when editing the survey, other fields may become available. See the following sections for more information:
• Configuring As-Needed Display Name
• Configuring Survey Sequence
8. Select Save.

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

Configuring Survey Sequence

Survey sequence represents the order in which surveys should 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. Additionally, the following parameters apply to survey sequence:

• 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.
• You can leave the field empty if the survey doesn’t have to be completed in a certain order.
• Survey sequence is only available when editing a survey with a schedule.
  • Survey sequence is not available if one or more schedules for this survey has an available type of “asNeeded”.

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 information on the contexts in which images are 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

Surveys can support a variety of HTML tags.

The following table shows where various HTML tags can be used.

Previewing a Survey

You can preview a survey from the respondent’s perspective in the survey preview. To preview a survey, locate the survey you want to preview in the survey library, the Surveys tab, or a survey’s JSON editor and select the Preview Survey icon ().

In the survey preview, you can preview a survey in a different language (if translations have been uploaded) by using the Language drop-down menu. From the Preview Size settings you can control the size of the device by selecting a predetermined device size, entering width and height for a custom device size, or by rotating the device with the Rotate icon ().

While completing surveys in the preview, you can reset the survey to its original state by selecting the Reset button at any time. After submission, scores (if they were configured) will appear at the top of the survey as a Site Staff would see them. Selecting the Edit button allows you to change the responses and re-submit the survey, which can be helpful in validating 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 9 question types: visual analog scale (VAS), numeric rating scale (NRS), single-choice/verbal rating scale (VRS), multiple-choice, number entry, text entry, date entry, time entry, and datetime entry. 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": {
    "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 Value 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": null
            },
            "default": {
              "type": "dynamic",
              "offset": {
                "value": -1,
                "unit": "months"
            }
          }
        }

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.",
}