Variables and scoring

A variable is a number that the form works out while it is being filled in. Use variables for quiz scores, prices and any other total built from answers. The editor calls this the Calculator. It is available from the Essential plan up.

Declaring variables

variables is a list of names.

"variables": ["score", "price"]

A name is made of letters, digits and hyphens, and is unique in the form.
Every variable is a number and starts at 0. There is no other type and no other starting value.
The first calculation added in the editor creates a variable named score when the form has none.

Calculations

Points are not stored on options or questions. A score is a calculation: an action in the logic block of a question that changes a variable when its condition is true.

Key	Type	Description
`action`	string	`add`, `subtract`, `multiply` or `divide`.
`condition`	object	When the calculation applies. Same format as a logic condition.
`details.target`	object	The variable to change: `{ "type": "variable", "value": "<name>" }`.
`details.value`	object	The amount. A fixed number: `{ "type": "constant", "value": 5 }`. Or the answer itself: `{ "type": "component", "value": "<question ref>" }`.

Points for an option

{
  "type": "component",
  "ref": "c3a9e1b7-5f24-4d68-8e0b-1a7c6d9f2e53",
  "actions": [
    {
      "action": "add",
      "condition": {
        "op": "is",
        "vars": [
          { "type": "component", "value": "c3a9e1b7-5f24-4d68-8e0b-1a7c6d9f2e53" },
          { "type": "choice", "value": "5d2f8c41-9b7e-4a13-a6c0-2e4f6b8d0a17" }
        ]
      },
      "details": {
        "target": { "type": "variable", "value": "score" },
        "value": { "type": "constant", "value": 1 }
      }
    }
  ]
}

A quiz is a set of such calculations, one for each correct option, and an end page that shows the result with {{variable:score}}.

Adding the answer itself

With the condition always, a number, rating, satisfaction or NPS question can add its own answer to a variable:

{
  "action": "add",
  "condition": { "op": "always", "vars": [] },
  "details": {
    "target": { "type": "variable", "value": "score" },
    "value": { "type": "component", "value": "9d0b2c4e-6a81-4f37-b5c9-0e2a4c6f8b13" }
  }
}

What the editor writes

The Calculator writes one kind of condition per question type, always about the question that owns the calculation.

Question type	Condition
`text`, `mail`, `website`, `dropdown`	`equal` to a text. For a dropdown, the label of the option.
`multiple_choice`, `picture_choice`	`is` an option.
`yesno`, `legal`	`is` `true` or `false`.
`number`, `rating`, `customer_sat`, `opinion_scale`	`equal` to a number, or `always` with the answer as the amount.
`date`	`on` a date.
`file_upload`, `signature`	`answered`.

Calculations cannot be added to phone_number, matrix, ranking, slider, numbers_scale, constant_sum, semantic_differential and statement.

How values are worked out

While the form is being filled in, each variable is rebuilt from 0 with the calculations of the pages the respondent has passed, in their order. The value is current on every page and can be shown with {{variable:<name>}}.
Going back removes the calculations of the pages after the one the respondent returns to.
The amount of a calculation that uses the answer is the number of the answer. A yes counts as 1 and a no as 0.
Results are rounded to two decimal places.
When the response is submitted, the values are worked out once more on the server, and those are the values stored with the response.
A variable that no calculation has touched stays 0, so multiplying or dividing it leaves 0.

Where values appear

Place	How
In the form	`{{variable:<name>}}` in a title, a description, or an end page address. See Inserted values.
In logic	As the left operand of a condition, with the number operators.
In responses	`variables`: a list of `{ "name", "value" }`. See Answers.
In webhooks	The same list in the payload.
In exports	One column per variable.
In notification e-mails	`{{variable:<name>}}` and `{{form:variables}}`.