Calculated fields - KayanOS Documentation

A calculated field stores a value that KayanOS derives from other data instead of asking a person to type it repeatedly. It can express an amount, score, flag, label fragment, relationship count, or other result that follows an approved rule. The result stays on the record so it can be reviewed, filtered, reported on, and used by later steps without redoing the calculation by hand. Calculated field is not a separate item in the entity field-type list. It is a normal, non-action, non-status field with a non-empty calculation_code expression. Choose the output field type to match the result: use Number for an amount or count, Boolean for a clear true/false result, Text for a short displayed value, and so on. A serial reference should use its dedicated serial configuration rather than a calculation that imitates issuance. The captured builder view below shows the Estimated Fee number field on the Citizen Service Request entity with its calculation expression. It is an example of selecting the ordinary output type first, then attaching the calculation rule to that field. KayanOS calculated Estimated Fee field configuration for the Citizen Service Request entity.

KayanOS calculated Estimated Fee field configuration for the Citizen Service Request entity.

When to use it

Use a calculated field when the result is deterministic from data that the record already holds or is configured to resolve. Good candidates include a service fee from an amount and rate, a completeness flag from structured intake data, an inspection count, an elapsed-workload score, or a reporting category derived from approved inputs. Use a different mechanism when the work needs judgment, authority, or an external event:

Need	Better approach	Why
A reviewer must decide an outcome	Status, action, and accountable review fields	A formula cannot stand in for a decision.
A user must enter an explanation	A normal editable field	A calculation should not erase or guess human narrative.
An issued public number	Serial ID	Issuance has a sequence, collision protection, and change history.
A rule that should block bad input	Field validation	A calculated result can show a problem, but validation controls acceptance.
A value from an unrelated service	An approved integration or action	A calculation only sees the context supplied to it.

Keep inputs visible and named for their business meaning. A field named requested_amount and another named fee_rate make the rule reviewable; one opaque JSON payload does not. Do not make people enter a value that the calculation immediately overwrites. If the source data is incomplete, decide whether the result should be null, whether a validation should stop the record, or whether a human must provide a separate decision.

Configuration

Choose the output field, then add its calculation expression in the entity builder. The calculation editor validates the expression against the context it provides and shows an error or warning state while you work. That check is useful for misspelled keys and invalid syntax, but it is not proof that live relationship data, permissions, or a later background refresh will behave as expected. Save and test a real non-production record.

Context and output behavior

The evaluation context depends on the execution path. Do not assume that a name available while a record is created or updated is also available to the background refresh. The two paths have deliberately different data:

Context value	Create/update validation and persistence	Background `calculate_entity_fields` refresh
`$`	A copy of the record data with only the output field currently being evaluated removed. Other calculated outputs can therefore be present during that synchronous operation.	A copy of stored record data with all calculated-field keys removed. A background formula must derive its result from source data rather than another calculated output.
`$value`	The current value of the output field at the time that field is evaluated. Use it only when a prior value is part of the approved rule.	Not supplied.
`$relations`	Direct relation data only when the surrounding create/update flow has resolved it. A single relation is an object or `null`; an array relation is an array of objects.	Direct relation data only for relationship fields configured for calculated-field refresh.
`$inverseRelations`	Always an empty object; synchronous calculation does not receive inverse-record collections.	Configured inverse relationship collections, represented as arrays under the inverse entity and field keys.
`$statusTemplates`	Server-supplied status-template context where the relevant configuration applies.	Not supplied.

In the synchronous path, KayanOS may make up to one pass per calculated field and stops when a pass makes no change. The expression result is compared with the current value; when it differs and is defined, the updated value is placed into the record data used by that create/update flow. A result of undefined, or an evaluation error, is skipped rather than written as a new value. The background job takes a different approach: it evaluates each calculated field once from its source-only context, then writes changed results together. That makes defensive null handling important: a silent blank may be safer than a wrong amount, but it can leave an earlier result in place until the source data is corrected. Start with a local calculation that has no relationship dependency:

$.requested_amount * $.fee_rate

With requested_amount equal to 250000 and fee_rate equal to 0.03, the expected Number result is 7500. Both source fields should be Number fields. If a rate is optional, explicitly choose a fallback rather than accidentally multiplying text, null, or a missing value.

Direct relations and inverse relations

A direct-relation formula only sees $relations in a normal create or update when the surrounding validation has resolved that relation context. The background job resolves only the direct relationship fields configured for calculated-field refresh. For a single relation such as service_category, $relations.service_category is either the related record object or null. For an array relation, the same key resolves to an array. Protect a relation access with a guard:

$relations.service_category && $relations.service_category.fee_rate != null
  ? $.requested_amount * $relations.service_category.fee_rate
  : null

With a related category rate of 0.03 and requested amount 250000, the expected result is 7500; without a category or rate, the expected result is null. Use the stored field keys of the related entity, not labels shown to staff. Inverse relations answer a different question: which other records point back to this record? They are background-path data, not a guaranteed synchronous context: during normal create and update, $inverseRelations is empty. Configure the inverse relationship on the entity before using it, then use the expression only where the configured background refresh is part of the design. In that background path, the values are arrays under the inverse entity key and its relation field key. Use the registered length(...) helper to count the array:

length($inverseRelations.inspections.request_reference)

If three inspection records point to the current request through request_reference, the expected Number result is 3 after the configured background recalculation. The keys inspections and request_reference in this example must match the configured inverse entity and field keys exactly. Do not write an aggregate against an inverse path until you have verified the saved configuration and refreshed parent record. There are two important timing paths. During create and ordinary update, KayanOS evaluates local data, any resolved direct relations, $value, and applicable status-template context; it has no inverse-record collection. The background calculate_entity_fields job reads configured direct and inverse relations, omits $value and $statusTemplates, recomputes each output once from source data, and logs evaluation errors. A rule that relies on inverse records should be verified after the background recalculation; do not assume that adding a child record instantly refreshes the parent’s inverse count in every path.

Dependencies, cycles, and status context

A short calculated-on-calculated chain can appear to settle during one synchronous create or update: that path may make repeated passes, bounded by the number of calculated fields. It is not a production-safe dependency contract. The background refresh removes every calculated output from $, makes one pass, and can later overwrite values from source data alone. Build durable policy from approved source fields instead of relying on one calculated result being available to another. Do not create circular rules such as a depending on b while b depends on a, or formulas that keep changing their own inputs. Status-template information can be supplied by the server during the synchronous path when a field uses the relevant status-template configuration. It is not supplied to the background job. Treat it as contextual data, not as an authorization shortcut; if a rule depends on a status template, test the exact template selection, record state, and refresh behavior that will be used at runtime.

Client projection is not the calculation authority

KayanOS can omit calculated values and calculated table-column metadata from client payloads, then recompute authoritative outputs on trusted server paths. This prevents a stale or user-modified client projection from becoming the source of a saved calculated result. It also means a calculated value that is absent from the browser payload is not necessarily missing from the record’s server-side calculation contract. Do not use a hidden calculated value for client-side authorization, page visibility that must be enforced securely, or approval evidence. Base those decisions on permitted source fields and server-validated workflow state. When a calculated table result matters to a document or decision, verify the saved or recomputed server value and the inputs that produced it rather than copying a value from browser state.

Worked example

A public-service directorate in Syria manages citizen requests for a local service. Each request includes requested_amount, fee_rate, a relation to service_category, and related inspection records. The service owner wants staff to see the estimated fee, a review flag, and the number of completed inspection records without retyping any result. Create these output fields:

Output field	Type	Calculation purpose
`estimated_fee`	Number	Amount multiplied by the applicable rate.
`needs_fee_review`	Boolean	Signals that the estimated fee reaches an agreed review threshold.
`inspection_count`	Number	Shows the configured inverse inspection count after background recalculation.

For the first version, keep the rate directly on the request and use a simple calculation:

$.requested_amount * $.fee_rate

For a request with requested_amount of 250000 and fee_rate of 0.03, estimated_fee becomes 7500. Place the result beside the source amount in the review layout, and keep both inputs visible so a reviewer can explain the number. Then define a clear Boolean threshold directly from the same source values:

$.requested_amount * $.fee_rate >= 10000

For the example above, needs_fee_review is false; when the amount and rate produce a fee of 12500, it is true. This is deliberately not $.estimated_fee >= 10000: a synchronously calculated estimated_fee can be visible during one validation pass, but the background path removes calculated outputs before it evaluates the threshold. Configure the business process so a true flag leads to a visible review task or status step. The field itself does not assign a reviewer or grant approval. If fee policy is stored on the related service_category record, replace the first formula with the guarded direct-relation form from the Configuration section. Test a request with no category, a category with no rate, and a category with a valid Number rate. If the relationship changes later, run the relevant recalculation check and verify the stored fee before producing a decision document. Finally, configure the inverse inspections.request_reference relationship only if the directorate needs the stored count for dashboards or reporting. Create one request, attach three inspection records, run or wait for the configured background recalculation, and confirm inspection_count is 3. A count is operational information; it is not proof that each inspection was accepted. Keep the inspection result and decision status in their own controlled fields.

Testing

Test calculations with a small non-production set that includes normal, empty, changed, and relationship cases. Write down both source values and expected stored results. Test a saved record, not only the editor indicator, because the editor can validate syntax while live data has a different relationship shape or missing value.

Test	Setup	Expected result
Local arithmetic	Known Number inputs	The stored output equals the independently calculated amount.
Missing input	Remove one optional source value	The formula returns the approved fallback such as `null`; it does not create a misleading number.
Direct relation	Use a valid related record, then remove it	The guard produces the related result when present and the fallback when absent.
Inverse count	Add and remove related child records	The background-recalculated output matches the configured array length.
Background-safe threshold	Change `requested_amount` or `fee_rate`, then run or wait for refresh	The flag equals the direct source expression in both paths; it does not require another calculated output.
Synchronous dependency experiment	Change a source for two calculated fields in one ordinary update	A short chain can settle within bounded synchronous passes, but it is not accepted as proof that a background refresh will preserve the chain.
Output editing	Try to supply a conflicting value for the output in a normal create or update	That synchronous calculation uses its evaluated result; verify the eventual stored value again after any background refresh.
Error handling	Temporarily use an invalid key or incompatible data	The editor flags the issue or evaluation is skipped; background logs identify the failed field.
Access review	Test with a restricted role	The layout and calculation do not expose a sensitive source through a derived value.

Use a conservative relation test expression before adding arithmetic:

$relations.service_category ? $relations.service_category.fee_rate : null

With a related category whose fee_rate is 0.03, the expected result is 0.03; with no related category, it is null. After this succeeds, add multiplication and threshold logic one expression at a time. For an inverse count, test the exact saved configuration rather than guessing the entity or field key from its screen title.

Troubleshooting

Symptom	Check first	Safe response
The calculated value is blank	Is a source key missing, is the result `undefined`, or did a guard intentionally return `null`?	Inspect a saved test record and make the intended fallback explicit.
The editor shows an error	Does the expression use the supplied context and valid JEXL syntax?	Start with one source path, verify it, then add operators and guards.
A relation value is missing	Is the field a direct relation, is it configured as one value or an array, and is that path resolving it?	Use the correct `$relations` shape and guard `null` or empty arrays.
An inverse count is blank or stale	Has the inverse relationship been configured, and has the background recalculation completed?	Do not expect an inverse count during synchronous create/update; run or wait for background recalculation and verify the stored parent record.
A result does not change	Did the source value actually persist, or is the expression returning the same JSON-equivalent value?	Check the saved source fields and field keys before changing the formula.
A dependency gives different values after refresh	Does the expression read another calculated field, `$value`, or `$statusTemplates`?	Rewrite the durable rule from source fields, then test the background result.
A calculation loops or gives unstable values	Do calculated fields depend on one another in a cycle during synchronous passes?	Remove the cycle and make the durable calculation read source data only.
A background job reports an error	Are a relation path, field key, or source type wrong?	Correct the data or expression, then rerun the calculation and inspect the stored result.

Permissions and data-quality limits

Only people with appropriate builder access should configure calculation code, relation definitions, and layouts. Members who create or update a record still need the normal entity permissions; a calculated field does not bypass field visibility, record scope, or update authorization. Treat a value produced in one synchronous pass as a result for that operation, not as a permission-approved guarantee that another calculated field will persist it after background refresh. Test with representative roles, especially where a result could reveal a restricted amount, person, category, or inspection outcome. Derived data can leak source data. For example, a Boolean flag can reveal whether a confidential threshold was exceeded, and a count can reveal that related records exist. Do not expose a calculated field in a public or broad staff layout until the service owner has reviewed both the source fields and what the derived result reveals. Do not put secrets, tokens, or personal identifiers into expression text or output values. Keep the formula small enough for a policy owner to read. Pair every meaningful calculation with a field description that says what it represents, its unit, its fallback for missing data, and the action staff should take when it is unusual. Calculations increase consistency; they do not validate an untrustworthy source, replace approval, guarantee a timely inverse refresh, or preserve a calculated-on-calculated dependency across a background pass.

Select suitable output and source field types in Entity fields and layouts.
Learn complete expression syntax and helper behavior in Expression language syntax.
Design direct and inverse relationships in Entities.
Use issued, auditable human references in Serial IDs.

​When to use it

​Configuration

​Context and output behavior

​Direct relations and inverse relations

​Dependencies, cycles, and status context

​Client projection is not the calculation authority

​Worked example

​Testing

​Troubleshooting

​Permissions and data-quality limits

​Related guides