> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Formulas
> How to write formulas that reference variables and perform calculations
This feature is not yet supported for the JSON Schema config type.
Formulas are special expressions that can reference fields from workflow steps and use functions to manipulate data and calculate values.
They are used in Validation steps to define validation rules.
## Examples
| Formula | Description |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `ISPRESENT(extraction1.address)` | Verify that an address has been extracted |
| `extraction1.amount = extraction1.price * extraction1.quantity + extraction1.tax` | Verify that the total amount is calculated correctly |
| `IF(classification1 = "invoice", extraction1.invoice_date, extraction2.due_date)` | If the document is an invoice, then get the invoice date, otherwise get the due date |
## Variables
A variable is simply a reference to a workflow data field. They can be outputs of document processor steps or fields retrieved from your system using External Data Validation steps.
### Classification
For Classification steps, the variable is the step name, e.g. `classification1`.
The type of the variable will be `text` and its value will be the file's classification type.
### Extraction
For Extraction steps, the variable is the step name joined with the field name, e.g. `extraction1.address` or `extraction2.line_items.quantity` (for nested object or array fields).
The type of the variable will match the type of the extraction field.
For subfields of an array, the type will be an array of the subfield's type.
The value may be `NULL` if the field could not be extracted.
### External Data Validation
For External Data Validation steps, the variable is the step name joined with the field path of the returned payload, `external1.path.to.field`.
It is your responsibility to ensure that External Data Validation variables
are populated and have the correct types. For example, to use array variables
you must return an object of arrays instead of an array of objects.
## Data types
All formulas values, including input variables, formula constants, and function outputs belong to one of the following data types.
| Type | Description |
| ---------- | -------------------------------------------------------------------------- |
| `boolean` | A `TRUE` or `FALSE` value |
| `number` | A 64bit floating number |
| `text` | A string of arbitrary length |
| `date` | A date without a time of day or time zone |
| `currency` | A monetary value containing a `number` amount and a ISO 4217 currency code |
| `array` | An array of the non-array type `T`. Mixed type arrays are not permitted. |
### Collection types
The `currency` and `array` types represent collections over one of the other primitive types and can be used wherever their underlying primitive type can be used.
For example, the `currency` type's primitive type is `number`, so it can be used in numerical operations like addition or multiplication with other `number` or `currency` values.
So can an array of numbers, but not an array of texts.
Note that when an operation or a function uses both collection and primitive types, then the output will usually, but not always, belong to the collection type.
For example, adding a `currency` and a `number` produces a `currency`, but comparing them will produce a `boolean` instead.
### Nulls
Values of any type can also be `NULL` which represents the absence of a value.
Generally, null values will be treated as zero values of their type (e.g. `0` or `FALSE` or `""`) when used in an operation or function.
Use the `ISPRESENT`, `ISBLANK`, or `IFNULL` functions to explicitly check for and handle nulls.
## Operations
The below table shows all the operations in their order of operations (from lowest to highest).
An operation with a higher order of operation will take precedence over a lower one.
| Operation | Type | Description |
| ------------- | --------- | ----------------------------------- |
| `a = b` | `boolean` | `a` is equal to `b` |
| `a <> b` | `boolean` | `a` is not equal to `b` |
| `a < b` | `boolean` | `a` is less than `b` |
| `a <= b` | `boolean` | `a` is less or equal to `b` |
| `a > b` | `boolean` | `a` is greater than `b` |
| `a >= b` | `boolean` | `a` is greater than or equal to `b` |
| `a + b` | `number` | `a` plus `b` |
| `a - b` | `number` | `a` subtract `b` |
| `s & t` | `text` | `s` concatenate `t` |
| `a * b` | `number` | `a` multiplied by `b` |
| `a / b` | `number` | `a` divided by `b` |
| `a ^ b` | `number` | `a` raised to the power of `b` |
| `-a` | `number` | Negative `a` |
| `( ... )` | `T` | Parentheses |
| `FUNC( ... )` | `T` | Function call |
## Functions
This is the list of all functions, their return types, and their behavior.
Please reach out to us if there are functions not included here that would be helpful to you!
| Formula | Type | Description |
| ----------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `ISPRESENT(arg: T)` | `boolean` | Returns whether or not the argument is not `NULL`. |
| `ISBLANK(arg: T)` | `boolean` | Returns whether or not the argument is `NULL`. |
| `IF(condition: boolean, ifTrue: T, ifFalse: T)` | `T` | Returns the value of `ifTrue` if `condition` is `TRUE`, returns the value of `ifFalse` otherwise. |
| `IFNULL(arg: T, ifNull: T)` | `T` | Returns the value of `arg` if it is not `NULL`, returns the value of `ifNull` otherwise. |
| `AND(arg: boolean, ...)` | `boolean` | Returns `TRUE` if all the arguments are `TRUE`, returns `FALSE` otherwise. |
| `OR(arg: boolean, ...)` | `boolean` | Returns `TRUE` if any of the arguments are `TRUE`, returns `FALSE` otherwise. |
| `NOT(arg: boolean)` | `boolean` | Returns `TRUE` if the argument is falsey (e.g. `FALSE`, `0`, `""`, `NULL`), returns `FALSE` otherwise. |
| `DATE(arg: text)` | `date` | Converts the given text into a `date` value. |
| `SUM(arg: array)` | `T` | Returns the sum of all the elements in the array. |
## Constants
Formulas may include constant values such as numbers (e.g. `0`, `12.50`, `-100`), texts (e.g. `"hello!"`, `""`), or booleans (`TRUE` or `FALSE`) only.
To declare a constant date, use the `DATE` function (e.g. `DATE("2024-01-01")`).
To include double quotation marks in a text constant, escape it with a backslash `\"`, e.g. `"She said \"Hi!\""`.
### SUM
The `SUM` function returns the sum of all subfield elements in an array field. For example, if you are extracting data from an invoice and have an array field `line_items` with a subfield `cost`, you can use the `SUM` function to get the total cost of all the line items. You could then compare that to the total amount due and validate that the data was correctly extracted.
```
SUM(extraction1.line_items.cost) = extraction1.total_amount_due
```