**Source URL:** https://ecoa.veevavault.help/en/lr/916459/index.md

# 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.
* Scores are not supported in repeat sections or for free draw images.
* 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. For surveys with multiple parts, the score is calculated only when all parts are completed.
  * This includes transcribed surveys.
  * Any data changes, transcriptions, or survey restorations will cause scores to be recalculated.
* If you configure scores to display to sites, site users can view scores immediately after the survey or all survey parts are completed.
Scoring data is included in the Survey Data extract.
* Creating a new collection version 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 site language.
* For surveys with multiple parts, you can configure scores that include questions in different survey parts.


## 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.
~~~ json
"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.
~~~ json
"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.
* **Interactive Image - Joint Count:** Each joint that the respondent selects is counted as one point, and the total score is the total number of joints that were selected.
* **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.
~~~ json
"optionalAnswers": [
  {
    "answer": "I do not take any medications",
    "name": "na",
    "score": 0,
  },
]
~~~

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: Null values are treated as a 0.</p>
    </div>
  </div>
</div>

 

## 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:

~~~ json
{
 "name": "Survey Name",
 "description": "Survey Description",
 "licenseText": "© License Text",
 "sections": [
   ...
 ],
 "conditions": [
   ...
 ],
 "scores" :
 [
   {
     "score": "score1",
     ...
   }
 ]
}
~~~

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>JSON Code Example</th>
      <th>Description</th>
      <th>Requiredness</th>
    </tr>
  </thead>
  <tbody>
      <tr>
      <td>The scores container</td>
      <td><code>"scores": "[<br>&emsp;{<br>&emsp;&emsp;"name": "score1",<br>]</code></td>
      <td>
        <ul>
            <li>The unique identifier of the score</li>
            <li>This identifier is included in the Survey Data export for this score. </li>
        </ul>
      </td>
      <td>Required</td>
    </tr>
    <tr>
      <td colspan="4">In the “score” node:</td>
    </tr>
    <tr>
      <td>The name of the score</td>
      <td><code>"name": "score1"</code></td>
      <td>
        <ul>
            <li>The unique identifier of the score.</li>
            <li>This identifier is included in the Survey Data export for this score. </li>
        </ul>
      </td>
      <td>Required</td>
    </tr>
    <tr>
      <td>The label of the score</td>
      <td><code>"label": "Survey Result"</code></td>
      <td>The display label of the score for site users and in data extracts.</td>
      <td>Required</td>
    </tr>
    <tr>
      <td>The function to calculate the score</td>
      <td><code>"function": "score.q1 + score.q3 + score.q5 + score.q7"</code></td>
      <td>
        <ul>
            <li>The function that defines how the score is calculated.</li>
            <li>Questions can be referenced by using the following convention: score.&lt;question name&gt;.</li>
            <li>Function has a list of supported operations available below.</li>
            <li><strong>Important:</strong> Do not reference block names that contain hyphens. The system interprets hyphens as minus operations. If you use a function with a hyphen in it, the calculations it provides may be incorrect.</li>
        </ul>
      </td>
      <td>Required</td>
    </tr>
    <tr>
      <td>The visibility of the score to site users</td>
      <td><code>“display”: true</code></td>
      <td>The value that defines if the score is displayed to site users when viewing the completed survey in the system. </td>
      <td>Required</td>
    </tr>
    <tr>
      <td>The array of result categories that the score can fall into.</td>
      <td>
        <code>"result": [<br>{<br>&emsp;&emsp;"condition":  "{{score}} <= 7",<br>&emsp;&emsp;"value": "{{score}} (Normal)"<br>},<br>{<br>&emsp;&emsp;"condition":  {{score}} <= 10",<br>&emsp;&emsp;"value": "{{score}} (Borderline Abnormal)"<br>},<br>{<br>&emsp;&emsp;"condition":  "{{score}} > 10",<br>&emsp;&emsp;"value": "{{score}} (Abnormal)"<br>}<br>]</code>
      </td>
      <td>
        <ul>
            <li>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.</li>
            <li>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.</li>
            <li>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.</li>
        </ul>
      </td>
      <td>Optional</td>
    </tr>
    <tr>
      <td colspan="4">In each "result" node:</td>
    </tr>
    <tr>
      <td>The condition for the result category</td>
      <td><code>{<br>&emsp;&emsp;"condition":  "{{score}} <= 7",<br>&emsp;&emsp;"value": "{{score}} (Normal)"<br>}</code></td>
      <td>
        <ul>
            <li>Condition is configured using the same supported operations as function.</li>
            <li>You can reference the numerical score using “{{score}}”.</li> 
            <li>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.</li>
            <li>The result of the condition must be either TRUE or FALSE.</li>
              <ul>
                <li>If TRUE, then that value is displayed and exported.</li>
                <li>If multiple conditions are TRUE, then the first TRUE value in the list is displayed and exported.</li>
                <li>If all conditions are FALSE, then the numerical value is displayed and exported.</li>
              </ul>
        </ul>
      </td>
      <td>Optional</td>
    </tr>
    <tr>
      <td>The value of the numeric score</td>
      <td><code>{<br>&emsp;&emsp;"value": "{{score}} out of 100"<br>},</code></td>
      <td>
        <ul>
          <li>Translated into the collection’s Site Languages.</li>
          <li>Contains the value that will be displayed to the site user and exported.</li>
          <li>You can reference the numerical score using “{{score}}”.</li>
        </ul>
      </td>
      <td>Required</td>
    </tr>
  </tbody>
</table>

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

~~~ json
"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,  {{score}} <= 10)",
             "value": "{{score}} (Borderline Abnormal)"
         },
         {
             "condition": "{{score}} > 10",
             "value": "{{score}} (Abnormal)"
         }
     ] }
]
~~~

## Function and Result Condition Supported Operations

The operations below are supported in survey scoring. For more information and examples for each of these supported operations, see the full [Vault Formula Reference Guide](/en/lr/52324/).

<div class="note-border alert-important">
  <div class="alert alert-important" role="alert">
    <div><i class="far fa-exclamation-circle"></i></div>
    <div class="alert-text">
      <p><strong>Important</strong>: Do not reference block names that contain hyphens. The system interprets hyphens as minus operations. If you use a function with a reference block that includes a hyphen, the function calculations may be incorrect.</p>
    </div>
  </div>
</div>



<table>
  <thead>
    <tr>
      <th>Type</th>
      <th>Name</th>
      <th>Operator</th>
      <th>Function</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="13">Math</td>
      <td>Add</td>
      <td>+</td>
      <td>Not applicable</td>
    </tr>
    <tr>
      <td>Subtract</td>
      <td>-</td>
      <td>Not applicable</td>
    </tr>
    <tr>
      <td>Divide</td>
      <td>/</td>
      <td>Not applicable</td>
    </tr>
    <tr>
      <td>Multiply</td>
      <td>*</td>
      <td>Not applicable</td>
    </tr>
    <tr>
        <td>Sum</td>
        <td>None</td>
        <td>sum(number1, number2…)</td>
    </tr>
    <tr>
      <td>Remainder</td>
      <td>%</td>
      <td>Not applicable</td>
    </tr>
    <tr>
      <td>Parenthesis</td>
      <td>()</td>
      <td>Not applicable</td>
    </tr>
    <tr>
      <td>Minimum Number</td>
      <td>Not applicable</td>
      <td>min(number1, number2…)</td>
    </tr>
    <tr>
      <td>Maximum Number</td>
      <td>Not applicable</td>
      <td>max(number1, number2…)</td>
    </tr>
    <tr>
      <td>Average</td>
      <td>Not applicable</td>
      <td>average(number1, number2…)</td>
    </tr>
    <tr>
      <td>Ceiling</td>
      <td>Not applicable</td>
      <td>ceiling(number)</td>
    </tr>
    <tr>
      <td>Floor</td>
      <td>Not applicable</td>
      <td>floor(number)</td>
    </tr>
        <td>Round</td>
        <td>None</td>
        <td>round(original_number,number_of_digits)</td>
    <tr>
    </tr>
    <tr>
      <td rowspan="6">Comparison</td>
      <td>Equal</td>
      <td>=</td>
      <td>Not applicable</td>
    </tr>
    <tr>
      <td>Does Not Equal</td>
      <td>!=</td>
      <td>Not applicable</td>
    </tr>
     <tr>
      <td>Less Than</td>
      <td><</td>
      <td>Not applicable</td>
    </tr>
    <tr>
      <td>Less Than or Equal To</td>
      <td><=</td>
      <td>Not applicable</td>
    </tr>
    <tr>
      <td>Greater Than</td>
      <td>></td>
      <td>Not applicable</td>
    </tr>
    <tr>
      <td>Greater Than or Equal To</td>
      <td>>=</td>
      <td>Not applicable</td>
    </tr>   
    <tr>
      <td rowspan="3">Logical</td>
      <td>And (All Conditions True)</td>
      <td>&&</td>
      <td>and(expression1, expression2…)</td>
    </tr>
    <tr>
      <td>Or (At Least One Condition True)</td>
      <td>||</td>
      <td>or(expression1, expression2…)</td>
    </tr>
    <tr>
      <td>If Statement</td>
      <td>Not applicable</td>
      <td>if(expression, value_if_true, value_if_false)</td>
    </tr>
    <tr>
      <td rowspan="2">Text</td>
      <td>Concatenation</td>
      <td>&</td>
      <td>concat(text1, text2…)</td>
    </tr>
    <tr>
      <td>Convert Number to Text</td>
      <td>Not applicable</td>
      <td>Text(number, 'format')</td>
    </tr>
  </tbody>
</table>