Menu Item

A Menu Item defines an entry in the tSM navigation (left menu, personal bookmarks, self-care portal).
Admins compose the information architecture by arranging items into a tree, setting visibility and privileges, and routing each item to a screen or listing.

What it’s for

• Main navigation — domain sections like Ticketing, CRM, DMS.
• Deep links — direct access to filtered listings or dashboards.
• Personalization — user-level bookmarks/favorites.
• Self-care — separate navigation for customer/partner portals.

Menu items support localization, validity windows, role-based visibility, and ordering to deliver a consistent navigation experience across modules.

---

Typical Uses

• Build a Ticketing section with children: All Tickets, My Queue, SLAs, Reports.
• Provide shortcuts for power users (e.g., “My Open Orders”, “Approvals”).
• Expose Self-care entries separate from internal UI.
• Hide WIP features via validity or feature flag stored in config/dataTags.
• Mirror Modules with top-level nodes; place related screens underneath.

---

Routing & Display

• routerLink — front-end route the item opens (preferred).
• url — backend endpoint associated with the screen/listing (optional; useful for tooling and deep link generators).
• icon — icon identifier used in UI.
• parentId — builds the menu tree (item becomes a child of the parent).

Visibility is governed by privilege (role/permission), visible flag, and validity; order is defined by sortOrder.

---

Reference

Menu Item (attributes)

Field	Type	Required	Read-only	Description / Notes
id	UUID	–	–	Identifier (not intended for end-user display).
code	String	Yes	–	Unique ASCII code (no spaces). Stable key referenced by UI/admin tools.
name	String	Yes	–	Label shown to users (localized via localizationData).
description	String	–	–	Tooltip/longer help text.
validityFrom/To	Date	–	–	Active window for the item.
valid	Bool	–	Yes	Computed from validity; not stored.
routerLink	String	–	–	Front-end route to open (preferred for navigation).
url	String	–	–	Backend URL associated with the screen/listing; helps deep-link tooling and integrations.
icon	String	–	–	Icon identifier used in UI.
parentId	UUID	–	–	Parent menu item (self.id); defines hierarchy.
type	Enum	–	–	MENU, BOOKMARK, or SELFCARE.
sortOrder	Long	Yes	–	Display order among siblings (lower first).
privilege	String	–	–	Permission/role required to see the item.
visible	Bool	–	–	Explicit show/hide flag (in addition to privilege/validity).
useDefaultSetting	Bool	–	–	If true, UI may apply default behavior (e.g., inherited filters/layout) for this item.
userId	UUID	–	–	When set, the item is user-specific (e.g., personal bookmark).
config	Map	–	–	Free-form admin/UI metadata (e.g., default filters, feature flags).
dataTags	List	–	–	Labels for grouping/reporting (e.g., core, pilot, selfcare).
localizationData	Object	–	–	Translations for name/description.
auditInfo	Object	–	–	Standard audit metadata.

type values

• MENU — standard navigation item (can have children).
• BOOKMARK — user or team favorite (often with userId).
• SELFCARE — item intended for customer/partner portal navigation.

---

Good Practices

• Prefer routerLink for consistent client-side routing; keep url as informational/auxiliary.
• Stable code — treat it as immutable; referenced by imports, scripts, and admin tools.
• Order & hierarchy — use sortOrder and parentId to build predictable trees; avoid excessive nesting.
• Guard with privilege — hide sensitive areas; combine with visible=false for staged rollouts.
• Use dataTags to flag bundles (e.g., pilot) for environment-specific toggles.
• Localize early — populate localizationData to keep navigation consistent across languages.
• Keep config lean — store only UI hints (filters, default views); business rules live in forms/processes.

---

See Also

• System Settings: Module — business-domain grouping behind navigation sections
• System Settings: EntityType — types that many menu screens refer to
• System Settings: Microservice — backends that power the routed screens