> ## Documentation Index
> Fetch the complete documentation index at: https://docs.farmtrace.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Special functions

> Build decisions and work with device snapshots, files, hashes, parent records, and captured HTTP responses.

Some functions on this page need data supplied by the form or workflow. Check each **Requires** line before using one in a normal calculated field.

## `Between`

Checks whether a value is inside an inclusive range.

* **Syntax:** `Between(value, minimum, maximum)`
* **Requires:** three non-null comparable values of the same type.
* **Returns:** Boolean; `null` in any position produces `false`.
* **Best for:** acceptable measurement, date, and quantity ranges.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Between([Moisture], 10, 14)
```

## `Case`

Matches one expression against a series of values and returns the result paired with the first match.

* **Syntax:** `Case(expression, value, result[, value, result...][, elseResult])`
* **Requires:** an expression, one or more same-type value/result pairs tested for equality, and an optional final fallback. A `null` value does not match, including another `null`.
* **Returns:** the selected result, the fallback, or `null` when nothing matches and no fallback is supplied.
* **Best for:** converting codes or categories into labels and outcomes.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Case([Priority],
     "H", "High",
     "M", "Medium",
     "L", "Low",
     "Unknown")
```

Only the selected result is evaluated.

## `DeviceLatitude`

Returns latitude from the device snapshot captured for this formula.

* **Syntax:** `DeviceLatitude()`
* **Requires:** a workflow or form submission with a captured device location.
* **Returns:** Numeric latitude.
* **Best for:** coordinate exports and location-aware submissions.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
DeviceLatitude()
```

## `DeviceLocation`

Returns the complete location from the device snapshot captured for this formula.

* **Syntax:** `DeviceLocation()`
* **Requires:** a workflow or form submission with a captured device location.
* **Returns:** Location.
* **Best for:** storing a submission location and calculating distance.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Distance(DeviceLocation(), [Site Location], "km")
```

## `DeviceLongitude`

Returns longitude from the device snapshot captured for this formula.

* **Syntax:** `DeviceLongitude()`
* **Requires:** a workflow or form submission with a captured device location.
* **Returns:** Numeric longitude.
* **Best for:** coordinate exports and location-aware submissions.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
DeviceLongitude()
```

## `DeviceTimestamp`

Returns the timestamp stored with the captured device snapshot.

* **Syntax:** `DeviceTimestamp()`
* **Requires:** a workflow or form submission with a captured device snapshot.
* **Returns:** Timestamp.
* **Best for:** recording when the device observation was taken.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
DeviceTimestamp()
```

All four device functions read one consistent snapshot within an evaluation.

## `FileName`

Returns the original name of an attached file.

* **Syntax:** `FileName(file)`
* **Requires:** a File attachment value.
* **Returns:** Text.
* **Best for:** attachment labels, extension checks, and integration metadata.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
FileName([Certificate])
```

## `FileType`

Returns the media type of an attached file.

* **Syntax:** `FileType(file)`
* **Requires:** a File attachment value.
* **Returns:** Text media type, such as `image/jpeg` or `application/pdf`.
* **Best for:** routing, validation, and integration metadata.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
FileType([Certificate])
```

## `Hash`

Calculates a message digest and encodes the binary result as text.

* **Syntax:** `Hash(algorithm, data, encoding)`
* **Requires:** Text algorithm (`MD5`, `SHA`/`SHA1`, `SHA2_256`, or `SHA2_512`), Text data, and `binhex` or `base64` encoding.
* **Returns:** Text digest.
* **Best for:** third-party request formats, checksums, and deterministic identifiers.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Hash("SHA2_256", [Payload], "binhex")
```

<Warning>
  A plain hash does not authenticate a request. Use `HMAC` when the receiving API specifies a shared-secret signature.
</Warning>

## `HMAC`

Calculates a keyed message authentication code and encodes the result as text.

* **Syntax:** `HMAC(algorithm, key, data, encoding)`
* **Requires:** Text algorithm (`MD5`, `SHA`/`SHA1`, `SHA2_256`, or `SHA2_512`), Text secret key, Text data, and `binhex` or `base64` encoding.
* **Returns:** Text signature.
* **Best for:** signing third-party API requests exactly as required by that API.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
HMAC("SHA2_256", [Signing Key], [Payload], "base64")
```

Prefer `SHA2_256` or `SHA2_512` for new integrations. Use older algorithms only when the receiving service explicitly requires them.

<Warning>
  Formulas are evaluated on the client. Never embed a reusable signing secret in a formula or client-readable field. When a key must remain secret, sign the request on a server or through a protected integration.
</Warning>

## `If`

Checks conditions in order and returns the result paired with the first true condition.

* **Syntax:** `If(condition, result[, condition, result...][, elseResult])`
* **Requires:** one or more Boolean condition/result pairs and an optional final fallback.
* **Returns:** the selected result, the fallback, or `null` when no condition is true and no fallback is supplied.
* **Best for:** thresholds, status labels, and conditional calculations.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
If([Moisture] < 10, "Low",
   [Moisture] > 14, "High",
   "In range")
```

Conditions stop after the first true match, and only its result is evaluated.

## `In`

Checks whether a value equals any supplied candidate.

* **Syntax:** `In(value, candidate[, candidate...])`
* **Requires:** a value and one or more same-type candidates tested for equality. A `null` value does not match, including another `null`.
* **Returns:** Boolean.
* **Best for:** compact status, category, and weekday checks.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
In([Status], "Open", "Pending", "Escalated")
```

## `ParentKey`

Returns the parent record key made available while creating or populating a related record.

* **Syntax:** `ParentKey()`
* **Requires:** a workflow or session context. A parent key is available only when the flow was opened from a parent record.
* **Returns:** the supplied parent-key value, or `null` when the context has no parent key.
* **Best for:** populating a reference back to the record that opened the child flow.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ParentKey()
```

## `Response`

Returns the body of a captured HTTP response or extracts a value from it.

* **Syntax:** `Response()`, `Response(path)`, or `Response(path, type)`
* **Requires:** an HTTP response captured by the current integration step. Paths use dotted/indexed JSON form such as `data.items[0].id`, or XPath for XML.
* **Returns:** raw Text body with no arguments; extracted Text by default; `Text`, `Bool`/`Boolean`, `Numeric`/`Number`, `Date`, `Time`, or `Timestamp` when a type is requested. A missing JSON or simple XML path returns `null`; an XPath string expression with no match can return empty Text.
* **Best for:** reading identifiers, statuses, dates, and other values returned by an API.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Response()
Response("data.reference")
Response("data.total", "Numeric")
Response("/result/reference", "Text")
```

## `ResponseHeader`

Returns values from a header on the captured HTTP response.

* **Syntax:** `ResponseHeader(name)`
* **Requires:** a captured HTTP response and Text header name. Header matching ignores case.
* **Returns:** Text. Multiple values are joined with a comma and space; a missing header returns empty text.
* **Best for:** request IDs, pagination links, rate-limit metadata, and response formats.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ResponseHeader("content-type")
```

## `ResponseStatus`

Returns the status code of the captured HTTP response.

* **Syntax:** `ResponseStatus()`
* **Requires:** an HTTP response captured by the current integration step.
* **Returns:** Numeric HTTP status code.
* **Best for:** success/failure routing and retry decisions.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Between(ResponseStatus(), 200, 299)
```

<Warning>
  `Response`, `ResponseHeader`, and `ResponseStatus` are only available after the current workflow has captured a response. They do not make an HTTP request themselves.
</Warning>