Work Item Diagnostics¶
Work item diagnostics help process builders understand what happened while a task was prepared, assigned, processed, or routed. Use them when the runtime result does not match the process design you expected.
Diagnostics are available from work item render information as diagnosticTrace when trace capture is enabled and the trace is still retained. The trace is troubleshooting data; it is separate from work item history, activities, audit logs, and form data.
When to Use Diagnostic Traces¶
Use diagnostic traces to answer questions such as:
- Why did this task appear for this user?
- Which role, group, or membership lookup assigned the task?
- Did the prework or postwork script run?
- Which route was selected after the action?
- Did a decision table, script, database query, REST call, or SOAP call affect this step?
- Did a reminder or deadline worker act on the work item?
Diagnostics are most useful during process development and test-mode runs. They are also useful for live troubleshooting when an administrator enables live trace capture.
Reading Diagnostic Trace Data¶
A diagnostic trace is organized as a timeline of runtime sessions for the work item. The main aggregate is workitem.diagnostics; inside it, each session represents one important runtime phase.
Common sessions include:
| Session | What it helps explain |
|---|---|
workitem.preprocess | How the work item was prepared before it reached the user, including assignment and prework behavior. |
workitem.process | What happened when the work item was completed, including postwork and route selection. |
workitem.reminder | Whether the reminder worker evaluated or sent a reminder for the work item. |
workitem.deadline | Whether the deadline worker evaluated or completed the work item by deadline behavior. |
Read the trace from top to bottom. Start with the session label, then inspect the child entries that match the behavior you are investigating. For example, assignment problems usually start in preprocess, route problems usually start in process, and reminder or deadline problems usually start in the matching worker session.
What the Trace Can Show¶
Diagnostic entries are grouped by the type of runtime work being performed. Depending on the process features used by the work item, a trace can show:
- assignment and visibility evaluation
- role and membership lookups such as manager resolution
- prework and postwork script execution
- route evaluation and selected target task
- decision model and decision table execution
- external calls, including REST, SOAP, database, document, file, and certificate operations
- runtime helper calls, including cache, calendar, localization, and database helpers
- reminder and deadline worker execution
Each entry can include a short label, timing, error information, input or output summary, and structured metadata. The exact details depend on which runtime operation produced the entry.
Previous Step Context¶
In test mode, a work item can include trace context from the previous completed work item. This helps explain why the current step was reached, especially after a route or postwork script created the next task.
Previous-step sessions are marked with traceContext=previousStep. When available, the runtime prefers the previous work item's workitem.process trace because it usually contains the action, postwork, and route evaluation that led to the current work item.
Availability and Limits¶
diagnosticTrace can be empty or unavailable when tracing is disabled, the work item is outside the configured trace mode, the trace has expired, or the work item has not produced traceable activity yet.
Trace data is intentionally bounded. Long values are shortened, and very large sessions are truncated. When truncation happens, the trace includes a trace.truncated summary entry so you know additional entries were hidden.
Administrators control trace capture mode and retention at the node level. For configuration details, see Diagnostic Trace Configuration.