When Should a Document Platform Generate Business Numbers?
Issue readable references while keeping document identity and business authority clear
Published
A case team needs a reference it can put on correspondence, quote in an email, and find in a report. Let the document platform issue that number when it owns the registration workflow. If another case system or an external registry already issues the authoritative number, carry that reference into the document record and keep one issuing authority.
A readable number such as CASE-2026-00001 is useful to people. A stable document ID keeps applications connected to the managed document. Both belong in the design, alongside an explicit decision about when the business number becomes official.
FormKiQ v1.19.1 introduced site-scoped numbering sequences for unique string attribute values with configurable patterns. Packaged Business Solutions deliver contract, case, and permit workflows; their configured issuance rules can align readable references with the right business milestone. The sequence capability and the commercial application's workflow scope are separate parts of that configuration.
Choose the issuing authority first
Issue the reference in the document workflow
A contract or case application can coordinate numbering with the point at which a record is opened, approved, or registered. Configure the sequence and the issuance step together, so staff know what receiving a number means.
Preserve its authoritative reference
When an ERP, licensing register, or case system assigns the official number, store that value with the associated FormKiQ document ID and site. Keep any internal document reference clearly distinct from the external number.
Choose the record being numbered too. One case may have an intake form, evidence, correspondence, and several document versions. Decide which share the case number and which need their own reference; allocating a new case number for every file upload can make the business register harder to follow.
Keep the business number separate from document identity
Store the issued number as a string attribute, preserving prefixes and leading zeroes. Keep the documentId, siteId, and any external business-record ID in the integration mapping. The number can appear in correspondence and reports without becoming the database key or a value every integration must parse.
Folder location, a department name, and a customer's trading name can change while the managed record stays the same. Our guide to document IDs and folder moves explains that distinction. Use explicit attributes for current ownership, confidentiality, and business relationships instead of encoding mutable details into the issued reference.
Decide when to issue the number
There is no single best milestone for every workflow. The right choice depends on what staff and external recipients should infer from an issued number. Make draft and official references visually distinct when they represent different states.
| Issuance point | Meaning and operational consequence |
|---|---|
| Draft creation | A reference is available for early discussion. The register needs to explain abandoned drafts and cancelled numbers. |
| Approval | The number identifies an approved record. Drafts use a separate reference until the required decision is recorded. |
| External acceptance | The reference follows an authoritative registration outcome. Track submissions and reconcile the returned number with the correct record. |
Configure scope, format, and the year boundary
FormKiQ's sequence configuration is scoped to a site and attribute key. It provides a pattern, starting value, minimum numeric padding, reset choice, and time zone. Supported reset choices are NONE and YEARLY; the time zone defaults to UTC.
Set the year token, reset policy, and IANA time zone explicitly. A displayed year alone is not an annual reset policy. Choose a namespace that distinguishes references across sites when needed.
A yearly case register
Use the case-management site, a caseNumber attribute, pattern CASE-{YEAR}-{SEQUENCE}, starting value 1, padding 5, reset YEARLY, and time zone Europe/London. The first number for 2026 is CASE-2026-00001. Verify the transition to CASE-2027-00001 at the configured year boundary before using this policy in production.
Worked example: one case number through registration and withdrawal
A service team uses FormKiQ's Case Management Business Solution to manage a missed-visit complaint. In this illustrative configuration, staff confirm the intake before registering the case and use DRAFT-1042 during that check.
- Check intake
Use the draft reference
The complaint, appointment confirmation, and intake decisions stay connected to the same record while staff discuss DRAFT-1042.
- Register
Record the issued number
The configured issuance step associates CASE-2026-00001 with the accepted case record and its document references.
- Retain
Explain the final outcome
If the complainant withdraws the case, retain its issued number and withdrawal outcome under the team's register policy.
If a connected service system's acknowledgement times out, the integration checks the number already stored on that case before retrying the handoff. It does not request a fresh business number merely because the receiving system did not respond. Later evidence and revised files keep their own document identities while remaining associated with the same case reference.
Account for gaps, retries, and imports
Separate allocation from completion of the wider business process. An issued number may belong to a cancelled transaction or a record whose downstream handoff failed. Agree how the register represents those outcomes, and preserve their history rather than silently recycling numbers to make the list look continuous.
The sequence-details API reports the current period, latest sequence, and last generated value. These describe shared sequence state. They are not a receipt for a particular case: another user may have received a number since your request. Correlate retries with the business record and inspect its stored outcome.
For migration, preserve authoritative legacy numbers and reconcile existing prefixes, leading zeroes, and duplicates before selecting the new namespace or cutover range. A manually imported value is not evidence that a sequence has advanced to match it. Test imports and configuration changes against the existing register, keeping legacy references available for lookup.
A practical numbering checklist
- Name the issuing authority, the record being numbered, and the milestone that makes the reference official.
- Record the site, attribute key, pattern, starting value, padding, reset policy, and time zone.
- Test concurrent issuance and the configured year boundary, including references used across sites.
- Reconcile a timed-out handoff using the business record; confirm that retry does not issue another reference.
- Show cancelled, void, and failed outcomes according to the agreed register policy.
- Check imported numbers and keep stable document IDs and site context in every integration.
Make the reference explain the business event
Generate business numbers where the issuing authority and registration workflow belong. A clear scope, issuance milestone, and outcome history make those references useful to staff and external systems. Stable document IDs continue to identify the underlying managed documents as names, folders, and workflow states change.
Technical guidance reviewed: November 12, 2026, against FormKiQ v1.19.1 release notes and the numbering-sequence configuration and retrieval references linked above.