Salesforce Flow Orchestrator multi-user automation best practices (2025)
/plugin marketplace add JosiahSiegel/claude-plugin-marketplace/plugin install salesforce-master@claude-plugin-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
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:
D:/repos/project/file.tsxD:\repos\project\file.tsxThis applies to:
NEVER create new documentation files unless explicitly requested by the user.
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:
| 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 = 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)
Requirements:
Setup ā Flows ā New Flow ā Orchestration
Name: Employee_Onboarding
Object: Employee__c (custom object)
Trigger: Record Created, Status = 'Pending Onboarding'
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'
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
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)
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
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)
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
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}
)
)
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);
}
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');
}
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?
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;
}
}
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
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);
});
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)
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
// 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);
}
}
}
}
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.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.