EntityType

EntityType is the canonical classification of a record in tSM (e.g., Customer, Ticket, Order, Attachment).
Together with an entity’s ID, it forms a universal reference used by UIs, processes, integrations, and cross-module links.

Business value:

• Consistent behavior — drives which forms, characteristics, rules, and widgets apply to a record.
• Cross-module linking — powers generic relationships like ownerType / refType (e.g., an Attachment with ownerType="Ticket").
• Discoverability & routing — ties an entity to its microservice and public API.
• Presentation — provides iconography and card/list widgets for a coherent UI.

Think of EntityType as the “class” of your records. Everything else (forms, listings, actions) composes on top of it.

---

Typical Uses

• Global references across modules: store ownerType="Ticket" + ownerId="019a7265-821f-70db-b8fe-f16e300ea061" to relate supporting entities (comments, attachments, …).
• UI composition: choose card profile, listing widget, and icon based on the type for consistent rendering.
• API discovery: resolve or override the public API URL for a type.
• Governance: use validity to soft-enable/disable types in environments or during migrations.
• Tagging & config: attach small bits of typed configuration and labels for admin tools and dashboards.

---

Examples

Entity	EntityType	Description
Ticket TCKT-123	Ticket	Service request/incident
Customer C001	Customer	Business or residential customer
Attachment A55	Attachment	File linked to another entity

Related concepts:

• Entity specification / profile — subtype rules and UI configuration per type.
• Characteristics — dynamic attributes bound to a type.
• ownerType / refType — use the EntityType string to establish relationships system-wide.

---

Reference

EntityType (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). Used everywhere (links, rules, configs).
name	String	Yes	–	Display name shown in admin UI.
microservice	String	Yes	–	Code of the Microservice where this entity lives (routing & ownership).
publicApiUrl	String	–	–	Optional override of the entity’s public API path relative to the microservice backendUrl. If not set, it’s derived from the entity code (kebab-case, plural).
defaultCardProfile	String	–	–	UI card profile to render entity details by default.
listingCardWidget	String	–	–	UI component used to render items of this type in lists.
icon	String	–	–	Icon identifier used in the UI.
description	String	–	–	Longer description / tooltip.
validityFrom/To	Date	–	–	Time window when the type is considered active.
valid	Bool	–	Yes	Computed from validity; not stored.
abbreviation	String	–	–	Short label for compact UI (must be unique if used).
config	Map	–	–	Free-form, small configuration for admin/UI tooling (not a deployment substitute).
dataTags	List	–	–	Labels for grouping/reporting (e.g., core, customer, ticketing).
localizationData	Object	–	–	Translations for name / description.
auditInfo	Object	–	–	Standard audit metadata.

---

Standard config Structure

The config map on an EntityType follows a standard layout used by the platform. All sections are optional — omit what you don't need.

{
  "persistence": { ... },
  "api": { ... },
  "core": { ... },
  "spel": { ... },
  "sync": { ... }
}

persistence — Storage & eventing

Describes where the entity's data is physically stored and how change events are published.

Key	Type	Description
dbTable	String	Database table name (e.g. crmt_customer_type). Informational — used by admin tools and diagnostics.
dbSchema	String	Database schema that owns the table (e.g. crm).
kafkaTopic	String	Kafka topic for standard CDC events. Events are published as EntityType$action where action is one of Created, Updated, Deleted. Leave empty if eventing is not enabled.
elasticsearchIndex	String	Name of the Elasticsearch index backing this entity. Leave empty if the entity is not indexed in ES.

Example:

"persistence": {
  "dbTable": "crmt_customer_type",
  "dbSchema": "crm",
  "kafkaTopic": "crm.customer-type",
  "elasticsearchIndex": null
}

api — Public API settings

Controls how the entity is exposed through the tSM Public API.

Key	Type	Default	Description
apiVersion	String	v2	Public API version supported by this entity.
entityEndpoint	String	plural dash-case of entity type	URL segment in the API (e.g. customer-types). If omitted, derived automatically from the entity type code.
searchFunction	String	search	Name of the standard API method used to list/search entities.

Example:

"api": {
  "apiVersion": "v2",
  "entityEndpoint": "customer-types",
  "searchFunction": "search"
}

core — Classification & code generation

Metadata that classifies the entity for internal code generation and the type system.

Key	Type	Description
dataCategory	String	Category of the data: Config (configuration/code-table), Data (transactional/business data), or History (audit/log records).
domainType	String	Domain classification (e.g. System, External).
abstractType	String	Base abstract type the entity extends (e.g. AbstractCodeTableTypeEntity).
publicObject	String	Name of the public-facing DTO class (e.g. CustomerTypePublic).

Example:

"core": {
  "dataCategory": "Config",
  "domainType": "System",
  "abstractType": "AbstractCodeTableTypeEntity",
  "publicObject": "CustomerTypePublic"
}

spel — SpEL expression context

Defines how the entity is referenced in SpEL expressions across tSM (rules, conditions, computed fields).

Key	Type	Description
domain	String	The SpEL domain prefix (e.g. crm → @crm.).
client	String	Client name used in SpEL expressions, i.e. the segment after the domain: @<domain>.<client>.xxx. For example, customerType → @crm.customerType.findByCode('VIP').

Example:

"spel": {
  "domain": "crm"
  "client": "customerType"
}

sync — Environment synchronization

Controls how the entity participates in data synchronization between tSM environments (e.g. DEV → TEST → PROD).

Key	Type	Default	Description
enabled	Boolean	true	Globally enable or disable sync for this entity type.
priority	Number	0	Ordering priority. When entities have dependencies, lower-priority entities are synced first.
searchLimit	Number	10000	Maximum page size — the largest number of entities that can be returned in a single search request during sync.
requestMaxSize	Number	1000	Maximum number of entities that can be created or updated in a single POST request.
filenamePattern	String	<code>	Pattern for the filename when syncing to the filesystem. Defaults to the entity's code.

Example:

"sync": {
  "enabled": true,
  "priority": 0,
  "searchLimit": 10000,
  "requestMaxSize": 1000,
  "filenamePattern": "<code>"
}

---

Good Practices

• Keep code stable — it becomes a key in references (ownerType, refType), configs, and API routing.
• Set microservice correctly — drives discovery and helps tools find the right backend.
• Prefer derived publicApiUrl unless you need a custom path; keep it relative to the microservice backendUrl.
• Define UI hints (defaultCardProfile, listingCardWidget, icon) so lists and cards look consistent across the platform.
• Use dataTags to group types in admin screens and reports (e.g., support, crm, files).
• Leverage validity to phase in/out types without schema changes.

---

See Also

• System Settings: Microservice — where the backends are registered
• System Settings: Module — business-domain grouping that consumes entity types
• Supporting Entities – Overview — how ownerType / refType reference entity types across modules