Offline API
Without the Offline API, computing the approval map for a process instance or executing a sequence of commands requires multiple round-trips to the runtime, checking available commands for each step, and handling errors one at a time. For client applications that need to present a complete picture of what can happen next - or execute a chain of commands without re-querying after each one - this adds complexity and latency.
The Offline API groups these operations into batch calls. Given a process instance or scheme, it computes the full map of available transitions for each activity. Given a list of commands, it executes them in sequence and returns results for all of them.
What it is
The Offline API is a set of methods on WorkflowRuntime.OfflineApi that work with process schemes and commands in bulk. It has two capabilities:
- Approval mapping - given a process scheme or a running instance, returns a dictionary of all activities and their available transitions. For a running instance, it also marks which activity is the current position and filters transitions by the user's authorization.
- Batch command execution - given a list of commands (optionally grouped by process ID), executes them in order and returns the result of each one. If one command fails, the remaining commands in that chain are skipped with an error message, preserving the transactional semantics of a command sequence.
These methods compute results using the current scheme definition and process state. They do not require a persistent connection to a specific runtime node - hence the name "Offline API."
For developers: access the API through runtime.OfflineApi. Two method groups are available, described below.
Approval map
Use GetApprovalMapAsync to get the complete transition structure for a process:
// Get the approval map by scheme definitionvar scheme = await runtime.Builder.GetProcessSchemeAsync("OrderApproval");var mapByScheme = await runtime.OfflineApi.GetApprovalMapAsync(scheme);// Get the approval map for a running instance, filtered for a specific uservar processInstance = await runtime.GetProcessInstanceAndFillProcessParametersAsync(processId);var mapForUser = await runtime.OfflineApi.GetApprovalMapAsync(processInstance, "user-42");// Each entry in the result maps an activity name to its details and transitionsforeach (var entry in mapForUser){ var activityName = entry.Key; var activity = entry.Value; Console.WriteLine($"{activity.Activity}: {activity.Transitions.Count} transitions available");}The map is a Dictionary<string, ActivityDto>. Each ActivityDto contains a list of TransitionDto objects describing the transitions available from that activity. For the instance-based overload, transitions are filtered by the user's authorization rules, and IsCurrent is set to true on the activity where the process currently is.
Batch command execution
Use ExecuteSomeCommandsAsync to execute several commands in one call:
var commands = new List<Command>{ new Command("Approve", "user-42", DateTime.UtcNow, processId), new Command("Submit", "user-42", DateTime.UtcNow, processId),};var results = await runtime.OfflineApi.ExecuteSomeCommandsAsync(commands);foreach (var result in results){ Console.WriteLine($"Command '{result.CommandName}': success={result.WasExecuted}");}The commands are grouped by ProcessId internally and executed in order by DateTime within each group. If a command fails (for example, the transition is not available), the remaining commands in that process group are skipped with a descriptive error. This prevents a broken command chain from leaving the process in an unexpected state.
Why it matters
The Offline API delivers these outcomes:
Single-call approval map - Build a complete picture of what a user can do at each step of a process with one API call. No need to loop through activities querying available commands one by one.
Atomic command sequences - Execute a chain of commands with automatic ordering and failure isolation. If one step fails, the remaining steps in that process group are skipped without affecting other groups.
Scheme-level inspection - The
GetApprovalMapAsync(ProcessDefinition, ...)overload works with an in-memory scheme definition, no database or running instance needed. Use it for reporting, analysis, or UI building without loading process data.Reduced round-trips - Batch operations replace multiple individual calls with one request, cutting latency and simplifying client-side error handling.
Who it is for
Evaluator (CEO, CTO, PM): The Offline API enables client applications to present the full workflow structure in a single call, reducing UI complexity and improving responsiveness.
Developer: Call GetApprovalMapAsync on runtime.OfflineApi to get the full transition map for a scheme or a running instance. Use ExecuteSomeCommandsAsync to execute a sequence of commands in one batch. Each result includes the command name, success status, and error message on failure.
Enterprise architect: The Offline API's scheme-based overload works with parsed definitions, making it suitable for read-only analytics and reporting services that inspect process structure without connecting to a running runtime node.
When to use it
Use the Offline API when you need to work with process structure or commands in a batch-oriented way:
- Displaying an approval flow UI - a client application shows the user all activities and transitions available in the process. Call
GetApprovalMapAsynconce to build the complete map instead of querying available commands activity by activity. - Executing a predefined command sequence - a background job or script needs to advance a process through several known states. Use
ExecuteSomeCommandsAsyncwith the full list; the API handles ordering, error isolation, and chain termination. - Computing process structure offline - a reporting or analytics tool loads a scheme definition and inspects its transition graph without connecting to a running runtime instance. The scheme-based overload of
GetApprovalMapAsyncworks with any loadedProcessDefinition.
How it compares
Below is how the Offline API compares to the alternative of querying available commands one by one.
| Approach | What it requires | Result |
|---|---|---|
| Query available commands one by one | Call GetAvailableCommandsAsync for each activity. Loop through transitions manually. Handle errors per command. | Multiple round-trips. Manual error handling. No built-in chain semantics. |
| Workflow Engine Offline API | One call to GetApprovalMapAsync for the full transition map. One call to ExecuteSomeCommandsAsync for batch execution. | Single call for the complete map. Automatic ordering, filtering, and chain termination on failure. |
Frequently asked questions
What is the Offline API in Workflow Engine?
The Offline API is a set of batch-oriented methods on WorkflowRuntime.OfflineApi. It provides two capabilities: computing the approval map (all activities and their available transitions for a scheme or a running instance) and executing multiple commands in sequence with automatic error handling.
Does the Offline API work without a database connection?
No. The Offline API requires access to the persistence store through the runtime, just like any other runtime API call. It processes data in batch rather than requiring a transaction per operation, but it is not a disconnected or network-offline mode.
How does GetApprovalMapAsync handle authorization?
The instance-based overload accepts an identityId parameter. It filters transitions by calling the runtime's authorization rule executor, so only transitions the specified user is allowed to execute appear in the result.
What happens when ExecuteSomeCommandsAsync fails mid-sequence?
Commands are grouped by ProcessId and sorted by DateTime. Within each group, execution stops at the first failure. The failed command and all remaining commands in that group get an error result with the failure message. Commands for other process IDs are unaffected.