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 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, our APIs return more Variables than are necessary for a given consumer implementation. The addition of 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
-- removesNULL
valuesfilter=variables:!system
-- removes System Variablesfilter=variables:!constant
-- removes Constant Variables
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 are as follows:
Array
Boolean
Date
Number
Percent
(Number
with percentformat
)Radio
String
(free text)Select
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 of the Variable, sometimes used as a descriptor.
Value
This is the calculated value
for the Variable. If there is no value, it will be null
. Inspecting a NULL value helps determine whether an Input Request was answered or not.
Value Default
The default value for a Variable, if specified. This is normally 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 to users. Formats commonly apply to Number
and Date
Variables.
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%"]
}
Numbers
Our Number
formatting scheme is based on Numeral.js.
Dates
Our Date
formatting scheme is based on Date-Fns.
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, System
Both isConstant
and isSystem
are Taffrail internal indicators for Variable meta data.
Updated 5 months ago