Configuring Scores

Within the survey JSON, you can configure survey scoring. The scores are calculated, exported with survey data, and optionally displayed to sites.

Overview

  • You can define scores for answers to survey questions in the survey JSON.
  • Scoring is available in preview mode, allowing you to review and/or test your scoring configuration.
  • Once the survey is submitted, the score is calculated.
  • Site users have scoring visibility immediately after submission.
  • Scoring data is included in the Survey Data extract.

  • Editing a survey with scoring configured:

    • May result in differences in score calculations between the previously approved version and this version.
    • May require new translations in each supported language.

Defining Scores

The following Component Types can be used for scoring:

  • Single Choice: Uses the score parameter on each answer. For example, selecting “Occasionally” below would result in a score of 10 for this question. 
    "answers": [
{
  "answer": "Occasionally",
  "name": "1",
  "score": 10,
},
]
  • Multiple Choice: Uses the score parameter on each answer. All selected values are added together. For example, selecting both “Walk” and “Run” below would result in a score of 15 for this question. 
    "answers": [
{
  "answer": "Walk",
  "name": "walk",
  "score": 5,
},
{
  "answer": "Run",
  "name": "run",
  "score": 10,
},
]
  • Number Entry: Scoring is based on the numeric answer response. Only number entry components with oneNum field can be used in scoring.
  • Numeric Rating Scale: Scoring is based on the numeric answer response.
  • Visual Analog Scale: Scoring is based on the numeric answer response.
  • *Optional answers: Eligible for scoring if used within one of the above component types. Uses the score parameter on each optional answer. For example, selecting the optional answer “I do not take any medications” below would result in a score of 0 for this question. 
    "optionalAnswers": [
{
  "answer": "I do not take any medications",
  "name": "na",
  "score": 0,
},
]

Configuration Parameters for Scores

The following parameters will be within an array of scores at the highest level in the survey JSON. See example below to see where the scores array belongs:

{
 "name": "Survey Name",
 "description": "Survey Description",
 "licenseText": "© License Text",
 "sections": [
   "..."
 ],
 "conditions": [
   "..."
 ],
 "scores" :
 [
   {
     "scores": "score",
     "..."
   }
 ]
}
Parameter JSON Code Example Description Requiredness
The name of the score "score": "score"
  • The unique identifier of the score
  • This identifier is included in the Survey Data export for this score.
Required
The label of the score "label": "Survey Result" The display label of the score for site users and in data extracts Required
The calculation occurring within the score "function": "score.q1 + score.q3 + score.q5 + score.q7"
  • The function that defines the scoring calculation
  • Questions can be referenced by using the following convention: score.<question name>
  • Function has a list of supported operations available below
Required
The site user visibility setting "display": true The value that defines if the score is displayed to site users when viewing the completed survey in the system. Required
The result of the score if it is necessary to derive a value from the numerical score "result": [
{
  "condition": "{{score}} <= 7",
  "value": "{{score}} (Normal)"
},
{
  "condition": {{score}} <= 10",
  "value": "{{score}} (Borderline Abnormal)"
},
{
  "condition": "{{score}} > 10",
  "value": "{{score}} (Abnormal)"
}
]
  • Results provide the ability to include text and/or context with the score’s numerical value.
  • If not configured, then the numerical value of the function is displayed to the site user and exported with Survey Data.
  • The numerical result of the function can be referenced in the condition OR in the value by using {{score}}.
  • The condition parameter:
    • Condition is configured using the same supported operations as Function.
    • Can be null when there are no conditions needed (Example: You can add context to the numerical value without providing different results based on the value.)
    • The result of the condition must be either TRUE or FALSE.
      • If TRUE, then that value is displayed and exported.
      • If multiple conditions are TRUE, then the first TRUE value in the list is displayed and exported.
      • If all conditions are FALSE, then the numerical value is displayed and exported.
  • The value parameter:
    • Translated into the collection's Patient Languages
    • Contains the value that will be displayed to the site user and exported
 Optional

Example Survey Scoring JSON Configuration

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

"scores": [
 {
     "name": "score",
     "label": "Surve
y Result",
     "function": "score.q1 + score.q3 + score.q5 + score.q7",
     "display": true,
     "result": [
         {
             "condition": "{{score}} <= 7",
             "value": "{{score}} (Normal)"
         },
         {
             "condition": "And({{score}} > 7, {{score}} <= 10)",
             "value": "{{score}} (Borderline Abnormal)"
         },
         {
             "condition": "{{score}} > 10",
             "value": "{{score}} (Abnormal)"
         }
     ] }
],

Function and Result Condition Supported Operations

The following operations are supported in survey scoring:

Type Name Operator Function
Math Add + Sum()
Subtract - Not applicable
Divide / Not applicable
Multiply * Not applicable
Remainder % Not applicable
Parenthesis () Not applicable
Minimum Number Not applicable min()
Maximum Number Not applicable max()
Average Not applicable average()
Ceiling Not applicable ceiling()
Floor Not applicable floor()
Comparison Equal = Not applicable
Does Not Equal != Not applicable
Less Than < Not applicable
Less Than or Equal To <= Not applicable
Greater Than > Not applicable
Greater Than or Equal To >= Not applicable
Logical And (All Conditions True) && and()
Or (At Least One Condition True) || or()
If Statement Not applicable if()
Text Concatenation & concat()
Convert Number to Text Not applicable Text(number, 'format')

For more information and examples for each of these supported operations, visit the full reference guide.