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 -- removes NULL values
• filter=variables:!system -- removes System Variables
• filter=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 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 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.