Value Converter

A Value Converter turns technical identifiers (UUIDs, codes) into human-friendly labels across tSM UI, exports, and automations.
Instead of showing 8f1d… or USR_00123, you can render “Jane Novak (NOC)”, “Incident – Priority P1”, or a formatted composite like “O2-BRNO-Router-23”.

What it’s for

• Listings & cards — show readable names in columns that are backed by foreign keys.
• Forms — present friendly pick-list values or denormalized labels.
• Documents/Notifications — render resolved names in PDFs, emails, SMS.
• Integrations — map incoming codes to display strings, or build composite labels.

Value Converters are config entries that bind a converter implementation (backend bean) with optional parameters, caching, and microservice scope.

---

Typical Uses

• Resolve User UUID → “Full name (Department)”.
• Render Location code → “Prague / DC-1 / Row-A” using hierarchy lookups.
• Map Partner status code → localized label (with fallback).
• Build composite labels (e.g., device name = site + rack + unit).
• Normalize third-party identifiers to internal display conventions.

---

How it works

1. Define a converter (this entity) with a stable code.
2. Optionally provide a parameters form (paramsFormCode) to collect runtime config (e.g., which fields to include).
3. Plug the converter where needed (UI schema, formatter templates, processes).
4. Converter runs on demand, reads input value(s), fetches related data, and returns a pretty string (or object).
5. Apply caching (cacheType: SHORT/LONG) to balance performance vs. freshness.

Converters are scoped to a microservice via microserviceCode and implemented by a backend bean (name can be inferred from code or set explicitly in backendBeanName).

---

Reference

ValueConvertorConfig (attributes)

Field	Type	Required	Read-only	Description / Notes
id	UUID	–	–	Identifier (not for end-user display).
code	String	Yes	–	Unique ASCII code (no spaces). Used wherever this converter is referenced.
name	String	Yes	–	Human-readable name shown in admin tools.
description	String	–	–	Tooltip/long help text.
validityFrom/To	Date	–	–	Active window.
valid	Bool	–	Yes	Computed from validity; not stored.
backendBeanName	String	–	–	Backend bean that implements the converter. If empty, it is derived from code.
paramsFormCode	String	–	–	Optional form to capture converter parameters (when not set, Monaco editor is shown for raw JSON).
microserviceCode	String	Yes	–	Microservice that provides/hosts this converter (use existing Microservice.code).
cacheType	Enum	Yes	–	Caching policy: NONE, SHORT, LONG. Default is NONE.
config	Map	–	–	Free-form metadata for tooling (keep lightweight).
dataTags	List	–	–	Labels for grouping/reporting (e.g., core, external).
localizationData	Object	–	–	Translations for name/description.
auditInfo	Object	–	–	Standard audit metadata.

cacheType guidance

• NONE — values change frequently (e.g., live status); prefer no caching.
• SHORT — minutes-scale volatility; good for user names with role badges.
• LONG — rarely changing reference data (locations, static dictionaries).

---

Good Practices

• Stabilize code — treat it as immutable; it’s referenced from UI configs and templates.
• Scope carefully — set microserviceCode to the service that knows the data best.
• Design params — when a converter is reusable in multiple contexts, expose options via paramsFormCode.
• Cache wisely — use SHORT/LONG to avoid overloading lookups; invalidate when upstream data changes.
• Localize output — return already localized labels when appropriate (or include locale in params).
• Fail soft — on missing input, return a clear placeholder (e.g., “—” or “[unknown: value]”) rather than throwing.

---

See Also

• System Settings: Microservice — inventory of backends where converters live
• System Settings: EntityType — many converters target specific entity types
• Output Management — where resolved labels are rendered into documents
• SpEL Clients — calling conventions for converters in processes/templates