Skip to main content

​
Use numbering expressions for identity, not policy

Serial and form-number expressions format a number that has already been allocated by KayanOS. They are appropriate for readable references such as CSR-2026-00042; they are not a replacement for a status, permission, approval, or audit decision. The two reserved helpers are documented in Serial and form-number helpers. Do not assume either helper is available in a regular calculated field. KayanOS Serial ID field configuration for the Citizen Service Request, showing namespace, format, and sequence settings.

​
Entity serial ID context

Namespace expressions receive: Format expressions add $namespace and $sequence; $sequence is a string. A namespace determines which sequence is incremented, while a format determines how the allocated sequence is displayed.

​
Form-numbering context

Form numbering uses a different root model. It provides $, $record, $savedState, $variables, $fields, $organizationId, $formId, $formVersionId, $sessionId, $codePrefix, $profile, $status, $initiatorId, $initiatorType, $publicUserId, $preview, $timezone, and $now. Format expressions add $namespace and $sequence.
Do not copy an entity serial expression into form numbering without changing its roots. For example, form numbering has $formId; an entity serial has $entityKey and $fieldKey.

​
The two helpers

serialDate understands only yyyy, yy, MM, and dd. It is intentionally different from general dateFormat, which uses uppercase YYYY, DD, and other tokens. An invalid date returns an empty string, so test the final rendered reference rather than only the individual helper.

​
Deterministic design rules

  • Keep namespaces stable. Changing a namespace changes the sequence stream.
  • Use $sequence, $namespace, stable scope keys, and the configured clock. Do not use random, shuffle, sample, or a record field that can change after allocation.
  • Use a readable, bounded format. Long display values are harder to use on forms, printed acknowledgements, and support calls.
  • Test the first value, a value after padding width, a year boundary, and any allowed manual/request mode.
  • Treat a rendered serial as a traceable reference; do not modify it merely to make a screen look nicer.

​
Common patterns

Use the category pattern only when service policy explicitly accepts a separate sequence per stored category value. A renamed label is not a stable category value.

​
Troubleshooting