Pre-Execution (Simulation)
A user clicks "Approve" on a purchase order. The workflow might route to the direct manager, skip to the department head, or trigger an escalation - depending on the amount, the user's role, and the time of year. Without running the actual command, there is no way to show the user what will happen next.
Pre-Execution simulates the workflow path from any activity without modifying the process instance's persisted state. The runtime evaluates transition conditions and auto-transitions, but it executes actions only from each activity's PreExecutionImplementation collection. Regular execution uses the separate Implementation collection; neither collection invokes the other automatically.
With Pre-Execution, you can build "Are you sure? This will route to Director Approval." prompts that show the predicted path before the user confirms. For example, simulating an invoice approval shows the user which approval chain their action will trigger, with no history records written and no state changed.
What it is
Think of it as a dress rehearsal for a workflow transition. The process instance is loaded, its parameters are populated, and transition conditions are evaluated. Activities run their pre-execution implementations, and Workflow Engine does not persist the simulated process changes.
You can start a simulation from three entry points:
- From the current activity - simulates what happens if the process continues from where it is now.
- From the initial activity - simulates the process from the very start.
- From any named activity - simulates the path from a specific activity by name.
The result is a list of ActivityDto objects showing which activities the process would visit and which transitions connect them.
For developers: Call PreExecuteAsync(processId, fromActivityName, ignoreCurrentStateCheck) on WorkflowRuntime. The runtime fills system parameters, sets processInstance.IsPreExecution = true, and runs the simulation without persisting process state. The return type is List<ActivityDto>, where each entry has an Activity name and a Transitions collection.
// Simulate from the current activityList<ActivityDto> result = await runtime .PreExecuteFromCurrentActivityAsync(processId);foreach (var activity in result){ Console.WriteLine($"Would visit: {activity.Activity}");}Detecting pre-execution in action code
An activity has two separate action collections: Implementation for regular execution and PreExecutionImplementation for simulation. An action runs during simulation only when it is included in PreExecutionImplementation; actions from Implementation do not run automatically.
If the same action is deliberately included in both collections, it can check IsPreExecution on the ProcessInstance to perform only the simulation-specific part or use different behavior. Actions used only for regular execution do not need the flag to keep them out of simulation.
if (processInstance.IsPreExecution){ // Run only the simulation-specific part of this shared action return;}// Run the regular-execution part of the shared actionawait _notificationService.SendAsync(/* ... */);Condition evaluation also handles pre-execution: conditions with a ResultOnPreExecution value use that value during simulation instead of evaluating the full expression. This lets you define expected outcomes for pre-execution separately from normal execution.
What does not happen during pre-execution
No simulated process state is persisted by Workflow Engine. Specifically:
- No history records are written.
- No parameter changes are saved.
- No timer registrations are created.
- No subprocess instances are started.
The persisted process instance is left unchanged. Actions in PreExecutionImplementation can still interact with external systems, so configure those actions for simulation intentionally.
Why it matters
Pre-Execution delivers these outcomes:
Confidence before committing - Users see the predicted workflow path and can confirm, cancel, or choose a different action. This reduces errors from incorrect assumptions about what a command will do.
Non-persistent what-if analysis - Administrators can simulate scheme changes on in-flight instances to verify the new path without altering the persisted process instance.
Explicit simulation actions - Each activity has a separate pre-execution implementation, so only actions selected for simulation run. When one action is reused in both implementations,
IsPreExecutionlets it select partial or different behavior.Better user experience - Approval UIs can show the predicted approval chain, escalation path, or next activity before the user commits, making the workflow transparent.
Who it is for
Evaluator (CEO, CTO, PM): Pre-Execution enables confirmation dialogs and what-if analysis that make workflows transparent and predictable. Users trust the system more when they can preview the result before acting.
Developer: Call PreExecuteAsync, PreExecuteFromCurrentActivityAsync, or PreExecuteFromInitialActivityAsync on WorkflowRuntime. Place simulation actions in PreExecutionImplementation. If the same action is also in Implementation, use processInstance.IsPreExecution to select its simulation-specific behavior. The API returns a List<ActivityDto> describing the predicted path.
Enterprise architect: Pre-Execution does not persist simulated process state. Actions configured in PreExecutionImplementation still run, so any external behavior must be appropriate for simulation.
When to use it
Use Pre-Execution when you need to show the user what would happen next without actually moving the process forward:
Confirmation dialogs - An approval UI displays "This request will route to Director Approval" with the predicted path before the user confirms. The user clicks "Approve" and sees the expected next step before committing.
What-if analysis - An administrator simulates what a scheme change would do to an in-flight instance, verifying the new path is correct before deploying the update.
Validation checks - Verify that a process instance can reach a desired state before setting the state directly. Pre-execution confirms the path exists.
Multi-step command preview - Before executing a complex command with multiple conditional transitions, show the user which branch the workflow will follow based on current parameters.
Do not use pre-execution as a replacement for ExecuteCommandAsync in normal workflow execution. Pre-execution does not persist the simulated process state. Use ExecuteCommandAsync when the user confirms the action.
How it compares
The table below compares Workflow Engine's pre-execution approach with the alternative of manually evaluating transition conditions.
| Approach | What it requires | Result |
|---|---|---|
| Manual condition evaluation | Duplicate transition logic in the UI layer, keep it in sync with the scheme, handle every branch manually | Fragile, hard to maintain - UI logic drifts from scheme logic over time |
| Workflow Engine Pre-Execution | Call PreExecuteAsync with the process ID and activity name | Workflow Engine evaluates the simulated path using transition conditions and each activity's pre-execution implementation |
The simulation uses the runtime's transition selection and condition handling, while activity actions come from PreExecutionImplementation rather than Implementation. Configure simulation actions so the predicted path reflects the behavior you want to preview.
Frequently asked questions
What happens during pre-execution simulation?
The runtime loads the process instance, fills its system parameters, sets IsPreExecution = true on the process instance, evaluates outgoing transitions with their conditions, executes activity pre-execution implementations, and returns the predicted path as a list of ActivityDto. No state is persisted - no history records, no parameter changes, no timer registrations.
When should I check the IsPreExecution flag in my activity code?
Check IsPreExecution when the same action is deliberately included in both Implementation and PreExecutionImplementation and needs partial or different behavior during simulation. Actions present only in Implementation are not invoked by pre-execution.
Can pre-execution trigger side effects like sending emails?
Pre-Execution can trigger side effects from actions explicitly placed in PreExecutionImplementation. Workflow Engine does not invoke regular Implementation actions automatically, but it also does not suppress external effects from simulation actions. Use IsPreExecution when sharing an action between both collections.
Do I need a specific license for Pre-Execution?
No. Pre-Execution is part of the core runtime and available in all editions.