Configuring Scores

You can configure survey scoring in the survey JSON. The scores are calculated on survey submission, exported with survey data, and optionally displayed to sites.

Overview

  • You can define scores for answers to survey questions in the survey JSON.
  • You can configure one or multiple scoring expressions, labels, and results in the scores parameter.
  • You can review and/or test your scoring configuration using Preview mode.
  • Once the survey is submitted, the score is calculated.
  • If you configure scores to display to sites, site users can view scores immediately after submission. Scoring data is included in the Survey Data extract.
  • Upversioning a collection with a survey that has scoring configured:
    • May result in differences in score calculations between the previously approved version and the new 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.
    • Scoring only supports number entry questions with a single answer, not those with multiple answers (e.g. Enter your height in feet and inches).
  • 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 question 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 where the scores array belongs in the following example:

{
 "name": "Survey Name",
 "description": "Survey Description",
 "licenseText": "© License Text",
 "sections": [
   ...
 ],
 "conditions": [
   ...
 ],
 "scores" :
 [
   {
     "score": "score1",
     ...
   }
 ]
}
Parameter JSON Code Example Description Requiredness
The scores container "scores": "[
 {
  "score": "score1",
]
  • The unique identifier of the score
  • This identifier is included in the Survey Data export for this score.
Required
In the “score” node:
The name of the score "score": "score1"
  • 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 function to calculate the score "function": "score.q1 + score.q3 + score.q5 + score.q7"
  • The function that defines how the score is calculated.
  • Questions can be referenced by using the following convention: score.<question name>.
  • Function has a list of supported operations available below.
 Required
The visibility of the score to site users “display”: true The value that defines if the score is displayed to site users when viewing the completed survey in the system. Required
The array of result categories that the score can fall into. "result": [
{
  "condition": "{{score}} <= 7",
  "value": "{{score}} (Normal)"
},
{
  "condition": {{score}} <= 10",
  "value": "{{score}} (Borderline Abnormal)"
},
{
  "condition": "{{score}} > 10",
  "value": "{{score}} (Abnormal)"
}
]
  • The result array provides the ability to categorize the score’s numerical value into one or many result categories and associate additional context with the score.
  • If the result array is not included, then the numerical value of the score is displayed to the site user and exported with Survey Data.
  • In the example, the numerical score can be categorized into one of three result categories. If the score is 5, it is in the “5 (Normal)” result category.
 Optional
In each "result" node:
The condition for the result category {
  "condition": "{{score}} <= 7",
  "value": "{{score}} (Normal)"
}
  • Condition is configured using the same supported operations as function.
  • You can reference the numerical score using “{{score}}”.
  • Can be null when there are no conditions needed. For 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.
 Optional
The value of the numeric score {
  "value": "{{score}} out of 100"
},
  • Translated into the collection’s Site Languages.
  • Contains the value that will be displayed to the site user and exported.
  • You can reference the numerical score using “{{score}}”.
 Required

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": "Survey Result",
     "function": "score.q1 + score.q3 + score.q5 + score.q7",
     "display": true,
     "result": [
         {
             "condition": "{{score}} <= 7",
             "value": "{{score}} (Normal)"
         },
         {
             "condition": "And({{score}} > 7,  <= 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.