Process Instance
A Process Instance is the runtime record Salesforce creates each time an Approval Process is started on a specific record.
Definition
A Process Instance is the runtime record Salesforce creates each time an Approval Process is started on a specific record. It tracks the current step, the assigned approvers, the timestamps of every transition, and the final outcome (approved, rejected, recalled, or still pending). Each running approval on a record produces one ProcessInstance row, accessible through the API and queryable in SOQL alongside its child ProcessInstanceStep and ProcessInstanceWorkitem records.
Process Instance is the audit substrate of every Salesforce Approval Process. The Approval Process definition (entry criteria, steps, approvers, actions) is metadata; the Process Instance is the runtime data showing what happened in a specific approval. Auditors, compliance officers, and developers building approval analytics dashboards all query ProcessInstance to answer questions like "how many discounts above 30 percent were approved last quarter" and "average approval cycle time per region." The instance is also the data structure recalled when a user clicks Recall Approval on a pending record.
How a Process Instance records every step of a running approval
The three-object hierarchy
Approval runtime data lives across three related objects. ProcessInstance is the parent: one row per approval submitted. ProcessInstanceStep is a child row per step the instance has completed (with the original status: Submitted, Approved, Rejected, Removed). ProcessInstanceWorkitem is the row representing the currently pending step where an approver still needs to act; only one workitem exists per running instance at a time. When a user clicks Approve in the UI, the platform writes a new ProcessInstanceStep and either advances the workitem to the next step or closes the instance.
The runtime data captured
Each ProcessInstance row captures the record being approved (TargetObjectId), the approval process definition (ProcessDefinitionId), the status (Pending, Approved, Rejected, Removed, Started, NoResponse), the start and finish timestamps, the submitter, and any comments. Each step row captures the actor, the action, the timestamp, the step name, and comments. This is everything an auditor needs to reconstruct an approval cycle from first submission to final outcome, including who approved and who delegated to a queue member.
Recall and the workitem lifecycle
When a user submits a record for approval, Salesforce creates the ProcessInstance plus the first ProcessInstanceWorkitem. The workitem assigns the approval to a user or queue. The approver acts (Approve, Reject, Reassign). On approve, the workitem is closed and a new step row is written; if there are more steps, a new workitem opens. On recall, the submitter cancels the pending workitem; the instance status becomes Removed. The workitem object is the only place where pending state lives, which is why notifications and dashboards typically query it directly.
Querying approval history in SOQL
Reports on approval cycle time, approval volume, and bottlenecks rely on ProcessInstance and ProcessInstanceStep. A typical query joins on the target object to filter by region or amount: SELECT Id, Status, CreatedDate, CompletedDate, TargetObject.Amount__c FROM ProcessInstance WHERE TargetObject.Region__c = 'EMEA' AND CreatedDate = LAST_QUARTER. The CompletedDate minus CreatedDate gives the cycle time. Combined with ProcessInstanceStep for the step-by-step view, this is the basis of every approval analytics dashboard.
Approval Process Recall and Reassignment
Recall is the action the original submitter takes to cancel a pending approval; it writes a Removed step and closes the workitem. Reassignment is the action an approver takes to delegate to another approver; it writes a step for the original assignment and a new workitem for the delegate. Both actions are logged with timestamps and the actor, which gives compliance teams the audit trail they need for sensitive approvals like financial commitments or contract changes.
Process Instance and Approval Process changes
When an admin edits the underlying Approval Process definition (adds a new step, changes an approver), in-flight ProcessInstance rows continue with the version they were submitted under. The platform freezes the approval flow at instance creation so a mid-flight change cannot inject a new step into running approvals. This is the correct behavior for audit integrity but can confuse admins who expect their edits to take effect immediately; they need to wait for new submissions or recall the in-flight ones.
Reporting limits and custom dashboards
Standard Salesforce reports include some approval data, but the most useful approval analytics come from custom report types built on ProcessInstance and ProcessInstanceStep. Cycle time by approval process, approver workload, bottleneck step, recall rate, and approval-to-close ratio are all reachable through these objects. Many sales-ops teams build a custom Lightning component that surfaces a Pending Approvals dashboard for managers based on ProcessInstanceWorkitem.
Query Process Instance data to build an approval analytics dashboard
Build a custom report on ProcessInstance, ProcessInstanceStep, and the target object so finance or compliance can see approval cycle time, volume, and bottleneck steps in one place.
- Identify the target object
Pick the object the approval runs on (Opportunity, Quote, Contract, custom). Note which fields you need on the report (Amount, Region, Owner, Stage).
- Create a custom report type
Setup, Report Types, New. Primary object is the target object. Add ProcessInstance as a related object linked by TargetObjectId. Add ProcessInstanceStep as a related object linked by ProcessInstanceId.
- Mark useful fields available
On the report type, mark Status, CreatedDate, CompletedDate, and the comment field as available for reporting. Add the step's Actor and StepStatus.
- Build a cycle-time report
Create a report on the new report type. Add a custom formula column: CompletedDate minus CreatedDate. Group by the target object's region or owner.
- Add filters
Filter to approvals that completed in the last quarter. Filter status to Approved or Rejected (exclude Pending for cycle time).
- Build the dashboard
Add the report to a dashboard with a bar chart of cycle time by region and a tile of Pending vs Completed counts. Pin to the finance or compliance home page.
Parent runtime object; one row per approval submitted.
Child object capturing each completed step with actor and timestamp.
Pending step record; one row per active workitem awaiting approver action.
Joins ProcessInstance to the target object to make the runtime data reportable alongside business fields.
- ProcessInstance freezes the approval flow at submission. Edits to the underlying Approval Process do not apply to in-flight instances; they only affect new submissions.
- ProcessInstanceWorkitem is the only place pending state lives. Reports on completed approvals use ProcessInstance plus ProcessInstanceStep; reports on pending approvals must include Workitem.
- CompletedDate is null while the instance is still pending. Cycle-time formulas need to handle the null case or filter completed instances only.
- Comments on a step are stored on the step row, not the instance. A report that needs the comment trail must include ProcessInstanceStep in the report type.
Trust & references
Cross-checked against the following references.
- ProcessInstance Object ReferenceSalesforce Developer Docs
- Approvals OverviewSalesforce Help
- ProcessInstanceStep ReferenceSalesforce Developer Docs
Straight from the source - Salesforce's reference material on Process Instance.
- ProcessInstance DocumentationSalesforce Developer Docs
- ProcessInstanceWorkitem ReferenceSalesforce Developer Docs
- Approval HistorySalesforce Help
Hands-on resources to go deeper on Process Instance.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Process Instance?
Q2. What does a process instance track?
Q3. Why analyze process instances?
Discussion
Loading discussion…