Variables

A Variable is a named parameter used to make Advice possible. Variables can be used for input and are returned by the Rules Engine as a result of formulas, rules, and calculations.

Every API response includes an array of Variables in the variables[] property. An example Variable looks like this:

{
  "dataType": "Freetext",
  "format": null,
  "id": "qT7UxR1ii",
  "isConstant": false,
  "isToggleable": false,
  "isSystem": false,
  "name": "Account_Type",
  "nameAlt": "Account Type",
  "type": "VARIABLE",
  "value": "Roth IRA",
  "valueDefault": null
}

Limiting Variables in API Responses

In some circumstances, the API returns more Variables than are necessary for a given implementation. Adding three (3) simple parameters can reduce the response payload size and increase performance.

To filter the Variables returned, add this filter parameter (shown below with 3 values combined):

?filter=variables,variables:!system,variables:!constant

This specific filter will remove "System" and "Constant" Variables as well as remove any Variable with a NULL value. Each of these could be used independently:

• filter=variables -- removes NULL values
• filter=variables:!system -- removes System Variables
• filter=variables:!constant -- removes Constant Variables

🚧

Sparse Fieldsets

These Variable filters are different than Sparse Fieldsets.

Variable properties

Id

Each Variable has a unique identifier.

Data Type

The dataType indicates what type of data is stored in that Variable. The list of possible types is as follows:

• Array
• Boolean
• Date
• Freetext
• Number
• Percent (alias for Number with percent format)
• Radio

Name

The canonical name of the Variable. The names are strings and will always match this regular expression:

/(^[a-zA-Z0-9][a-zA-Z0-9_?]*$)/

Only alphanumeric characters, underscores (_), and question marks (?) are allowed.

Name Alt

This is a "friendly" name for the Variable, sometimes used as a descriptor. Often unused or ignored.

Value

This is the calculated value for the Variable. If there is no value, this property will be null. Inspecting a null value helps determine whether a question has been answered or not.

Value Default

The default value for a Variable, if specified. This is usually a Taffrail-defined default when common scenarios would apply, such as 67 for the Retirement_Age Variable.

Format

The format field specifies how a value should be displayed in the user interface. The Taffrail API will automatically apply formatting. Formats commonly apply to Number, Percent, and Date Variables.

{
  "format": "0[.]0",
  "value": 1.23,
  "valueFormatted": "1.2"
}

For all Variable types except Array, the value of the format property is a String. For Array types, the format property will be an Array of formats corresponding, in parallel, to the values in the value property.

For example:

{
  "type": "Array",
  "value": [1, 2, 3],
  "format": [null, null, "0.0%"],
  "valueFormatted": [1, 2, "3.0%"]
}

For more details, go to Formats.

Toggleable

Only Variables of type Boolean are capable of being "toggleable." This field is itself a Boolean indicating whether the Backlink can be switched on or off (true or false, respectively) with a toggle- or switch-style interface element.

Constant

isConstant indicates a Variable whose value is fixed and should not be changed by user input. Use this to filter Variables from display — constant Variables are typically reference data (e.g., IRS limits, regulatory thresholds) rather than user-modifiable inputs.

System

isSystem indicates a Variable used internally by the Rules Engine. System Variables are generally not relevant for display in the user interface. Use the filter=variables:!system parameter to exclude them from API responses.