Process Instance

Jevgenije Betin Updated 2026-07-27 9 min read 1,680 words

concepts process workflow Essential

A process instance is one execution of a scheme. Workflow Engine creates a process instance for a specific scheme, assigns it a unique identifier, positions it at the initial activity, and persists its state to the database. Each process instance can carry its own parameters and business data through the workflow.

What a process instance is

Each process instance that Workflow Engine manages holds three pieces of state: the current activity name, the parameter values attached to this execution, and the transition history. Workflow Engine reads and writes this state through the persistence provider during execution. Transition history is recorded by default and can be disabled per activity.

A process instance moves through several lifecycle states that Workflow Engine manages automatically:

stateDiagram-v2
    Initialized --> Running
    Running --> Idled
    Idled --> Running
    Running --> Finalized
    Running --> Terminated
    Running --> Error
    Error --> Running
    Finalized --> Running
    Terminated --> Running

A process instance reaches the Finalized state when it enters an activity marked as final (IsFinal="true"). Until then, the instance cycles between Idled (waiting) and Running (executing). By default, an unhandled execution error sets Error when a command or active timer exit remains; otherwise it sets Terminated.

The Finalized, Terminated, and Error statuses can all return to Running through SetStateAsync, activity-setting methods, or ResumeAsync. The Error status also accepts commands and timers, while Finalized and Terminated do not.

How a process instance works

Workflow Engine creates a process instance when you call CreateInstanceAsync with a scheme code and a unique identifier:

var processId = Guid.NewGuid();var createParams = new CreateInstanceParams("InvoiceApproval", processId)    .AddPersistentParameter("Amount", 1500.00m)    .AddPersistentParameter("OwnerId", "user-42");await runtime.CreateInstanceAsync(createParams);

Once created, the process instance moves from one activity to the next when a transition fires. A transition can be triggered by a command, by a timer, or automatically when the process instance arrives at the activity. Workflow Engine finds the matching transition, evaluates any conditions on it, and runs the configured actions.

If the trigger does not apply - for example a command is not available at the current activity, or the rule for that command does not permit the given identity - Workflow Engine does not fire the transition.

Process instance properties

A ProcessInstance object exposes properties that reveal the current state, the execution context, and the identity of the user who triggered the transition. These properties are accessible inside actions, conditions, and rules through the processInstance parameter.

Identification properties

These properties identify the process, its scheme, and its place in the process tree:

TenantId is supplied through CreateInstanceParams when the process instance is created and is read-only afterward. In tenant-scoped contexts, Workflow Engine validates it before loading or changing the process instance.

Current state properties

These properties report where the process currently is and where it has been:

Execution context properties

These properties provide context about what is currently executing and why:

Identity properties

These properties track who triggered the current execution:

Reading properties from code

Inside an action, condition, or rule, access these properties directly from the processInstance parameter:

public async Task ExecuteActionAsync(string name, ProcessInstance processInstance,    WorkflowRuntime runtime, string parameter, CancellationToken token){    // Identification    var processId = processInstance.ProcessId;    var schemeCode = processInstance.SchemeCode;    var tenantId = processInstance.TenantId;    // Current position    var currentActivity = processInstance.CurrentActivityName;    var currentState = processInstance.CurrentState;    // Execution context    var executingActivity = processInstance.ExecutedActivity?.Name;    var executingTransition = processInstance.ExecutedTransition?.Name;    var triggeredBy = processInstance.ExecutedTimer ?? processInstance.CurrentCommand;    // Identity    var userId = processInstance.IdentityId;    Console.WriteLine(        $"Process {processId} ({schemeCode}, tenant {tenantId}): at {currentActivity}," +        $" state {currentState}, triggered by {triggeredBy}");}

To read properties from application code outside actions, load the process instance through WorkflowRuntime:

var processInstance =    await runtime.GetProcessInstanceAndFillProcessParametersAsync(processId);string activityName = processInstance.CurrentActivityName;string stateName = processInstance.CurrentState;

Process instance and scheme

A scheme is the blueprint; a process instance is an execution based on that blueprint. Workflow Engine creates many process instances from the same scheme, each tracking its own state independently. When the scheme is updated, existing instances continue running against the scheme version they started with, and can be migrated to a new version on demand.

Accessing the scheme from a process instance

Every process instance holds a reference to its scheme definition. Use this to inspect the scheme's activities, transitions, and other elements at runtime:

// Access the scheme from the process instancevar scheme = processInstance.ProcessScheme;// List all activitiesList<ActivityDefinition> activities = scheme.Activities;// Find the initial activityActivityDefinition initial = scheme.InitialActivity;// Find a specific activity by nameActivityDefinition review = scheme.FindActivity("Review");// List all transitionsList<TransitionDefinition> transitions = scheme.Transitions;// Find a specific transitionTransitionDefinition transition = scheme.FindTransition("ApproveReview");

Accessing current state through WorkflowRuntime

Without loading the full process instance, query the current state directly:

// Quick queries without loading the full instancestring activityName = await runtime.GetCurrentActivityNameAsync(processId);string stateName = await runtime.GetCurrentStateNameAsync(processId);ProcessStatus status = await runtime.GetProcessStatusAsync(processId);

See also

• Scheme

  A scheme defines the blueprint that each process instance follows.

• Activity

  Activities are the stable states where a process instance waits.

• Command

  Commands move a process instance from one activity to another.

• Process Logs

  Process logs record events scoped to a single process instance.

Frequently asked questions

What is a process instance in Workflow Engine?

A process instance is one execution of a scheme, created by Workflow Engine for a specific business process. Each instance has its own current activity, parameter values, and transition history, and is persisted independently in the database.

How do I create a process instance in Workflow Engine?

Create a process instance by calling CreateInstanceAsync with a scheme code and a unique identifier. Workflow Engine positions the new instance at the initial activity defined in the scheme and persists it to the database. You can also provide initial parameter values to set business data at creation time.

Can a process instance move backwards to a previous activity?

A process instance can move backwards only if a transition to that previous activity exists in the scheme. If no transition leads back to the target activity, the instance cannot move there through normal execution. You can, however, set the process instance to a specific state if the target activity is configured to accept direct state changes.

How do I get the current activity of a process instance from application code?

Call runtime.GetCurrentActivityNameAsync(processId) for the activity name, or load the full instance with runtime.GetProcessInstanceAndFillProcessParametersAsync(processId) and read processInstance.CurrentActivity or processInstance.CurrentState.

What is the difference between CurrentState and ExecutedActivityState?

CurrentState is the last recorded business state. It remains unchanged until the process completes a transition to an activity with a different state. ExecutedActivityState is the state of the activity whose actions are currently executing. During action execution, these can differ.