Mnemonic

A Mnemonic defines how tSM generates readable business identifiers (keys/codes) for your entities.
While every record has a technical UUID (id), users and integrations often need meaningful identifiers such as TCK-2025-00456 or ORD-EU-00123.

Where it’s used

• Business data (e.g., Ticket, Order, Account): generates a Key
• Registers / code tables (e.g., SLA type, Process type): generates a Code
• Many public APIs accept both UUID id and business key/code in URLs for CRUD

---

Concept & Capabilities

A Mnemonic is a configurable pattern that combines:

• Constants — prefixes/suffixes ("TCK-", "ORD-")
• Dynamic variables — entity fields, user/org context, date parts
• Sequences — auto-incremented numbers with optional restart periods (yearly, monthly, …) and padding

Examples:

Entity	Pattern (conceptual)	Example result
Ticket	TCK_${yyyy}_${sequence(4)}	TCK_2025_0456
Order	ORD_${region}_${sequence(5)}	ORD_EU_01234
Customer Account	ACC_${type}_${yyyyMM}_${sequence(3)}	ACC_BUS_202501_007

The generation is unique within scope (global, per type, per region, etc., depending on your SpEL and sequence configuration).

---

How it works (high level)

1. You define a Mnemonic configuration with a SpEL expression in spel.
2. When a record needs a business key/code, the engine evaluates the expression, reading runtime data and consuming a sequence.
3. The computed value is stored on the entity (e.g., Ticket.key, or a register code) and used in UI and APIs.

SpEL anatomy (examples)

#date.format('yyyy') + '-' + #sequence.next('TICKET-YEARLY', 4)

#root.customer?.region + '-' + #sequence.next('ORDER-PER-REGION:' + #root.customer?.region, 5)

'TCK-' + #date.format('yyyyMM') + '-' + #sequence.next('TCK-' + #date.format('yyyyMM'), 4)

• #root … the current entity/context payload (fields you pass during generation)
• #date … helper for formatting current time
• #sequence.next(name, pad) … obtains the next number for a named sequence, left-padded to pad digits (restart behavior is controlled by restartPeriod in the mnemonic config; see below)

Exact helper names in your environment may vary—keep the intent: combine context + formatted date/time + a sequence.

---

Typical flows

• On create: generate a business key automatically before save, using entity data (type, priority, region…).
• Bulk imports: pre-generate or generate-on-insert to keep sequential order and avoid collisions.
• Scoped sequences: reset numbering per month/year, or per region/customer, by including scope in the sequence name.

---

Reference

MnemonicConfig (attributes)

Field	Type	Required	Read-only	Description / Notes
id	UUID	–	–	Identifier (not for end-user display).
code	String	Yes	–	Unique ASCII code (no spaces). Stable key used by tools/processes.
name	String	Yes	–	Human-readable name.
description	String	–	–	Longer help text/tool-tip.
validityFrom/To	Date	–	–	Active window for this mnemonic config.
valid	Bool	–	Yes	Computed from validity; not stored.
spel	String	Yes	–	SpEL expression that builds the final identifier (may reference date/time, payload fields, and sequences).
configType	String	–	–	Links to a ConfigType (grouping for backup/restore, Studio filters).
restartPeriod	Enum	–	–	Sequence restart policy: PERPETUAL, YEARLY, MONTHLY, DAILY.
sequenceName	String	–	–	Optional DB sequence name override (if your deployment uses a DB-backed sequence).
dataTags	List	–	–	Labels for dashboards/filters (e.g., ticketing, ops).
config	Map	–	–	Free-form metadata used by admin tooling.
localizationData	Object	–	–	Translations for name / description.
auditInfo	Object	–	–	Standard audit metadata.

restartPeriod

• PERPETUAL – sequence never resets
• YEARLY – resets each calendar year
• MONTHLY – resets each calendar month
• DAILY – resets each calendar day

---

Example configurations

Yearly ticket sequence with prefix and zero-padding

'TCK-' + #date.format('yyyy') + '-' + #sequence.next('TCK-YEARLY', 4)

Region-scoped order sequence

'ORD-' + #root.region + '-' + #sequence.next('ORD:' + #root.region, 5)

Customer-type + month scope

'ACC-' + #root.customerType + '-' + #date.format('yyyyMM') + '-' + #sequence.next('ACC:' + #root.customerType + ':' + #date.format('yyyyMM'), 3)

Pass the fields you need (e.g., region, customerType) in the generation payload so the expression can use them.

---

Good Practices

• Keep code stable — referenced by processes and admin tools.
• Design for uniqueness — include enough scope in the sequence name to avoid collisions (e.g., year/month/region).
• Human-first — prefer short, readable keys; keep noisy data out of the prefix.
• Reset wisely — use restartPeriod to match business expectations (monthly orders vs. perpetual account numbers).
• Idempotency — guard against duplicate generation on retries (generate once per record and persist atomically).
• APIs — expose both UUID and business key/code where practical to simplify integrations and user operations.

---

See Also

• System Settings: ConfigType — organize mnemonic configs for promotion and tooling
• System Settings: EntityType — where keys/codes are ultimately used and exposed in UI/API
• Backup / Restorer, tSM Studio — tools that rely on consistent grouping and stable codes