Expressions in the builder - KayanOS Documentation

Use expressions to make a rule visible

An expression is appropriate when a value or decision can be derived consistently from fields that already exist. It is not a replacement for a workflow design, a permission model, or a review step. Good builder uses include:

calculating a service target from received date, category, and priority;
showing a conditional section only when a request needs an inspection;
validating that an amount is positive or a reference has a required format;
constructing a readable document or notification line from structured fields;
summarizing a related list for an internal reviewer.

Do not use an expression to conceal a critical decision, to bypass an approval, or to place a secret in a template.

Choose the right place for the rule

Need	Best fit	Example
Show a value derived from fields	Calculated field	estimated fee, elapsed days, combined label
Prevent invalid input	Field validation	required reference, allowed value range
Show or hide a section	Layout or form condition	display inspection details only when needed
Generate readable text	Document template or label expression	service acknowledgement, case title
Find permitted form data	Form expression with `getRecords`	show qualifying licenses in a staff form

Keep the rule near the decision it supports. A calculated service target belongs with the request fields; a document phrase belongs in the document template; a permission-sensitive lookup belongs only in its supported form context.

Build a calculated field step by step

1. Define the result in plain language

For a permit request, write: “The target date is two days after receipt for urgent requests and seven days after receipt for all other requests.”

2. Confirm the source fields

You need a Date or Date-time field such as received_at and a controlled field such as priority. Do not rely on a visible label if the expression needs the field key.

3. Write the smallest expression

$.priority == "urgent" ? addDays($.received_at, 2) : addDays($.received_at, 7)

4. Test normal and exceptional records

Test an urgent request, a normal request, and a request with no received date. Decide what the blank-date result should be before publishing. If a missing date must block work, use a validation rule; do not silently calculate an unreliable target.

Four practical patterns

Calculate a numeric result

Use normal fields for amounts and a calculated field for the final, reviewable result.

round(($.base_fee + $.inspection_fee) * $.multiplier, 2)

Use this for fee estimates, quantities, progress percentages, or workload totals. Store the inputs separately so a reviewer can understand the result.

Show a conditional section

Use a simple condition to avoid asking irrelevant questions.

$.requires_inspection.value == true

For a licensing form, use this condition on the inspection section. The condition improves the entry experience; it does not grant access or change the record status.

Validate a reference before saving

Validation expressions return true when valid and a localized message when invalid.

v.required() and v.matchRegex("^LIC-[0-9]+$")

In a field-validation context, the current field value is supplied automatically when the first argument is omitted. Test a valid reference, an empty reference, and a value with the wrong prefix.

Build a document sentence with a fallback

Use a template string to construct readable text without exposing missing data.

`Request {{ $.serial_id }} is assigned to {{ $.owner.name || "the service team" }}`

Keep the data itself in fields. The template is for presentation, not the source of truth.

Make expressions maintainable

Name fields for their business meaning, not for a temporary screen label.
Prefer one short expression per decision over a long expression that combines unrelated policy.
Use parentheses around mixed arithmetic and comparisons.
Treat null, empty text, and empty lists as expected states.
Keep rule text and the user-facing field description aligned. If the policy changes, update both.
Test with a non-production record after changing a field key, option value, relation, or template context.

Diagnose a result before changing the expression

Symptom	Check first
Blank calculated value	Is the source field present in this expression context?
Unexpected text or `NaN`	Is a number being read as text or an empty value?
Condition never shows	Does the controlled option use the exact stored value?
Validation never appears	Is the rule configured as validation and returning `true` or an error result?
Template hides a name	Does the relation expose the property in this context, and is a fallback intended?

Next steps

Read the complete expression language syntax.
Browse all registered helpers, each with a signature and example.
Use Entity fields and layouts to choose the right source data before writing a rule.

​Use expressions to make a rule visible

​Choose the right place for the rule

​Build a calculated field step by step

​1. Define the result in plain language

​2. Confirm the source fields

​3. Write the smallest expression

​4. Test normal and exceptional records

​Four practical patterns

​Calculate a numeric result

​Show a conditional section

​Validate a reference before saving

​Build a document sentence with a fallback

​Make expressions maintainable

​Diagnose a result before changing the expression

​Next steps