Worklog

Worklogs record time and activity details on tSM records (Tickets, Orders, Assets, Projects, …).
They provide a reliable basis for effort tracking, billing, SLA reporting, and operational accountability.

Typical use cases:

• Service & Support — investigation time, implementation work, on-call interventions
• Professional Services — billable/non-billable hours per order/project
• Operations & Maintenance — preventative tasks, incident post-mortems
• Change & Release — change execution windows, verification/testing effort

• Non-interruptible work — create a single block for an execution window (e.g., maintenance 22:00–02:00) and add checkpoints as comments if desired.

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

Effort tracking

tSM includes a Worklog Console—a focused UI where each user can:

• See all their worklogs across tickets/orders/projects for a chosen period (today, this week, custom range).
• Start a new worklog with one click from wherever they are (ticket header button, global quick-add, or keyboard shortcut).
• Run a live timer, pause/resume, or post time retroactively (e.g., after a call).
• Edit/merge/split entries and add structured details via the selected worklogTypeCode form (billable flag, rate, category, location).
• Review totals (daily/weekly) with optional rounding rules and validation (e.g., prevent overlaps if your policy requires it).

Typical flow:

1. Open a record → click Log work → timer starts (ownerType/ownerId prefilled).
2. Stop when done or adjust start/end for accuracy.
3. Add type + notes; submit. The entry appears in both the record’s timeline and your Worklog Console.

---

Typical Flows

1) Log work with start/end and description

@dms.worklog.create({
  "ownerType": "Ticket",
  "ownerId": #ticket.id,
  "worklogTypeCode": "Investigation",
  "description": "<p>Reviewed logs and reproduced the issue.</p>",
  "startDate": #parseDate("2025-11-11T09:00:00Z"),
  "endDate": #parseDate("2025-11-11T10:30:00Z"),
  "data": { "billable": true, "location": "remote" }
})

2) Quick “now” entry for ad-hoc work

@dms.worklog.create({
  "ownerType": "Order",
  "ownerId": #order.id,
  "worklogTypeCode": "Implementation",
  "description": "<p>Applied configuration and verified.</p>",
  "startDate": #now().minusMinutes(45),
  "endDate": #now(),
  "data": { "billable": true }
})

3) Link a worklog to an additional record (e.g., related Task)

@dms.worklogRelatedEntity.create({
  "worklogId": #worklog.id,
  "name": "Related task",
  "refType": "Task",
  "refId": #task.id,
  "data": { "relation": "executed-for" }
})

If a related entity with refType = "TASK" is present, the worklog exposes taskEntityRefId (read-only) for convenience.

4) Search worklogs for a record (for summaries and billing)

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

---

Business & Governance

• Classification — worklogTypeCode (code table) distinguishes activities such as Investigation, Implementation, Testing. Types can define a form for consistent UI/validation and an icon for recognizable UI cues.
• Time accounting — startDate/endDate define the measured window. Use types and data fields to mark billable vs non-billable, travel, after-hours, etc.
• Attribution — workerId can explicitly set the performer (defaults to the authenticated user when omitted).
• Compliance & Audit — audit info records who created/updated the worklog and when.
• Cross-linking — Worklog Related Entity lets you reference additional records (e.g., Task/Change), without duplicating the worklog.

---

Reference

Worklog (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, Asset, …).
ownerId	String	Yes	–	Parent record ID.
workerId	UUID	–	–	Performer; defaults to the authenticated user on creation if omitted.
description	String	–	–	Work description in (subset) HTML; keep it concise and safe for display.
startDate	Date	–	–	Start timestamp of the work.
endDate	Date	–	–	End timestamp of the work.
data	Map	–	–	Custom key/value data (e.g., billable, category, location).
worklogTypeCode	String	–	–	Activity type code (FK to Worklog Type).
taskEntityRefId	String	–	Yes	Convenience field derived from related entities when a link with refType = "TASK" exists.
auditInfo	Object	–	–	Standard audit fields (created by/at, updated by/at).

Duration is implied by startDate/endDate. If you need explicit duration fields in UI, compute them from these timestamps or store them in data.

---

Worklog Related Entity (attributes)

Links a worklog to additional records beyond its owner (e.g., a Task, Change, or Asset).

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

---

Worklog Type (code table)

Defines allowed worklogTypeCode values and their behavior (form, icon, privileges).

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 used to validate/render additional fields in data.
privilege	String	–	–	Optional privilege required to use/view this type.
icon	String	–	–	UI icon identifier.
dataTags	List	–	–	Labels/tags for search and reporting.
config	Map	–	–	Additional configuration.
auditInfo	Object	–	–	Standard audit fields.

---

Good Practices

• Use clear types (worklogTypeCode) and keep descriptions crisp; rely on form (when defined) for structured fields.
• Always set times — ensure startDate and endDate are correct and in a consistent timezone policy.
• Billable logic — store billable markers/rates in data or drive them from the selected type.
• Cross-reference instead of duplicating — link to Tasks/Changes via Worklog Related Entity.
• Reportability — standardize keys in data (e.g., billable, rate, category) for easier analytics.

---

See Also

• Supporting Entities – Overview (ownership & typing model)
• Comment — narrative context alongside time entries
• Attachment — add evidence (screens, PDFs) to the same record
• SpEL Clients — configuration & usage