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 coordinates multi-user, multi-step, multi-stage business processes without code. Different users complete sequential tasks in one 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

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 and Monitoring

Advanced Flow Orchestrator designs (parallel approvals, conditional branches, retry / escalation, record-triggered orchestration, external integration handoffs) plus monitoring, reporting, and operational dashboards live in references/advanced-patterns-monitoring.md. Load that reference for complex multi-stage implementations and production observability.

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:
1. Check queue membership: Setup → Queues
2. Verify object permissions: User profile/permission set
3. 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:
1. Enable debug logs: Setup → Debug Logs
2. Check Flow error emails: Setup → Process Automation Settings
3. 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:
1. Verify record meets entry criteria
2. Check orchestration activation status
3. 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<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: Advanced Patterns and Monitoring

Advanced Flow Orchestrator designs (parallel approvals, conditional branches, retry/escalation, record-triggered orchestration, external integration handoffs) plus monitoring, reporting, and operational dashboards. SKILL.md keeps overview, use cases, architecture, build steps, step types, integrations, best practices, troubleshooting, pricing, and migration.

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:

1. Average Time per Stage
   SELECT StepDefinitionName,
          AVG(LastModifiedDate - CreatedDate) as AvgDuration
   FROM FlowOrchestrationWorkItem
   WHERE Status = 'Completed'
   GROUP BY StepDefinitionName

2. 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

3. 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 < 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;
    }
}