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 formulaic 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, our APIs return more Variables than are necessary for a given consumer 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
• Number
• Percent (alias for Number with percent format)
• 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 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 an Input Request 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, System

Both isConstant and isSystem are Taffrail internal indicators for Variable metadata.