CSR-2026-00042. It is different from the internal record ID and from a reference supplied by another system. A good serial rule makes a request easy to find, quote on a letter, and trace during review without asking staff to invent numbers.
This guide explains the serial_id entity field. It covers the number itself, its sequence namespace, the expression that renders it, the limited ways a value can be assigned or changed, and the checks that collision-protect active issued values while retaining change history. Use stable field keys in every expression; a translated field title is not an expression key.
The captured builder view below shows a real Serial ID configuration for the Citizen Service Request entity, including automatic generation, the manual-entry policy, namespace and format expressions, the starting value, and timezone.
When to use it
Use a serial ID when a record needs one durable reference that people can safely repeat across a workflow. Typical examples are a citizen-service request reference, permit number, inspection reference, maintenance ticket, decision number, or outgoing-letter number. Put the serial near the top of the record layout and use it in search, documents, notifications, and staff conversations. Choose another field when the value has a different job:
Start with one serial field for one business identity. Do not reuse a single field for both an intake reference and a final certificate number unless those numbers are genuinely the same throughout the lifecycle. If a later decision needs its own legal or document reference, model it separately and relate the records.
The service keeps each issued value as an issue record. A retry of the same allocation uses an idempotency key. The counter is keyed by organization and namespace, and the active-issue constraint collision-protects a rendered value against another active issue in that same organization and namespace. A stored sequence value has a separate constraint in the same scope. This protects a live allocation from a race or repeated request; it is not a reason to make the visible format ambiguous. When an explicit change supersedes an issue, its old rendered value remains in history but no longer occupies the active rendered-value constraint, so storage can permit that historical text to be used again. Consult the issue history for traceability, and adopt a human no-reuse policy whenever a service must forbid that outcome.
Configuration
In the entity builder, add a field whose type is Serial ID, save the entity and field, then configure its serial settings. A serial configuration has six decisions: generation mode, manual-entry policy, namespace expression, format expression, start number, and timezone. Test the configuration before making the field part of a public-facing form or document.Generation mode
The hybrid mode is not a promise that a user will be asked to choose a method each time. In the usual create flow, a blank value is allocated because the configuration includes automatic generation. The on-request operation does not issue a second value for an already assigned field.
Manual entry and later changes
The manual-entry policy is intentionally narrow:
Neither policy makes an assigned serial freely editable. A normal update that tries to replace or clear an existing serial is rejected. A deliberate replacement uses the explicit serial-change operation, requires an authorized update operation, and is unavailable when the field is fixed. That operation creates a new issue record, marks the prior issue as superseded, and can retain the reason and the acting member. The superseded value remains traceable in history, but it is no longer a permanent rendered-value lock in storage. Treat the operation as an exceptional correction process with an accountable reason and a documented reuse policy, not as a convenience edit.
Namespace and format expressions
The namespace determines which records share a counter and an active-rendered-value collision scope. Its default is the organization, entity key, and field key together:org-1, entity citizen_service_requests, and field request_reference, that resolves to org-1:citizen_service_requests:request_reference. The organization and namespace identify one counter. The database prevents a rendered value held by one current, non-superseded issue from being assigned to another current issue in that scope; it separately prevents reuse of a stored sequence value there. This is not a permanent global registry of rendered text: after an explicit change supersedes an issue, the historical rendered text can be reused by storage. Keep the default when each entity field needs its own numbering stream. Use a shared namespace only when several fields intentionally draw from one controlled series, review every format for collisions between active issues, and consult issue history before treating a visible reference as historically unique.
The format expression turns the next sequence into the visible reference. The default format is $sequence. A readable public-service format can be:
42 in 2026, the expected result is CSR-2026-00042. serialPad(value, width, char?) pads the left side with 0 unless a different single padding character is supplied. serialDate(format, value?, timezone?) formats a date using yyyy, yy, MM, and dd; its second argument is the value to format and its third argument is the timezone. Use the exact argument order shown above.
Both expressions are evaluated in a record-aware context:
Do not put a citizen name, national identifier, contact detail, password, or access token in a serial expression. The reference may appear in exports, documents, and conversations. Also avoid a format that omits
$sequence unless the remaining values distinguish every concurrently active allocation; otherwise a rendered collision with an active issue is retried and can ultimately fail rather than silently replacing that issue.
Start number, timezone, preview, and prefill
Start at is the first positive sequence value for a new namespace. Use it when an approved paper register already starts at a known number, but do not lower it after issuing live references. Invalid or non-positive input is normalized to a safe positive start, so enter and review the intended value explicitly. Timezone chooses either the organization’s default timezone or UTC for$timezone. It matters when the format includes a date at a local-day boundary. Choose organization time for an office’s operating day; choose UTC only when one global date convention is required. Change it carefully: the same instant can produce a different date prefix in a different timezone.
Use the serial preview before issuing a record. It resolves the expressions and shows the next candidate, but it is non-binding: it does not advance the counter or reserve the value. A later real allocation can therefore differ if another record is issued first.
For existing records with no value, use the bulk-prefill control only after saving both the entity and the field. Filter the candidate set, inspect the preview count and samples, then start the background job. The operation is intended for blank serial fields; it leaves records that have been assigned a value alone. Keep the filter narrow for the first run and verify the job outcome before widening it.
Worked example
A public-service directorate in Syria receives citizen requests for a local service. Intake officers need a reference that is readable over the phone, appears on an acknowledgement document, and remains stable while the request is assigned, inspected, and decided. The entity iscitizen_service_requests; the serial field key is request_reference.
Configure the field as follows:
Save the configuration, then create a request with the serial left blank. The create flow allocates the next number and stores it with the request. If the next sequence is 42 at a 2026 local time, the expression below produces the value staff will see:
CSR-2026-00042. The acknowledgement template should use the stored request_reference, not re-evaluate the serial expression. An inspection record can relate to the request and display this reference; it should not copy the serial into a second editable text field.
If the directorate needs a later-issued certificate reference, create a separate certificate entity or serial field. For a review-first process, use request mode instead: leave the serial blank at intake, allow the authorized reviewer’s update operation to generate it after acceptance, and test that a second request returns the already assigned value rather than a new one.
For a controlled legacy migration, set manual entry to blank_only, filter only the records whose request_reference is blank, and give each imported legacy value its own initial assignment. Do not attempt to change assigned values through normal updates. If a correction is legally approved, use the explicit change flow, include a reason such as “paper register transcription correction,” and retain the old and new issue history for audit review.
Testing
Test the configuration with a non-production workspace and a small, named set of records. Record each expected value before running the test so a reviewer can distinguish a correct result from an accidental one.
Test the format expression independently with known data. For example, use a five-digit width and a known sequence to make the expected padding unambiguous:
$sequence equal to 7, the expected result is CSR-00007. Then test a namespace expression that deliberately uses a record value only if a separate sequence per category is policy, not an accident:
service_category value. Test an empty or changed category before relying on it, and prefer the default namespace when there is no approved reason to split the sequence.
Troubleshooting
Permissions and data-quality limits
Building or bulk-prefilling a serial field requires field-management access. Previewing a serial requires permission to create or update the relevant entity. Request generation and explicit replacement require an authorized update operation on the specific record; scoped access can prevent an otherwise authorized member from editing that record. A fixed serial field cannot use the explicit replacement path. Permissions protect the operation, not the quality of the policy. Before publishing, have the service owner approve the prefix, year behavior, start number, namespace boundary, and correction reason. Keep the serial field read-only in layouts where staff should not supply it. Preserve external references in a separate field, and never treat an attractive serial format as evidence that the underlying request was approved. The issue history records how a value was created—generated, manual, bulk-prefilled, or changed—and links a replacement to the superseded issue. Review the full history, not only the current field value, during corrections and migration reconciliation. A superseded issue keeps its historical rendered text, but that text no longer blocks a new active issue at the storage layer. If historical text must never be reused, make that an explicit human operating policy and enforce it in review. History supports accountability, but it does not replace record-level permissions, document retention controls, or an approved operating policy.Related guides
- Choose the field and layout around the reference in Entity fields and layouts.
- Model the request, inspection, and decision as connected records in Entities.
- Learn expression syntax, operators, and helper behavior in Expression language syntax.
- Use derived amounts, flags, and summaries in Calculated fields.