Comment

Comments capture notes, discussions, and updates directly on records across tSM (Tickets, Customers, Orders, …). They help teams collaborate in context, keep a clear communication trail, and present customer-visible replies where needed.

Typical use cases:

• Service & Support — agent internal notes, customer replies, system messages
• Sales & Account — meeting notes, follow-ups, next steps
• Operations — handover notes, shift logs, change approvals
• Automation — workflow status messages, integration echoes

Related concepts (covered in the overview): supporting entities link to a parent via ownerType and ownerId. Comments can be further classified by commentTypeCode (the entity type).

Unified History Stream (Comments as the primary history)

In many modules (notably CRM or Ticketing), Comments serve as the canonical history timeline of the owning record. Instead of splitting information across multiple lists, tSM aggregates heterogeneous events into a single, filterable stream:

• Customer notes – messages coming from customers or portal users
• Helpdesk updates – agent notes, internal memos, handovers
• Process events – workflow transitions, SLA milestones, automations
• Audit events – permission changes, assignments, state changes

Each entry is a Comment with a dedicated commentTypeCode and optional formData carrying structured fields (e.g., SLA target, new assignee, reason code). Operators can filter by type (e.g., Customer, Internal, Process), search within content/metadata, and customize listing columns (e.g., author, visibility, type, key fields from formData).

Example filters & views

• Show only customer-facing conversation: CustomerReply, CustomerQuestion
• Show only process info: WorkflowStep, SLAEvent, AssignmentChange
• Show all with badges: type icon + highlight private vs. public
• Add columns from formData (e.g., SLA Status, New Owner, Reason) for quick scanning

Public comments & self-care / notifications

Use public comments (private = false) to surface information on the self-care portal or to deliver via notifications (email/SMS/in-app). This ensures customers see the same timeline agents do—only with customer-safe entries—keeping communication consistent and traceable.

---

Typical Flows

1) Add an internal note (hidden from customer)

@dms.comment.create({
  "ownerType": "Ticket",
  "ownerId": #ticket.id,
  "commentTypeCode": "InternalNote",
  "private": true,
  "comment": "<p>Investigating issue; probable cache invalidation gap.</p>"
})

2) Add a customer-visible reply

@dms.comment.create({
  "ownerType": "Ticket",
  "ownerId": #ticket.id,
  "commentTypeCode": "CustomerReply",
  "private": false,
  "comment": "<p>We’ve applied a fix. Could you please try again?</p>"
})

3) Create a structured comment with form data

Use formData when the commentTypeCode has an associated form (validation, UI rendering, reporting).

@dms.comment.create({
  "ownerType": "Order",
  "ownerId": #order.id,
  "commentTypeCode": "Approval",
  "private": false,
  "comment": "<p>Order approved.</p>",
  "formData": {
    "approvedBy": #auth.user.name,
    "approvedAt": #now(),
    "riskClass": "Low"
  }
})

4) Link the same comment to another record (cross-reference)

@dms.commentRelatedEntity.create({
  "commentId": #comment.id,
  "name": "Also relevant to this order",
  "refType": "Order",
  "refId": #order.id,
  "data": { "relation": "impacts-fulfillment" }
})

5) Retrieve comments for a record

@dms.comment.search({
  "ownerType": "Ticket",
  "ownerId": #ticket.id
})

Tip: Keep HTML in comment simple and safe (paragraphs, links, lists). Rich rendering can be driven by commentTypeCode and templates.

---

Business & Governance

• Classification — commentTypeCode (code table) defines purpose (e.g., InternalNote, CustomerReply, Approval, SystemMessage), optional form, icon, and rendering templates.
• Visibility — private = true hides content from customers/portals; combine with roles/Sharing for precise access.
• Templating — types may reference text/HTML templates for consistent formatting (e.g., approvals, SLA notices).
• Compliance — audit fields record author and timestamps; use types + forms for structured, reportable data.
• Cross-linking — Comment Related Entity allows referencing additional records without duplicating content.

---

Reference

Comment (attributes)

Field	Type	Required	Read-only	Description / Notes
id	UUID	–	–	Unique identifier (not intended for end-user display).
ownerType	String	Yes	–	Parent record type (e.g., Ticket, Customer, Order).
ownerId	String	Yes	–	Parent record ID.
comment	String	–	–	HTML content of the comment.
private	Boolean	–	–	If true, hide from customers/portals.
userId	UUID	–	–	Author override; defaults to the authenticated user on creation.
date	Date	–	Yes (default)	Creation date (defaults to now).
formData	JSON	–	–	Structured payload validated by the form defined on the comment type.
commentTypeCode	String	–	–	Type code (FK to Comment Type table).
commentTypeName	String	–	Yes (load)	Display name of the type; loaded from the type table; write attempts are ignored.
auditInfo	Object	–	–	Standard audit fields (created by/at, updated by/at).

---

Comment Related Entity (attributes)

Links a comment to additional records beyond its owner.

Field	Type	Required	Description
id	UUID	–	Identifier of the relation row.
refType	String	Yes	Type of the referenced record (e.g., Ticket, Order).
refId	String	Yes	ID of the referenced record.
name	String	Yes	Display name of the link.
data	Map	–	Optional metadata for the relation.
commentId	UUID	–	The comment being linked.
auditInfo	Object	–	Standard audit fields.

---

Comment Type (code table)

Defines allowed commentTypeCode values and behavior: UI icon, form for formData, templates for rendering.

Field	Type	Required	Read-only	Notes
code	String	Yes	–	Unique ASCII code (no spaces). Used in APIs & configurations.
name	String	Yes	–	Display name shown to users.
description	String	–	–	Tooltip/long description.
validityFrom/To	Date	–	–	Controls whether the type is currently valid.
valid	Boolean	–	Yes	Computed from validity; not stored.
localizationData	Object	–	–	Translations for attributes (e.g., name, description).
form	String	–	–	Form name for validating formData.
icon	String	–	–	UI icon identifier displayed next to comments of this type.
privilege	String	–	–	Optional privilege required to use/view this type.
textDocumentTemplate	String	–	–	Template code for text rendering of comment content.
htmlDocumentTemplate	String	–	–	Template code for HTML rendering of comment content.
config	Map	–	–	Additional configuration.
dataTags	List	–	–	Labels/tags for search and reporting.
auditInfo	Object	–	–	Standard audit fields.

---

Good Practices

• Choose the right type (commentTypeCode) to standardize formatting, forms, and visibility.
• Keep customer-visible comments clear and minimal; use templates for consistency.
• Use private for internal notes and combine with Sharing/permissions for strict control.
• Store structured fields in formData for reliable reporting and workflows.
• Cross-link with Comment Related Entity instead of duplicating content across records.

---

See Also

• Supporting Entities – Overview (ownership & typing model)
• Attachment — store files referenced by comments or workflows
• Sharing — access control and collaboration
• SpEL Clients — configuration & usage