Apex Flow Invocation From Apex

Apex Flow Invocation From Apex

Activates when Apex calls Flow.Interview.createInterview to run an Autolaunched Flow. Produces type-safe parameter maps, output retrieval, and clear guidance on the "Apex calls Flow" architectural choice.

Before Starting

• Is the Flow Autolaunched? Only Autolaunched Flows can be started from Apex. Screen Flows cannot run headless and throw.
• Does the Flow's API name exactly match what you will pass? Flow.Interview.createInterview looks up by API name — a typo produces a SObjectException at runtime, not compile time.
• What is the exact type of each input variable in the Flow? Collections of SObjects, dates, currencies all have specific Apex types the Flow engine expects.
• Does the caller execute in a trigger context? Flow invocations count against SOQL, DML, and CPU governor limits of the caller.
• Is this a good architectural fit? If the only reason you're calling a Flow is "admin owns it," ensure the Flow's logic actually benefits from Flow's declarative shape. Plain Apex is usually simpler.

Core Concepts

The Parameter Map Must Match Flow Variable Types Exactly

createInterview accepts Map<String, Object>. The keys are Flow input-variable API names. The values are Apex primitives, SObjects, or List<SObject>. Mismatched types throw Flow.FlowException at runtime with messages like "Type mismatch: expected Decimal, got String".

Collections in Flows have two flavors — SObject collections and primitive collections. Passing List<String> where the Flow expects a "Collection of Text" generally works; passing List<Opportunity> where it expects a "Collection of SObject Records" requires the Flow's SObject type to match.

Starting The Interview Runs The Flow

After createInterview, call .start(). This synchronously runs the Flow to completion (for Autolaunched Flows without pause elements). Long-running Flows — those with loops that create/update many records — count every action against the caller's governor limits.

Output Variables Come Back By Name

After .start(), retrieve outputs with interview.getVariableValue(name). The return type is Object; cast to the expected type. A typo in the output name returns null — no exception.

Invocable Actions Are A Better Fit For Dynamic Invocation

If the caller doesn't know which Flow to run until runtime, consider registering the Flow as an Invocable Action and using the Action framework. This gives you discovery, validation of required parameters, and a better error surface than raw Flow.Interview.

Common Patterns

Pattern 1: Invoke An Autolaunched Flow With Typed Inputs And Outputs

When to use: Apex must delegate a calculated business rule that an admin maintains in Flow.

How it works:

public with sharing class TierAssignmentService {
    public static String assignTier(Account a, Decimal yearToDate) {
        Map<String, Object> params = new Map<String, Object>{
            'inputAccount'    => a,
            'yearToDateAmount'=> yearToDate
        };
        Flow.Interview i = Flow.Interview.createInterview('Assign_Account_Tier', params);
        i.start();
        return (String) i.getVariableValue('resultTier');
    }
}

Why not the alternative: Hardcoding the tier logic in Apex forces deploys for admin-owned tweaks. Calling the Flow preserves declarative ownership while giving Apex a clean call site.

Pattern 2: Bulk-Safe Flow Invocation

When to use: A trigger fires for 200 records and each needs the Flow's logic.

How it works:

public with sharing class BulkTierAssignment {
    public static void assignAll(List<Account> accounts, Map<Id, Decimal> ytdById) {
        Map<String, Object> params = new Map<String, Object>{
            'inputAccounts' => accounts,
            'ytdMap'        => ytdById
        };
        Flow.Interview i = Flow.Interview.createInterview('Bulk_Assign_Tier', params);
        i.start();
    }
}

Why not the alternative: Calling createInterview in a per-record loop multiplies CPU consumption and makes failure isolation harder. Design the Flow to accept a collection and iterate internally.

Decision Guidance

Recommended Workflow

1. Confirm the Flow is Autolaunched (Flow Builder → Start element → "Autolaunched Flow").
2. Read the Flow's input and output variable API names and their Apex-equivalent types.
3. Build a Map<String, Object> with typed keys/values.
4. Call Flow.Interview.createInterview('Flow_API_Name', params) — confirm exact API name.
5. Wrap .start() in try/catch for Flow.FlowException (flow-internal failures) and DmlException (for governor exhaustion).
6. Read outputs via getVariableValue(name) with a cast.
7. Add a test with @IsTest that arranges realistic input and asserts the output; the Apex wrapper still needs its own coverage.

Review Checklist

• Flow is Autolaunched, confirmed in Setup.
• Parameter map keys match Flow variable API names exactly (case-sensitive).
• Parameter value types match Flow variable types exactly.
• createInterview + start() are wrapped in try/catch.
• Output retrieval casts to the expected Apex type.
• Invocation is NOT in a per-record loop over 200 records; Flow accepts a collection.
• Unit test covers the Apex side end-to-end.

Salesforce-Specific Gotchas

See references/gotchas.md for the full list.

1. Screen Flows fail at runtime — only Autolaunched Flows start from Apex.
2. Typo in Flow API name throws at runtime, not compile time.
3. Governor limits are charged to the calling transaction, not reset by the Flow boundary.
4. Output variable typo returns null silently.
5. Picklist values must match Flow's expected internal value, not the label.

Output Artifacts

Related Skills

• apex-invocable-method — the inverse: exposing Apex to Flow
• apex-trigger-architecture — where to put the Flow invocation
• apex-async-architecture — when to enqueue instead of inline-invoking