flow-orchestrator-2025

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (
) in file paths, NOT forward slashes (/ ).

Examples:

❌ WRONG: D:/repos/project/file.tsx
✅ CORRECT: D:\repos\project\file.tsx

This applies to:

Edit tool file_path parameter
Write tool file_path parameter
All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

Priority: Update existing README.md files rather than creating new documentation
Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
User preference: Only create additional .md files when user specifically asks for documentation

Salesforce Flow Orchestrator (2025)

What is Flow Orchestrator?

Flow Orchestrator enables you to orchestrate multi-user, multi-step, and multi-stage business processes without code. It allows different users to complete sequential tasks within a unified workflow, with built-in approvals, conditional logic, and error handling.

Key Capabilities:

Multi-User Workflows: Assign tasks to different users/teams across stages
Stage-Based Execution: Organize work into logical stages
Background Automation: Combine user tasks with automated steps
Visual Progress Tracking: Users see their position in the workflow
Fault Paths: Handle errors gracefully (Summer '25)
No-Code: Build complex processes without Apex

When to Use Flow Orchestrator

Use Case Flow Orchestrator? Why

Employee Onboarding (HR → IT → Manager) ✅ Yes Multi-user, sequential stages

Quote-to-Cash (Sales → Finance → Operations) ✅ Yes Cross-functional approval process

Case Escalation (L1 → L2 → L3 Support) ✅ Yes Tiered assignment with SLAs

Simple record automation (create/update) ❌ No Use Record-Triggered Flow

Single-user process ❌ No Use Screen Flow

Batch data processing ❌ No Use Scheduled Flow or Apex Batch

Orchestration Architecture

Orchestration = Stages → Steps → Background Automations

Stage 1: "HR Review" ├─ Step 1.1: Interactive Step (HR Manager reviews) ├─ Step 1.2: Background Automation (create records) └─ Decision: Approved? → Next Stage : End

Stage 2: "IT Provisioning" ├─ Step 2.1: Interactive Step (IT assigns equipment) ├─ Step 2.2: Background Automation (provision accounts) └─ Step 2.3: Interactive Step (IT confirms completion)

Stage 3: "Manager Onboarding" ├─ Step 3.1: Interactive Step (Manager schedules 1:1) └─ Step 3.2: Background Automation (send welcome email)

Building an Orchestration (Step-by-Step)

Example: Employee Onboarding Process

Requirements:

HR reviews new hire documents → Approved/Rejected
If approved, IT provisions accounts and equipment
Manager schedules first day and assigns mentor
System sends notifications at each stage

Step 1: Create Orchestration

Setup → Flows → New Flow → Orchestration Name: Employee_Onboarding Object: Employee__c (custom object) Trigger: Record Created, Status = 'Pending Onboarding'

Step 2: Design Stages

Stage 1: HR Document Review

Stage Name: HR_Document_Review Stage Description: HR verifies employee documentation Run Mode: One at a Time (sequential)

Step 1.1 (Interactive):

Name: Review_Documents
Assigned To: Queue "HR_Onboarding_Queue"
Due Date: 2 days from start
Screen Flow: HR_Document_Review_Screen
Inputs: Employee__c.Id

Step 1.2 (Background - Decision):

If HR_Approved = true → Next Stage
If HR_Approved = false → End + Send Rejection Email

Stage 2: IT Provisioning

Stage Name: IT_Provisioning Condition: Runs only if Stage 1 approved

Step 2.1 (Interactive):

Name: Assign_Equipment
Assigned To: Queue "IT_Provisioning_Queue"
Due Date: 3 days from stage start
Screen Flow: IT_Equipment_Assignment
Inputs: Employee__c.Id

Step 2.2 (Background):

Name: Create_AD_Account
Autolaunched Flow: Create_Active_Directory_Account
Inputs: Employee__c.Email, Employee__c.FirstName

Step 2.3 (Background):

Name: Send_IT_Confirmation
Action: Send Email Template
Recipient: Employee__c.Email
Template: Welcome_Email

Stage 3: Manager Setup

Stage Name: Manager_Setup Depends On: Stage 2 complete

Step 3.1 (Interactive):

Name: Schedule_First_Day
Assigned To: Employee__c.Manager__c
Due Date: 1 day from stage start
Screen Flow: Manager_Onboarding_Tasks

Step 3.2 (Background):

Name: Update_Status
Record Update: Employee__c.Status = 'Onboarding Complete'

Step 3: Implement Fault Paths (Summer '25)

Fault Path on IT Provisioning Failure:

If Step 2.2 (Create_AD_Account) fails: ├─ Retry Step (1 attempt after 10 minutes) ├─ If still fails: │ ├─ Send email to IT Manager with error details │ ├─ Create Task for manual provisioning │ └─ Assign Interactive Step to IT Manager for resolution └─ Continue to Stage 3 (don't block entire process)

Configuration:

Step 2.2: Create_AD_Account ├─ Fault Path Enabled: true ├─ Retry Attempts: 1 ├─ Retry Delay: 10 minutes └─ On Final Failure: ├─ Create Task │ ├─ Subject: "Manual AD Account Creation Needed" │ ├─ Assigned To: IT_Manager_Queue │ └─ Priority: High └─ Send Email Notification ├─ Template: IT_Provisioning_Failure └─ Recipients: IT Managers

Interactive Steps vs Background Steps

Interactive Steps

Use for: Actions requiring human judgment or input

Interactive Step Configuration: ├─ Screen Flow: Define UI for user input ├─ Assigned To: User, Queue, or Role ├─ Due Date: Formula (TODAY() + 2 for 2 days) ├─ Instructions: What user should do ├─ Input Variables: Data passed to screen flow └─ Output Variables: Data returned from user

Example Screen Flow (HR Review):

Screen: Review Documents ├─ Display: Employee Name, Position, Documents Uploaded ├─ Input: Radio Button (Approve / Reject) ├─ Input: Text Area (Comments - required if reject) └─ Action: Save & Submit

Output Variables:

HR_Approved (Boolean)
HR_Comments (Text)

Background Steps

Use for: Automated actions without user interaction

Background Step Types: ├─ Autolaunched Flow: Call another flow ├─ Apex Action: Invoke Apex method ├─ Send Email: Email template or custom ├─ Post to Chatter: Notify users ├─ Create Records: DML operations ├─ Update Records: Field updates ├─ External Service: REST callout └─ Wait: Pause for duration or until condition

Advanced Patterns

Pattern 1: Conditional Stage Execution

Use Case: Skip stages based on criteria

Stage 2: Manager Approval Condition: Order_Total__c > 10000

Entry Criteria Formula: {!$Record.Order_Total__c} > 10000

Result:

If order <= $10,000 → Skip Stage 2, go to Stage 3
If order > $10,000 → Execute Stage 2 (manager approval required)

Pattern 2: Parallel Steps Within Stage

Use Case: Multiple teams work simultaneously

Stage 3: Parallel Provisioning Run Mode: All at Once (parallel)

Step 3.1 (Interactive): IT assigns laptop [Assigned to IT Queue] Step 3.2 (Interactive): Facilities assigns desk [Assigned to Facilities Queue] Step 3.3 (Interactive): HR orders business cards [Assigned to HR Queue]

Stage completes when: All steps complete

Pattern 3: Dynamic Assignment

Use Case: Assign to different users based on record data

Step Assignment Formula: IF( {!$Record.Region__c} = 'West', {!$User.WestCoastManager}, IF( {!$Record.Region__c} = 'East', {!$User.EastCoastManager}, {!$User.DefaultManager} ) )

Pattern 4: SLA Monitoring

Use Case: Escalate if step not completed on time

Step Due Date: {!$Flow.CurrentDate} + 2 (2 days)

Scheduled Flow: Check_Overdue_Steps

Schedule: Daily at 8 AM
Query: OrchestrationWorkItem where DueDate < TODAY AND Status = 'In Progress'
Action: Send escalation email to manager

Monitor with SOQL:

// Query overdue orchestration steps List<FlowOrchestrationWorkItem> overdueItems = [ SELECT Id, Label, StepDefinitionName, AssignedToId, RelatedRecordId, DueDate, Status FROM FlowOrchestrationWorkItem WHERE DueDate < TODAY AND Status = 'InProgress' ORDER BY DueDate ASC ];

// Send escalation notifications for (FlowOrchestrationWorkItem item : overdueItems) { sendEscalationEmail(item); }

Monitoring and Reporting

FlowOrchestrationWorkItem Object

Query work items for reporting:

// Active orchestrations List<FlowOrchestrationWorkItem> activeItems = [ SELECT Id, Label, StepDefinitionName, AssignedToId, CreatedDate, LastModifiedDate, DueDate, Status, RelatedRecordId FROM FlowOrchestrationWorkItem WHERE Status = 'InProgress' ORDER BY DueDate ASC ];

// Calculate time spent in each step for (FlowOrchestrationWorkItem item : activeItems) { Long milliseconds = item.LastModifiedDate.getTime() - item.CreatedDate.getTime(); Decimal hours = milliseconds / (1000.0 * 60 * 60); System.debug('Step: ' + item.Label + ', Time: ' + hours + ' hours'); }

Dashboard Metrics

Key Metrics to Track:

Average Time per Stage SELECT StepDefinitionName, AVG(LastModifiedDate - CreatedDate) as AvgDuration FROM FlowOrchestrationWorkItem WHERE Status = 'Completed' GROUP BY StepDefinitionName
Completion Rate by Assignee SELECT AssignedToId, COUNT(CASE WHEN Status = 'Completed' THEN 1 END) as Completed, COUNT(CASE WHEN DueDate < TODAY AND Status = 'InProgress' THEN 1 END) as Overdue FROM FlowOrchestrationWorkItem GROUP BY AssignedToId
Bottleneck Identification
- Which steps take longest?
- Which steps have highest rejection/failure rate?
- Which assignees have most overdue items?

Custom Dashboard Component

public class OrchestrationMetrics { @AuraEnabled(cacheable=true) public static Map<String, Object> getMetrics() { Map<String, Object> metrics = new Map<String, Object>();

    // Total active orchestrations
    Integer active = [SELECT COUNT() FROM FlowOrchestrationWorkItem WHERE Status = 'InProgress'];
    metrics.put('active', active);

    // Overdue count
    Integer overdue = [SELECT COUNT() FROM FlowOrchestrationWorkItem
                      WHERE Status = 'InProgress' AND DueDate &#x3C; TODAY];
    metrics.put('overdue', overdue);

    // Average completion time (last 30 days)
    AggregateResult[] avgTime = [
        SELECT AVG(LastModifiedDate - CreatedDate) avgDuration
        FROM FlowOrchestrationWorkItem
        WHERE Status = 'Completed'
          AND CreatedDate = LAST_N_DAYS:30
    ];
    metrics.put('avgCompletionHours', (Decimal)avgTime[0].get('avgDuration') / (1000.0 * 60 * 60));

    return metrics;
}

}

Integration with Other Features

Pattern: Orchestration + Approval Process

Stage 2: Manager Approval ├─ Step 2.1 (Interactive): Manager reviews │ └─ Screen Flow with Approve/Reject buttons ├─ Background Automation: Update approval status └─ If Approved: Proceed to Stage 3 If Rejected: Send rejection email, End orchestration

Pattern: Orchestration + Platform Events

Publish events at stage transitions:

trigger OrchestrationStageTrigger on FlowOrchestrationStageInstance (after insert, after update) { List<OrchestrationStageEvent__e> events = new List<OrchestrationStageEvent__e>();

for (FlowOrchestrationStageInstance stage : Trigger.new) {
    if (stage.Status == 'Completed') {
        events.add(new OrchestrationStageEvent__e(
            OrchestrationId__c = stage.OrchestrationInstanceId,
            StageName__c = stage.StepDefinitionName,
            CompletedDate__c = System.now()
        ));
    }
}

if (!events.isEmpty()) {
    EventBus.publish(events);
}

}

Subscribe externally:

// External system tracks orchestration progress client.subscribe('/event/OrchestrationStageEvent__e', (message) => { const { OrchestrationId__c, StageName__c } = message.data.payload; console.log(Stage ${StageName__c} completed for ${OrchestrationId__c});

// Update external dashboard
updateOrchestrationStatus(OrchestrationId__c, StageName__c);

});

Pattern: Orchestration + Agentforce

AI agent handles certain steps:

Stage 2: Document Verification ├─ Step 2.1 (Background): AI agent verifies documents │ └─ Agentforce Action: Verify_Document_Compliance │ - Uses Einstein OCR to extract text │ - Uses LLM to validate against compliance rules │ - Returns: Compliant (true/false) + Confidence score ├─ Decision: If confidence < 90% → Human review └─ Step 2.2 (Interactive - Conditional): Human verifies (if AI uncertain)

Best Practices

Design

Plan stages before building: Sketch workflow on paper/whiteboard
One business process per orchestration: Don't combine unrelated processes
Meaningful stage/step names: Use business terminology, not technical jargon
Clear instructions: Tell users exactly what to do in each step
Appropriate due dates: Balance urgency with realistic timelines

Performance

Minimize steps per stage: <10 steps per stage for maintainability
Avoid unnecessary waits: Only pause when truly needed
Bulkify background automations: Process multiple records efficiently
Use decision logic wisely: Skip unnecessary stages with conditions
Monitor active orchestrations: Archive completed ones regularly

Error Handling

Always implement fault paths (Summer '25): Don't let failures block entire process
Retry transient errors: Network issues, temporary API failures
Escalate permanent errors: Create tasks for manual intervention
Log failures: Track what went wrong for troubleshooting
Test error scenarios: Intentionally trigger failures in sandbox

Security

Respect sharing rules: Use "with sharing" in Apex called by orchestrations
Field-level security: Ensure users have access to fields in screen flows
Queue membership: Verify users in queues have necessary permissions
Sensitive data: Mask or encrypt PII in screen flows and work items

User Experience

Mobile-friendly screens: Many users work on mobile devices
Progress indicators: Show users where they are in process
Clear next steps: Always tell users what happens after they complete a step
Timely notifications: Send reminders before due dates
Feedback on submission: Confirm action was successful

Troubleshooting

Common Issues

Issue 1: Work items not appearing for users

Causes:

User not in assigned queue
User lacks permission to object
Filter criteria on view excludes item

Solution:

Check queue membership: Setup → Queues
Verify object permissions: User profile/permission set
Review work item list view filters

Issue 2: Background step failing silently

Causes:

Apex error in called flow/action
Required field missing
Governor limit exceeded

Solution:

Enable debug logs: Setup → Debug Logs
Check Flow error emails: Setup → Process Automation Settings
Implement fault path to catch and handle errors

Issue 3: Orchestration not triggering

Causes:

Trigger criteria not met
Record not updated properly
Orchestration inactive

Solution:

Verify record meets entry criteria
Check orchestration activation status
Review audit trail for record updates

Debug with Apex

// Query orchestration details for debugging public class OrchestrationDebugger { public static void debugOrchestration(Id recordId) { // Find orchestration instances for record List<FlowOrchestrationInstance> instances = [ SELECT Id, Label, Status, CreatedDate FROM FlowOrchestrationInstance WHERE RelatedRecordId = :recordId ORDER BY CreatedDate DESC ];

    for (FlowOrchestrationInstance instance : instances) {
        System.debug('Orchestration: ' + instance.Label);
        System.debug('Status: ' + instance.Status);

        // Get work items
        List&#x3C;FlowOrchestrationWorkItem> items = [
            SELECT Id, Label, Status, AssignedToId, DueDate
            FROM FlowOrchestrationWorkItem
            WHERE OrchestrationInstanceId = :instance.Id
            ORDER BY CreatedDate
        ];

        for (FlowOrchestrationWorkItem item : items) {
            System.debug('  Step: ' + item.Label + ', Status: ' + item.Status);
        }
    }
}

}

Pricing and Availability

Editions: Enterprise, Performance, Unlimited, Developer
Included Runs: 600 orchestration runs/year (no charge)
Additional Runs: Purchase in blocks for high-volume use
Permissions Required:
Create/Edit: Manage Flows permission
View: View Orchestration in Automation App (Winter '26)
Approve Flows: Approval Designer system permission (Winter '26)

Resources

Flow Orchestrator Guide: https://help.salesforce.com/s/articleView?id=platform.orchestrator_flow_orchestrator.htm
Trailhead: "Flow Orchestration Basics"
Release Notes: Summer '25 and Winter '26 for latest features
FlowOrchestrationWorkItem Reference: Salesforce Object Reference documentation

Migration from Process Builder

Process Builder → Flow Orchestrator:

Process Builder supports only simple automation Flow Orchestrator adds:

Multi-user coordination
Interactive steps
Stage-based organization
Visual progress tracking
Fault handling

When to migrate:

Process involves multiple users
Need stage-based workflow
Want user interface for steps
Require better error handling

Flow Orchestrator transforms complex, cross-functional business processes into visual, manageable workflows that scale across your organization.

flow-orchestrator-2025

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

tailwindcss-advanced-layouts

tailwindcss-animations

tailwindcss-mobile-first

docker-best-practices