Log

Logs capture system and integration events tied to records across tSM (Tickets, Orders, Integrations, …).
They provide an auditable trail for troubleshooting, compliance, SLA evidence, and observability of inbound/outbound calls, background jobs, and workflow steps.

Typical use cases:

• Integrations — request/response bodies, HTTP status, correlation IDs, partner message IDs
• Automation & Workflows — step-by-step execution traces with timings and results
• Support & Ops — error details attached to affected tickets/orders for faster diagnosis
• Compliance — retention-friendly event history with searchable metadata

Related concepts (covered in the overview): supporting entities link to a parent via ownerType and ownerId. Logs are further categorized by logTypeCode (the entity type).

What this “Log” is — and what it isn’t

tSM distinguishes three different logging concepts:

• Application logs (INFO/WARN/ERROR/DEBUG): developer/ops diagnostics written by services; not modeled as entities in DMS.
• Audit log: who changed what/when (field-level history on business entities).
• Integration logs (this entity): business-relevant records of message exchanges with partners/systems, modeled as first-class data you can view, search, report on, and retain under policy.

Integration logs as business evidence

Although technical by nature, integration logs are treated as primary business entities:

• They prove exchanges with external partners (requests/responses, status codes, correlation/message IDs).
• They are human-readable: use Form Designer to render a business-friendly view of the request, response, and related data (no need to read raw JSON/XML).
• They support reprocessing (e.g., retry/resend a message) when your process allows it.
• You can search, apply SLAs, compute statistics, and build reporting dashboards on top of them.

Scope and typical content

While various technical events can be stored here, the primary use is integration messages (e.g., REST or SOAP) capturing:

• Request/Response bodies
• Result codes and error messages
• Correlation IDs / Message IDs for traceability
• Timing (start/end/duration) for performance and SLA evidence

When needed, attach additional metadata to each log via relatedData (and, if applicable, typed forms), so business users can filter and understand messages without reading low-level payloads.

---

Typical Flows

1) Record an outbound integration call (with correlation)

@dms.log.create({
  "ownerType": "Order",
  "ownerId": #order.id,
  "logTypeCode": "OutboundAPI",
  "startDate": #now(),
  "request": "{ \"action\": \"createShipment\", \"order\": \"" + #order.number + "\" }",
  "response": null,
  "resultCode": null,
  "resultMessage": null,
  "correlationId": #uuid(),
  "messageId": null,
  "module": "fulfillment",
  "relatedData": {
    "endpoint": "https://partner.example/api/v1/shipments",
    "method": "POST"
  }
})

2) Complete the log after receiving the response

@dms.log.patch(#log.id, {
  "endDate": #now(),
  "response": "{ \"shipmentId\": \"SHP-100231\", \"status\": \"created\" }",
  "resultCode": "200",
  "resultMessage": "OK"
})

If duration is not provided, it is computed automatically as endDate - startDate.

3) Attach additional context (related record)

@dms.logRelatedEntity.create({
  "logId": #log.id,
  "name": "Shipment entity",
  "refType": "Shipment",
  "refId": "SHP-100231",
  "data": { "provider": "PartnerX" }
})

4) Search logs for a record (e.g., for a troubleshooting view)

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

Tip: Use correlationId and/or messageId consistently across steps and systems to stitch together multi-hop flows.

---

Business & Governance

• Classification — logTypeCode defines the scenario (e.g., OutboundAPI, InboundWebhook, WorkflowStep, SystemEvent), request/response forms, icons, and optional resend URL.
• Timing — startDate + endDate (and derived duration) enable performance and SLA insights.
• Observability — store protocol, endpoint, partner/system names in relatedData or on the Log Type for reporting consistency.
• PII & Security — redact sensitive data from request/response; keep tokens/credentials out of logs. Use relatedData for safe, structured metadata.
• Cross-linking — relate logs to multiple records (e.g., Ticket + Order + Shipment) via Log Related Entity without duplicating log documents.

---

Reference

Log (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, Order, Integration).
ownerId	String	Yes	–	Parent record ID.
logType	Object	–	–	Full type object (optional). Either logType or logTypeCode must be provided on create/patch.
logTypeCode	String	Yes	–	Type code (FK to Log Type). Alternative to logType.
startDate	Date	Yes	–	Start timestamp.
request	String	Yes	–	Request text/payload (free text; consider size and redaction).
response	String	–	–	Response text/payload (optional; consider size and redaction).
resultCode	String	–	–	Result/status code (200, 400, 500, partner codes, etc.).
resultMessage	String	–	–	Human-readable message (error detail, reason).
endDate	Date	Yes	–	End timestamp.
correlationId	String	–	–	Cross-system correlation (trace ID).
messageId	String	–	–	Message identifier from broker/partner.
description	String	–	–	Free text description (may include HTML).
duration	Long (ms)	–	–	Explicit duration; if omitted it is computed as endDate - startDate.
module	String	–	–	Module/feature tag (e.g., billing, fulfillment).
relatedData	Map	–	–	Arbitrary metadata (endpoint, HTTP method, partner system, protocol, etc.).
relatedEntities	List	–	–	Additional cross-links (see Log Related Entity).
auditInfo	Object	–	–	Standard audit fields (created by/at, updated by/at).

---

Log Related Entity (attributes)

Link a log to additional records beyond its owner (e.g., Shipment, Task, Asset).

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

---

Log Type (code table)

Defines allowed logTypeCode values and their behavior (forms for request/response/related data, protocol, resend URL, etc.).

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.
appFrom / appTo	String	–	–	Source/target application identifiers.
requestFormCode	String	–	–	Form code for rendering/validating request structure.
responseFormCode	String	–	–	Form code for response structure.
relDataFormCode	String	–	–	Form code for relatedData structure.
language	String	–	–	Language hint for payload formatting.
protocol	String	–	–	Protocol marker (HTTP, MQTT, SFTP, …).
formCode	String	–	–	Generic form code (legacy/compat).
config	Map	–	–	Additional configuration.
resendUrl	String	–	–	Optional URL for resending/replay operations.
localizationData	Object	–	–	Translations for attributes (e.g., name, description).
validityFrom/To	Date	–	–	Controls whether the type is currently valid.
valid	Boolean	–	Yes	Computed from validity; not stored.
dataTags	List	–	–	Labels/tags for search/reporting.
auditInfo	Object	–	–	Standard audit fields.

---

Good Practices

• Redact smartly — avoid storing secrets and personal data in request/response. Put safe, structured metadata into relatedData.
• Correlate consistently — populate correlationId (and messageId when available) across the entire call chain.
• Type for clarity — pick meaningful logTypeCode values and back them with forms to keep payloads readable and reportable.
• Close the loop — always set endDate; let duration auto-compute for reliable timing analytics.
• Link, don’t duplicate — tie related records via Log Related Entity instead of copying payloads across entities.

---

See Also

• Supporting Entities – Overview (ownership & typing model)
• Worklog — time-based accountability alongside logs
• Attachment — store payload snapshots or generated reports
• SpEL Clients — configuration & usage