Notification

Notifications automate and orchestrate outbound and in-app communication (Email, SMS, in-app, user comments, etc.) to customers and users.
Compared with simple “send email” calls, tSM Notifications provide rules, templates, auditable persistence, delivery windows, reprocessing, and retention.

Typical business uses:

• Service & Support — ticket updates to customers, escalations to on-call groups
• Order & Field Ops — schedule confirmations, technician ETAs, completion summaries
• Compliance & Finance — policy updates, invoice delivery, payment reminders
• Product & Growth — lifecycle nudges, renewal notices, success check-ins

Related concepts (covered in the overview): notifications are owned by a record via ownerType/ownerId, can include attachments, related entities, and are classified by a notification template (templateCode) and delivery type.

---

How notifications are produced

Event & trigger sources (eventType)

tSM supports multiple ways to trigger a notification:

• SYSTEM / PROCESS (Kafka) — reactive; a rule listens to events (e.g., CommentCreated, TicketStatusChanged). Other microservices do not need to know a notification will be sent (inversion of control).
• KAFKA (arbitrary topic) — subscribe directly to a topic with a filter (headers/body) defined in rule config.
• REST — push event data via a public REST endpoint.
• DIRECT — call a template explicitly (no event routing) from process logic.

Each Notification Rule defines the trigger (event type), optional config (e.g., Kafka topic and filters), and—optionally—an evalNotificationUrl used to compose the final payload.

Two ways to build the message

1. Default evaluation
   Use the selected Notification Template: content is rendered either from the template’s content or via Output Management (formatterDocumentTemplateId) with data/formatterDocumentTemplateDataOverride. Attachments included if provided at creation time.
2. Eval URL (evalNotificationUrl)
   Back end composes the notification by POSTing event data + candidate templates to a URL which returns the final data, owner, targets (notificationTo), related entities, and—optionally—attachments.
   This path is required when using Kafka-based creation (SYSTEM/PROCESS/KAFKA).

Delivery

• default — tSM’s built-in senders handle Email/SMS/Application/UserComment/etc.
• client-specific — a custom sender bean (apiSenderBeanName) integrates with a third-party API.

---

Typical Flows

1) Direct send using a template (synchronous example)

@dms.notification.send({
  "ownerType": "Ticket",
  "ownerId": #ticket.id,
  "templateCode": "TicketCustomerUpdate",
  "notificationTo": [
    { "ownerType": "User", "ownerId": #customer.userId, "email": #customer.email }
  ],
  "data": {
    "ticketKey": #ticket.key,
    "status": #ticket.status,
    "publicComments": @dms.comment.search({
       "ownerType": "Ticket", "ownerId": #ticket.id,
       "filter": { "private": false }
    })
  },
  "attachments": [
    { "name": "summary.pdf", "mimeType": "application/pdf", "data": #pdfBase64 }
  ]
})

2) Reactive send via Kafka event + Eval URL

A Notification Rule listens to CommentCreated. For each matching event, tSM posts to evalNotificationUrl, which decides whether/how to send.

// Rule config (conceptual) 
@dms.notificationRule.upsert({
  "code": "CommentCreatedCustomerNotify",
  "name": "Notify customer on public comment",
  "eventType": "SYSTEM",
  "config": { "kafka": { "topic": "CommentCreated", "header": "[private==false]" } },
  "evalNotificationUrl": "/notification/eval/public-comment"
})

// Eval handler (your backend) returns a decision & payload:
{
  "ownerType": "Ticket",
  "ownerId": "12345",
  "notificationTo": [{ "email": "customer@example.com" }],
  "relatedEntities": [{ "name": "Ticket", "refType": "Ticket", "refId": "12345" }],
  "data": { "ticketKey": "TCKT-12345", "commentHtml": "<p>We fixed it.</p>" }
}

3) Respect business hours (delivery window)

@dms.notificationTemplate.upsert({
  "code": "NightSafeSMS",
  "name": "SMS during business hours only",
  "deliveryType": "SMS",
  "deliveryTimeCode": "BUSINESS_HOURS",  // see Delivery Time
  "subject": "Status update",
  "formatterDocumentTemplateId": #tplId
})

4) Resend to different recipients

@dms.notification.resend({
  "notificationId": #notif.id,
  "notificationTo": [{ "email": "ops-team@example.com" }]
})

---

Business & Governance

• Rules & Templates — admins configure Notification Rules (triggers, sources, eval URL) and Notification Templates (channel, content, business hours, form-driven config). Many templates can listen to the same rule with additional filters.
• Audience — notificationTo targets users/groups (via ownerType/ownerId) or direct contacts (email/phone). Use templates to standardize addressing (e.g., primary contact, current assignee).
• Content generation — use Output Management for rich layouts; override specific parts with formatterDocumentTemplateDataOverride when needed.
• Compliance — persisted Notification entities store parameters, rendered content, recipients, and status transitions. Retention: “live” notifications stay in DB; archives are kept in Elasticsearch with policy-driven pruning (per type: DB days, ES days, and selective attribute scrubbing—params, content).
• Delivery windows — bind templates to a Delivery Time (e.g., business hours, no nights).
• Reprocessing — failed items can be retried; templates may expose custom resend logic (e.g., via sender bean).
• Observability — track status (PLAN→PROCESSING→SENT/DELIVERED/FAILED/…), messageId from the sender, and userStatus (read/unread).

---

Reference

Notification (entity)

Field	Type	Required	Read-only	Notes
id	UUID	–	–	Identifier (not for end-user display).
ownerType / ownerId	String	Yes	–	Record this notification belongs to.
templateCode	String	Yes	–	The template driving channel/content.
subject / contents	String	–	contents: RO	Subject and rendered content (contents usually generated by template/formatter).
notificationTo	List<NotificationTo>	–	RO	Resolved recipients; stored via DB relation.
relatedEntities	List	–	RO	Cross-links to other records.
data / params	Map	–	–	Rendering data (data) and generator params (params).
status	Enum	–	–	PLAN, PROCESSING, SENT, DELIVERED, FAILED, PROCESSED, …
created / sent	Date	–	–	Timestamps.
deliveryFromTime/ToTime	Time	–	–	Per-notification override of window (rare; prefer template’s deliveryTimeCode).
fromUserId / from	UUID / String	–	–	Sender identity/override.
messageId	List<String>	–	–	IDs returned by downstream sender(s).
userStatus	String	–	–	User-level status (e.g., read/unread).
auditInfo	Object	–	–	Standard audit fields.
expirationDate	Date	–	RO	Computed from template expiration and sent.

Notification Create (input DTO)

Used by DIRECT/REST creation paths.

Field	Type	Required	Notes
ownerType / ownerId	String	Yes	Owning record.
templateCode	String	Yes	Template to use.
notificationTo	List<NotificationTo>	Yes	Targets (users or direct addresses).
relatedEntities	List	–	Optional cross-links.
data	Map	–	Rendering payload for formatter/template.
formatterDocumentTemplateDataOverride	Map	–	Partial overrides for formatted content.
attachments	List	–	Optional attachments (Base64).
from, subject, messageId, contents, status, userStatus	–	–	Optional overrides; when contents is set, formatter is bypassed.

Notification Resend (input DTO)

Field	Type	Required	Notes
notificationId	UUID	Yes	Existing notification to resend.
notificationTo	List<NotificationTo>	Yes	New recipients.

Notification To (recipient)

Targets a User (via ownerType/ownerId) or a direct address (email, phone, address). Includes email type (TO, CC, BCC) and recipient data resolved by the system.

Notification Related Entity

Holds additional references (e.g., location, asset, shipment) with optional geodata and freeform data.

Notification Rule (code table)

Defines the trigger and how to evaluate data for templates.

Key fields	Purpose
eventType	One of SYSTEM, PROCESS, KAFKA, REST, DIRECT.
config	Source specifics (e.g., Kafka topic, header filter).
evalNotificationUrl	URL used to fetch/compute final payload (mandatory for Kafka-driven creation).
apiSenderBeanName	Custom sender bean (optional) for client-specific delivery.
configFormCode	Form that shapes NotificationTemplate.config (admin UX).
microserviceCode / configTypeCode	Scoping and specialization across domains.

Notification Template (code table)

Controls channel, content, business hours, and retention impact.

Key fields	Purpose
deliveryType	Channel: EMAIL, SMS, APPLICATION, USER_COMMENT, INCOMING_EMAIL, LETTER (if used).
content / formatterDocumentTemplateId	Static vs formatted content via Output Management.
deliveryTimeCode	Business window (see Delivery Time).
subject, from, to, icon, category	Presentation and classification.
status	ACTIVE / INACTIVE.
expiration	Days the message is actionable (e.g., button/URL validity).
notificationRuleCode	Which rule triggers this template.
config / dataTags	Admin-configured options and tags (via configFormCode form).

Delivery Time (code table)

Defines allowed send window (e.g., 08:00–18:00 workdays). Templates reference it by deliveryTimeCode.

---

Persistence & Retention

• Database stores live notifications including parameters and rendered content.

• Elasticsearch stores the archive for search/analytics and long-term evidence.

• Retention is configurable per type:

  • DB TTL — days until removal from DB after send (can be 0 to delete immediately after successful archive).
  • Archive TTL — days until removal from Elasticsearch.
  • Attribute scrubbing — selectively drop large/sensitive fields in ES (e.g., params, content) after N days.

---

See Also

• Output Management — design message layouts and generate content
• Log — system & integration evidence (pair with notifications for end-to-end traceability)
• Sharing — control visibility of in-app notifications
• SpEL Clients — how to call the clients from processes