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

```csharp
// Simulate from the current activity
List<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.

```csharp
if (processInstance.IsPreExecution)
{
    // Run only the simulation-specific part of this shared action
    return;
}

// Run the regular-execution part of the shared action
await _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, `IsPreExecution` lets 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

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

Table: Comparison of pre-execution approaches

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

## See also

- [Process Instance](https://docs.workflowengine.io/get-started/concepts/process-instance/): The entity whose state is simulated during pre-execution.
- [Set State Directly](https://docs.workflowengine.io/evaluate/workflow-engine-features/direct-state-control/): Move a process instance to a specific activity without running transitions.
- [Timers and Scheduling](https://docs.workflowengine.io/evaluate/workflow-engine-features/timers-scheduling/): How timer intervals behave during pre-execution.
- Pre-Execution Reference: API reference and detailed simulation behavior.