SLA and Advice

This document describes SLA definition DTOs and Advice DTOs used by Ticketing.

1. Business Meaning

1.1 SLA Definition

SLA behavior in Ticketing is defined using:

• Sla as the main SLA definition,
• Metric as measurable SLA dimensions,
• Goal as concrete target values,
• ConditionItem as event-driven start/end/pause/recalculation conditions.

This model separates policy definition from runtime execution:

• policy is defined in Sla/Metric/Goal,
• runtime clocks are controlled by lifecycle events evaluated through ConditionItem.

Business effect: organizations can evolve contractual logic without changing core ticket schema.

1.2 Advice and SLA Pause Semantics

Advice marks time intervals where SLA is typically paused.

Operationally:

• AdviceType.impactOnSla indicates whether advice affects SLA timing,
• Advice.dateFrom / Advice.dateTo represent actual pause interval bounds,
• Advice.plannedDateTo and notificationMinutes support planned stop and reminders.

Typical business usage:

• waiting for customer confirmation,
• waiting for third-party supplier,
• waiting for planned maintenance window,
• waiting for physical access permit.

By explicitly storing these intervals, SLA fairness is transparent and auditable.

1.3 How to Configure SLA and Advice

Recommended business-first setup:

1. Define SLA families in Sla per operational domain (type, moduleId) such as incident assurance, field dispatch, or partner handling.
2. Define Metric objects for what must be measured, for example time to acknowledge, time to restore, and time to resolve.
3. Define Goal thresholds per metric, including business calendar rules (working hours, holidays, 24x7).
4. Define ConditionItem rules to map lifecycle events to SLA clocks (START, END, PAUSE_START, PAUSE_END, RECALC).
5. Validate metric conditions against actual ticket workflow to avoid ambiguous or conflicting clock transitions.
6. Define AdviceType records and explicitly decide which reasons affect SLA using impactOnSla.
7. Operationalize Advice usage in procedures so pauses are entered with clear reason and planned end (plannedDateTo).
8. Add reminder discipline via notificationMinutes so paused tickets reliably return to active handling.

Configuration principles:

• keep metric semantics stable and business-readable,
• keep goal calendars explicit to avoid false breaches,
• keep pause reasons finite and auditable,
• keep SLA and Advice governance aligned with contractual obligations and partner agreements.

1.4 Why SLA and Advice Attributes Exist

Business rationale:

• SLA type and moduleId: bind policy to the right operating context and accountable organization unit.
• metric conditions: convert lifecycle events into deterministic measurable clocks.
• goals time and calendar: express contractual targets in business-time semantics.
• advice impactOnSla: controls whether a pause reason should stop SLA time.
• advice dateFrom / dateTo: preserve exact pause boundaries for audit, penalty review, and dispute handling.
• advice plannedDateTo: introduces expected resume point for operational planning.
• advice notificationMinutes: adds proactive reminder control to prevent stale paused cases.

Operational outcomes:

• clearer contractual governance,
• fewer false SLA breaches,
• stronger auditability for partner/customer disputes,
• improved operational discipline during waiting intervals.

1.5 Plain Explanation

Simple explanation:

• Sla says which commitments apply.
• Metric says what we measure.
• Goal says what target must be achieved.
• ConditionItem says when the SLA clock starts, stops, pauses, or recalculates.
• Advice says "we are waiting now", and this is typically when SLA pause is recorded.
• AdviceType says whether that waiting reason should pause SLA or not.

If teams use this consistently, SLA results become fair, explainable, and trusted by operations and business stakeholders.

Reference links:

• SLA policy objects: Sla, SlaExpanded, SlaExpand
• Metrics and targets: Metric, Goal, ConditionItem, ConditionItemType
• Pause governance: Advice, AdviceType, AdviceStatus

---

2. Entity Reference: SLA

Sla

Business role: top-level SLA policy object defining which service objectives apply for a module/process context. It is the governance anchor for contractual response/resolution commitments.

Field	Type	Required	Read-only	Description
id	UUID?	No	No	Row unique identifier / primary key in UUID format. ID may be assigned by the client using UUIDv4 standard, or it is generated by TSM. This ID SHOULD NOT be displayed to the end user.
code	String	Yes	No	Code of the SLA. It is used whenever the value is referenced from computer program or API. It MUST be unique and SHOULD contain only ASCII characters without spaces (best to use valid programming language identifier).
name	String	Yes	No	Name of this SLA, this is displayed to the user.
description	String?	No	No	Description of the SLA, it may be used as a tooltip. Default: null.
validityFrom	Date?	No	No	Begin of the validity of the SLA. Default: null.
validityTo	Date?	No	No	End of the validity of the SLA. Default: null.
type	String?	Yes	No	Type of this SLA Default: null.
metrics	List<Metric>?	No	No	List of SLA Metric codes which are applied. Default: ArrayList().
moduleId	UUID?	No	No	ID of target TSM module for which the SLA is defined.FK TsmModule.id Default: null.
localizationData	LocalizationData?	No	No	Localization data associated with the SLA. Default: LocalizationData().
dataTags	List<String>	Yes	No	Additional data tags (aka labels). Default: ArrayList().
config	MutableMap<String, Any?>	No	No	Config of the value. Default: HashMap().

SlaExpanded

Business role: read model variant of SLA used when metric detail must be delivered in one payload for UI/API consumers.

Field	Type	Required	Read-only	Description
id	UUID?	No	No	Row unique identifier / primary key in UUID format. ID may be assigned by the client using UUIDv4 standard, or it is generated by TSM. This ID SHOULD NOT be displayed to the end user.
code	String	Yes	No	Code of the sla. It is used whenever the value is referenced from computer program or API. It MUST be unique and SHOULD contain only ASCII characters without spaces (best to use valid programming language identifier).
name	String	Yes	No	Name of this sla, this is displayed to the user.
type	String?	Yes	No	Type of this sla Default: null.
metrics	List<Metric>?	No	No	Metrics. Default: null.

Metric

Business role: measurable SLA dimension (for example time-to-acknowledge or time-to-resolve) with start/end/pause rules and target goals.

Field	Type	Required	Read-only	Description
id	UUID?	No	No	Row unique identifier / primary key in UUID format. ID may be assigned by the client using UUIDv4 standard, or it is generated by TSM. This ID SHOULD NOT be displayed to the end user.
code	String	Yes	No	Code of the metric. It is used whenever the value is referenced from computer program or API. It MUST be unique and SHOULD contain only ASCII characters without spaces (best to use valid programming language identifier).
name	String	Yes	No	Name of this metric, this is displayed to the user.
description	String?	No	No	Description of the value, it may be used as a tooltip. Default: null.
tooltip	String?	No	No	Tooltip. Default: null.
order	Double?	No	No	Order. Default: null.
slaId	UUID?	No	No	Sla ID. Default: null.
conditions	List<ConditionItem>	Yes	No	Conditions. Default: ArrayList().
goals	List<Goal>?	No	No	Goals. Default: emptyList().
startSpelExpression	String?	No	No	Start Spel Expression. Default: null.
endSpelExpression	String?	No	No	End Spel Expression. Default: null.
data	MutableMap<String, Any?>	No	No	Data of entity Default: HashMap().

Goal

Business role: concrete target threshold for an SLA metric, including calendar and optional conditional expression.

Field	Type	Required	Read-only	Description
id	UUID?	No	No	Row unique identifier / primary key in UUID format. ID may be assigned by the client using UUIDv4 standard, or it is generated by TSM. This ID SHOULD NOT be displayed to the end user.
metricId	UUID	Yes	No	Matric ID
spelExpression	String?	No	No	SPEL expression Default: null.
time	String	Yes	No	Time in format hours:minutes
calendar	String	Yes	No	Calendar
order	Double?	No	No	Order. Default: null.

ConditionItem

Business role: event condition rule defining when metric measurement starts, ends, pauses, or recalculates during ticket lifecycle execution.

Field	Type	Required	Read-only	Description
eventType	String	Yes	No	Event Type.
eventData	MutableMap<String, Any?>	No	No	Event Data.
type	ConditionItemType	Yes	No	Type.

Enum SlaExpand

Value	Meaning
METRICS	Expand SLA metrics.
METRICS_GOALS	Expand SLA metrics and their goals.

Enum ConditionItemType

Value	Meaning
START	Condition starts SLA metric measurement.
END	Condition ends SLA metric measurement.
PAUSE_END	Condition ends SLA pause interval.
PAUSE_START	Condition starts SLA pause interval.
RECALC	Condition triggers SLA recalculation.

---

3. Entity Reference: Advice

Advice

Business role: operational marker for waiting/dependency intervals where SLA clock is typically paused (for example awaiting customer, vendor, shipment, or planned maintenance window).

Field	Type	Required	Read-only	Description
id	UUID?	No	No	Row unique identifier / primary key in UUID format. ID may be assigned by the client using UUIDv4 standard, or it is generated by TSM. This ID SHOULD NOT be displayed to the end user.
ticketId	UUID	Yes	No	Ticket this advice belongs to.
adviceType	String	Yes	No	Code of the advice type.
impactOnSla	Boolean?	No	Yes	Impact on SLA. Default: null.
adviceStatus	AdviceStatus	Yes	No	Status of the advice. Default: AdviceStatus.VALID.
description	String?	No	No	Advice description - usually the reason why the advice was created. Default: null.
dateFrom	Date	Yes	No	Start date of the Advice - date when SLA calculation should be paused (for adviceType with impact on Sla)
dateTo	Date?	No	No	Real date when the Advice was stopped. Default: null.
plannedDateTo	Date?	No	No	Real date when the Advice was stopped. Default: null.
notificationMinutes	Int?	No	No	If set, the number of minutes before the plannedDateTo to send notification. Default: null.
data	Map<String, Any?>	No	No	Any additional data in JSON format. Default: HashMap().

AdviceType

Business role: controlled taxonomy of advice reasons with explicit indicator whether the advice affects SLA timing.

Field	Type	Required	Read-only	Description
id	UUID?	No	No	Row unique identifier / primary key in UUID format. ID may be assigned by the client using UUIDv4 standard, or it is generated by TSM. This ID SHOULD NOT be displayed to the end user.
code	String	Yes	No	Code of this value. It is used whenever the value is referenced from computer program or API. It MUST be unique and SHOULD contain only ASCII characters without spaces (best to use valid programming language identifier).
name	String	Yes	No	Name of this value, this is displayed to the user.
description	String?	No	No	Description of the value, it may be used as a tooltip. Default: null.
validityFrom	Date?	No	No	Begin of the validity of the value. Default: null.
validityTo	Date?	No	No	End of the validity of the value. Default: null.
localizationData	LocalizationData?	No	No	Localization data of the record attributes Default: LocalizationData().
config	MutableMap<String, Any?>	No	No	config of the value, it may be used for another variables Default: HashMap().
dataTags	List<String>	Yes	No	Additional data tags (aka labels). Default: ArrayList().
impactOnSla	Boolean	Yes	No	Information from AdviceType - cannot be updated Default: false.

TaskState

Business role: compact state descriptor used for task-state representation in workflow-related ticket operations.

Field	Type	Required	Read-only	Description
code	String	Yes	No	Code
name	String	Yes	No	Name
description	String?	No	No	Description Default: null.

Enum AdviceStatus

Value	Meaning
VALID	Advice definition is valid and available.
CANCELED	Advice was canceled before completion.
CLOSED	Advice finished and was closed.
ACTIVE	Advice is currently active.