Ticket Relationships and Context

This document covers relationship and context DTOs that connect tickets to other tickets, parties, impacted entities, and type registries.

1. Business Meaning

1.1 Ticket-to-Ticket Relationship

TicketRelationship models explicit links between tickets (parent/child, dependency, and others) using relationship type codes.

From business perspective, this creates a controlled ticket graph instead of isolated records. That graph is crucial for major incidents, duplicate suppression, dependency orchestration, and consolidated closure management.

1.2 Impact and Party Context

• RelatedEntity models technical/business objects affected by or associated with a ticket.
• RelatedParty models parties/roles involved in ticket handling.

Together, these structures provide operational context required for major-incident handling, cross-ticket consolidation, and business-impact communication.

In telecom/service-assurance use cases, this context is the difference between:

• "we fixed one ticket" and
• "we can explain which customers/services were affected, who owns communication, and which technical domain caused the issue."

1.3 How to Configure Relationships and Context

Recommended setup sequence:

1. Define link semantics in LinkType (parent-child, duplicate, dependency, blocked-by), including reverse labels for UI readability.
2. Define RelatedEntityType to classify impacted objects (service, resource, customer asset, location, platform component).
3. Define RelatedPartyType and RelatedPartyRole to standardize actor semantics (requester, affected customer, resolver, supplier, field engineer).
4. Establish integration naming rules for refType and identifier rules for refId across CRM, inventory, monitoring, and partner domains.
5. Define minimal required context by ticket type. Example: major incident requires at least one impacted service entity and one accountable owner party.
6. Use TicketRelationship, RelatedEntity, and RelatedParty as part of ticket lifecycle governance, not only as optional enrichments.

Configuration principles:

• relationship type semantics must be finite and stable,
• refType values should map to known system domains, not free text,
• context should be sufficient for impact communication and RCA, but not overloaded with redundant data,
• relationship and context rules should be validated in workflow gates for critical ticket types.

1.4 Why Relationship and Context Attributes Exist

Business rationale:

• ticketId / relatedTicketId: preserve ticket graph topology and enable coordinated execution.
• type on TicketRelationship: preserves semantic meaning of each edge for automation, analytics, and UI rendering.
• refType / refId: preserve authoritative pointers to master records in external systems.
• reason on RelatedEntity: separates root-source context from impacted scope and associated context.
• relatedPartyType / relatedPartyRole: separate party structure from responsibility semantics.
• refData and data: preserve snapshot context used during operations even when master data later changes.

Operational outcomes:

• faster impact communication to business/customer stakeholders,
• cleaner handover between NOC, care, and field teams,
• better RCA evidence in post-incident review,
• reduced duplicate activity on correlated incidents.

1.5 Plain Explanation

Simple explanation for business teams:

• TicketRelationship tells how tickets are connected,
• RelatedEntity tells what is affected,
• RelatedParty tells who is involved and in which role.

If these are configured and used consistently, teams can answer four core questions quickly:

1. Is this ticket part of a bigger incident?
2. Which services/customers/assets are impacted?
3. Who owns communication and who owns technical resolution?
4. What external records prove this context?

Reference links:

• Ticket graph edge: TicketRelationship
• Impact objects: RelatedEntity, RelatedEntityType
• Stakeholders and roles: RelatedParty, RelatedPartyType, RelatedPartyRole

---

2. Entity Reference: Ticket Relationship

TicketRelationship

Business role: explicit graph edge between tickets used for major-incident coordination, dependency tracking, duplicate handling, and consolidated closure logic across related cases.

Field	Type	Required	Read-only	Description
id	UUID?	No	No	Ticket relationship 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	String	Yes	No	Ticket identifier - UUID or key. In GUI is written: ticketId.key type(tict_link_type.name) relatedTicketId.key. eg.: 'IdMain is parent of idRel'
relatedTicketId	String	Yes	No	Related ticket identifier - UUID or key.In GUI is written: relatedTicketId.key type(tict_link_type.reverse_name) ticketId.key, eg.: 'idRel is child of idMain'
type	String	Yes	No	Type of the ticket relationship. This value MUST be one of ticket relationship code from 'Ticket Relationship' registry
description	String?	No	No	Free text to describe the ticket. It may contain HTML formatting. Default: null.

Interface TreeNode

Business role: projection contract for ticket graph visualizations. It supports business-facing relationship trees used in NOC/SOC dashboards and incident war-room views.

Field	Type	Description
id	String	Id.
ttype	String	Ttype.
name	String	Name.
style	String	Style.
pstyle	String	Pstyle.

Interface TreeLink

Business role: projection contract for links in ticket relationship graphs. It preserves relationship semantics for visual analytics and impact navigation.

Field	Type	Description
id	String	Id.
type	String	Type.
ticketId	String	Ticket ID.
relatedTicketId	String	Related Ticket ID.

---

3. Entity Reference: Related Entities and Parties

RelatedEntity

Business role: references affected or associated business/technical objects (service, resource, customer asset, location, etc.). This aligns with TMF621 relatedEntity and is essential for impact analysis and root-cause tracking.

Field	Type	Required	Read-only	Description
id	UUID?	No	No	Related entity 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 identifier - UUID.
name	String?	Yes	No	Entity name.
refId	String	Yes	No	Related entity ID.
refType	String?	Yes	No	Related entity type (Customer, Ticket, EntityInstanceConfiguration, EntityInstance, etc. from EntityType registry). Default: null.
refData	Map<String, Any?>?	No	No	Json structure of related entity attributes related to entity. Values are valid in creation time, so they can be different from actual data in master system. Default: HashMap().
type	String	Yes	No	Entity type. Information about structure or content (SERVICE, RESOURCE, CUSTOMER, OPERATOR...).FK RelatedEntityType.code
subType	String?	No	No	Entity sub type. Code from catalog (MMO_TV ...). Default: null.
data	MutableMap<String, Any?>	No	No	Json structure of entity attributes related to ticket. Values are valid in creation time, so they can be different from actual data in master system. Default: HashMap().
placeId	String?	No	No	Place ID. Default: null.
gpsLat	Double?	No	No	Coordinates - latitude. Default: null.
gpsLng	Double?	No	No	Coordinates - longitude. Default: null.
reason	RelatedEntityReason	Yes	No	Entity source Default: RelatedEntityReason.RELATED.
parentRelatedEntityIds	MutableList<UUID>	Yes	No	List of parent Entity IDs Default: ArrayList().
typeConfig	MutableMap<String, Any?>	No	Yes	Map of related entity type configuration indexed by config code. read only proxy of RelatedEntityType.type.config (pointed by self.type). Value must be a JSON string valid according to characteristics form (go to the Form designer and download JSON Schema specification which can be used to validate the actual value). Default: HashMap().

Enum RelatedEntityReason

Value	Meaning
RELATED	Entity directly related to the ticket (source/context).
IMPACTED	Entity impacted by the ticket.
ASSOCIATED	Associated entity with contextual relevance.
DECO	Impacted entity calculated automatically by decomposition.

RelatedParty

Business role: references involved actors and roles (customer, reporter, resolver, partner, vendor). This aligns with TMF621 relatedParty and supports communication, accountability, and contractual governance.

Field	Type	Required	Read-only	Description
id	UUID	Yes	No	Identifier of related party.
ticketId	UUID	Yes	No	Ticket identifier - UUID.
name	String?	No	No	The name of the related entity if applicable. Default: null.
relatedPartyType	String	Yes	No	Code of related party type. Indicates the data type/structure of related party. I.e. data type/structure about customer/operator etc..FK RelatedPartyType.code
relatedPartyRole	String?	No	No	Code of related party role. Indicates the role of related party.FK RelatedPartyRole.code Default: null.
data	MutableMap<String, Any?>	No	No	Json structure of entity attributes related to ticket. Values are valid in creation time, so they can be different from actual data in master system. Default: HashMap().
refData	MutableMap<String, Any>?	No	No	Json structure of referenced entity attributes related to ticket. Values are valid in creation time, so they can be different from actual data in master system. Default: HashMap().
refId	String?	Yes	No	Identified of related party in master system.
refType	String	Yes	No	Type of related party in master system

---

4. Registry Reference: Related Entity/Party Types

RelatedEntityType

Business role: governs allowed classes of related entities and their metadata/forms. It standardizes cross-domain context modeling and prevents inconsistent reference payloads.

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.
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.
description	String?	No	No	Description of the value, it may be used as a tooltip. Default: null.
localizationData	LocalizationData?	No	No	Localization data of the record attributes Default: LocalizationData().
config	MutableMap<String, Any?>	No	No	Map of related entity type configuration indexed by config code. Value must be a JSON string valid according to characteristics form (go to the Form designer and download JSON Schema specification which can be used to validate the actual value). Default: HashMap().
entitySpecId	UUID?	No	No	Entity specification ID. Default: null.
entityTypeId	UUID?	No	No	Entity type ID. Default: null.
icon	String?	No	No	Graphic element displayed next to the type of notification Default: null.
form	String?	No	No	Form code. Default: null.
dataTags	List<String>	Yes	No	Additional data tags (aka labels). Default: ArrayList().

RelatedPartyType

Business role: governs structural types of related parties and integration contracts with master-party domains.

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.
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.
description	String?	No	No	Description of the value, it may be used as a tooltip. Default: null.
localizationData	LocalizationData?	No	No	Localization data of the record attributes Default: LocalizationData().
entitySpecId	UUID?	No	No	Entity specification ID. Default: null.
entityTypeId	UUID?	No	No	Entity type ID. Default: null.
form	String?	No	No	Form code. Default: null.
dataTags	List<String>	Yes	No	Additional data tags (aka labels). Default: ArrayList().
config	MutableMap<String, Any?>	No	No	Config of the value. Default: HashMap().

RelatedPartyRole

Business role: governs role semantics in ticket context (for example requester, affected customer, assignee, supplier). It enables consistent stakeholder analytics and notification rules.

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.
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.
description	String?	No	No	Description of the value, it may be used as a tooltip. Default: null.
localizationData	LocalizationData?	No	No	Localization data of the record attributes 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().