Process Tracing

Overview

Process Tracing provides detailed visibility into the execution of every process instance. When tracing is enabled, FlowOn BPM captures granular records of each step in the process lifecycle, creating a comprehensive audit trail for debugging, compliance, and analytics.

Each trace record documents what happened, when it happened, and the data context at that moment—giving you complete insight into how your processes execute in production.

Tracing serves multiple purposes across different stakeholders:

• Process Designers use traces to verify that processes behave as intended
• Operations Teams use traces to diagnose problems when process instances don't proceed as expected
• Compliance Officers use traces as audit evidence that required steps were followed
• Business Analysts use traces to understand process performance and identify optimization opportunities
• Support Teams use traces to investigate specific cases and answer questions from stakeholders

Trace Record Structure

Each Process Stage Trace record captures the following information:

Field	Description	Example
Owner	The entity that created the trace record (typically System)	System
Process Stage	The stage in the process where this trace was recorded	"Credit Review", "Final Approval"
Substage	The specific phase within the stage lifecycle	Entering, Exiting, Task Completion, Transition
Trace Data	Contextual data captured at the time of the trace	Field values, decisions made, errors encountered

Substage Types

Each stage in a process goes through multiple phases during execution. FlowOn BPM traces each of these phases as distinct Substages:

Entering

The Entering substage is traced when a process instance arrives at a stage.

Aspect	Details
When Captured	Immediately when the stage is entered, before On Entering automation executes
What It Records	Stage entry timestamp, source stage/transition, initial data state
Use Cases	Track when work arrived, measure queue times, debug automation triggers

Task Completion

The Task Completion substage is traced when assigned work is completed.

Aspect	Details
When Captured	When task(s) are marked complete and completion criteria are met
What It Records	Completion timestamp, who completed the task, task outcome data
Use Cases	Track work completion, measure processing times, identify bottlenecks

Exiting

The Exiting substage is traced when a stage is completed and the process is ready to move on.

Aspect	Details
When Captured	After On Exiting automation completes, before transition evaluation
What It Records	Exit timestamp, stage duration, outcome data, automation results
Use Cases	Track stage completion, measure total stage time, audit automation execution

Transition

The Transition substage is traced when the process moves from one stage to another.

Aspect	Details
When Captured	When transition guards are evaluated and a path is selected
What It Records	Which transition was taken, guard evaluation results, target stage
Use Cases	Debug routing logic, audit decision paths, analyze process flow patterns

Trace Data

The Trace Data field captures comprehensive contextual information at each substage. All trace records include three levels of context:

Common Trace Fields

Field	Description
@Process.Definition.Id	Unique identifier of the process definition
@Process.Definition.Name	Name of the process
@Process.Definition.Version	Version number of the process definition
@Process.Entity	The primary entity the process operates on
@Process.Instance.Id	Unique identifier of this specific process instance
@Process.Instance.Subject	Subject/title of the process instance
@Process.Instance.StartDate	When the process instance started
@Process.Instance.DueDate	When the process instance is due
@Process.Instance.Owner	Owner of the process instance (user or team)
@Process.Stage.Definition.UniqueName	Unique name of the stage definition
@Process.Stage.Instance.Id	Unique identifier of this stage instance
@Process.Stage.Instance.Owner	Current owner of the stage
@Process.Stage.Instance.Subject	Subject/title of the stage
@Process.Stage.Instance.DueDate	When the stage is due
@Process.Stage.Instance.Task	Reference to the activity/task record

Substage-Specific Fields

Entering Trace Data:

• Task subject and due date
• Related entity references
• Security role assignments
• Created task/activity output

Task Completion Trace Data:

• Reference to the completed task/activity
• Whether all completion criteria have been met

Exiting Trace Data:

• Final field values after updates
• Stage duration (by comparing with Entering timestamp)

Transition Trace Data:

• The name/unique identifier of the target stage

Using Traces

Debugging

Traces help identify issues in process execution:

Problem	How Traces Help
Process stuck at a stage	Check Entering trace to confirm arrival; look for missing Task Completion
Wrong path taken	Review Transition trace to see guard evaluation results
Automation failed	Examine Exiting trace data for error details
Unexpected delays	Compare timestamps between Entering and Task Completion

Compliance & Audit

Traces provide a complete audit trail:

• Who completed each task
• When each action occurred
• What decisions were made
• Why specific paths were taken (guard evaluations)

Analytics

Aggregate trace data to analyze process performance:

Metric	Derived From
Average stage duration	Entering → Exiting timestamps
Task completion time	Entering → Task Completion timestamps
Most common paths	Transition trace data
Bottleneck stages	Stages with longest durations

Enabling Tracing

Tracing is configured at the process level when creating or editing a process:

Setting	Effect
Tracing Enabled	All substages traced for every instance
Tracing Disabled	No detailed traces captured (better performance)

Recommendations by Environment

Environment	Tracing Recommendation
Development	✅ Always enabled
Test/UAT	✅ Enabled
Production (low volume)	✅ Enabled for audit
Production (high volume)	⚠️ Consider performance impact

Best Practices

• Enable tracing during development and testing for full visibility
• Enable tracing for critical business processes requiring audit trails
• Consider performance for high-volume processes—tracing adds overhead
• Review traces regularly to identify optimization opportunities