Designing Workflows
Designing Workflows defines the terms used to describe and create a workflow definition. Workflow is the general business concept; Scheme is the precise Workflow Engine artifact edited in Workflow Designer and built by Workflow Runtime before it creates a Process Instance.
Workflow definitions and elements
These terms distinguish the general business idea of a Workflow, its stored Workflow Engine definition, and the notation and content that describe the definition's structure, runtime behavior, and localized user-facing labels.
Workflow: A coordinated sequence of business work. Workflow is a useful general business word. In precise technical descriptions, Scheme identifies the definition and Process Instance identifies one execution.
Scheme: The canonical Workflow Engine name for the stored workflow definition containing Activities, Transitions, Commands, Parameters, and related configuration. Workflow definition and process definition are acceptable explanatory phrases in general prose. Scheme is the precise name of the Workflow Engine artifact and is unrelated to a database schema or an OpenAPI Schema.
Simple Process Notation: The native notation used to describe Workflow Engine Schemes. It can be represented in Scheme XML and shown visually by Workflow Designer. A Scheme Diagram can look like a flowchart, but flowchart is a comparison rather than the notation's official name. Simple Process Notation is not BPMN 2.0.
Scheme Code: The stable business identifier used to find a family of Scheme versions. Scheme Code is different from Scheme ID and Process ID.
Scheme ID: The unique identifier Workflow Builder assigns to a generated Scheme version stored for execution. It appears in code as ProcessDefinition.Id. Scheme Code remains stable across versions.
ProcessDefinition: The public .NET object that represents a Scheme in memory. Workflow Builder can create it from stored Scheme content, while the Programmatic Scheme Builder can create it directly in code.
Activity: A point in a Scheme that represents where a Process Instance is and what happens there. It can run configured Actions, and the Process Instance can remain at the Activity until a Transition moves it. An Activity may have a State, but Activity and State are different concepts. Related configuration terms include:
- Activity Implementation is the list of Actions configured to run during normal execution of an Activity. It is stored in Implementation. The separate PreExecutionImplementation list is used during Pre-Execution. An Activity Implementation is not a Custom Activity Type.
- Execution Timeout sets the time after which Workflow Runtime requests cancellation of normal Activity execution; it does not apply during Pre-Execution. The runtime does not forcibly stop the running work and waits for it to finish before it can apply the configured response, such as retrying or moving to another Activity or State. Work that does not respond to cancellation can therefore continue past the timeout. Its exact code name is ExecutionTimeout.
- Idle Timeout acts when a Process Instance waits too long at the Activity. Its exact code name is IdleTimeout.
- Activity Exception Handler defines a response to matching exceptions raised during normal Activity execution. In code, it is represented by ActivityExceptionsHandler and stored in ExceptionsHandlers.
Initial Activity: An Activity marked with IsInitial, where a new Process Instance begins. Initial Activity is not the same concept as the Initialized Process Status.
Final Activity: An Activity marked with IsFinal. Reaching a Final Activity can complete the normal process path. Final Activity is not the same concept as the Finalized Process Status.
State: An optional business label on an Activity. More than one Activity can use the same State, and an Activity can have no State. State is not the current Activity and is not the Process Status.
Annotation: Named metadata with a JSON value attached to an Activity or Transition. An Annotation describes the workflow model; it is not runtime data stored in a process Parameter.
Code Action: Executable C# code represented by CodeActionDefinition. A Scheme can store Code Actions in ProcessDefinition.CodeActions; Workflow Engine compiles and invokes them as Actions, Conditions, or Rules. Code Action does not mean every C# method called by the host application.
Localization: Translated display text for workflow elements, including States, Commands, command input labels, Actions, Conditions, Schemes, and Comments. An application can use these translations in its UI, and Workflow Designer can use them when displaying a Scheme. Scheme translations appear in ProcessDefinition.Localization; a host can also supply translations through ILocalizationProvider. Localization changes only the text shown to users; it does not rename the underlying Scheme elements, Process Parameters, or public code identifiers.
Parameters and data
Parameters carry data used by Process Instances. These terms distinguish where data is declared, how long it lives, whether Workflow Engine persists it, and whether it belongs to one Process Instance or a wider scope.
Parameter: Named data available during execution. An Explicit Parameter is declared in the Scheme; an Implicit Parameter exists at runtime without a Scheme declaration. Code can create one by setting an undeclared name; Persistence Provider can reconstruct one when stored data has no definition in the current Scheme, using UnknownParameterType. ParameterPurpose describes storage. DynamicParameter handles runtime-shaped data, not a Parameter purpose.
Persistence Parameter: A process Parameter with ParameterPurpose.Persistence. Workflow Runtime normally saves changes to it with the Process Instance when workflow progress is persisted. An Activity can be configured to skip that parameter save. A saved value can be restored for later work with the Process Instance.
Temporary Parameter: A process Parameter with ParameterPurpose.Temporary. It can be supplied to a Workflow Runtime operation or created by code while the Process Instance is in the Running status. It remains available from creation until the Process Instance leaves Running. The value exists only in memory: it is not persisted and is lost if the host application stops or crashes.
System Parameter: A process Parameter with ParameterPurpose.System. Workflow Engine owns the semantics and lifecycle of this runtime-managed value.
Global Parameter: Shared typed data stored outside one Process Instance through the persistence provider. Global Parameters can be shared across Schemes; tenant-aware APIs can also scope them to a tenant. A Global Parameter is not a process Parameter.
External Parameter: Process data whose value is read from and written to an application-owned store instead of Workflow Engine persistence, while Actions and Conditions still access it through the normal Process Instance Parameter API. The exact provider interface is IWorkflowExternalParametersProvider. External describes where the value is stored; it is not a ParameterPurpose value.
Workflow Designer and templates
Workflow Designer edits a Scheme definition and provides reusable Designer Templates for authoring. Interactive Designer uses the same editor to observe a running Process Instance instead of defining another notation or execution model.
Workflow Designer: The embeddable visual editor for creating and changing Schemes. The exact JavaScript class is WorkflowDesigner, and the package name is @optimajet/workflow-designer. Older material can call the same component Visual Designer or Workflow Engine Designer. The visual representation it edits is a Scheme Diagram, which depicts a definition rather than one running Process Instance.
Designer Template: A reusable Scheme fragment available on the Templates tab in Workflow Designer. Dragging a Designer Template onto the canvas copies its Activities, Transitions, and related Scheme content into the Scheme being edited. Designer XML template is a descriptive name for the same file-based fragment. The catalog is library.json, and the templatefolder setting can provide a custom catalog and XML files, making the library a Workflow Designer extension point. A Designer Template is inserted while authoring; it is not a Workflow Template expanded through build-time Scheme Inlining or an HTML template that renders the Workflow Designer interface.
Interactive Designer: A live observation mode that updates Workflow Designer as a Process Instance moves. It uses the Real-Time Tracking Plugin and is not another name for the normal design mode.
Scheme authoring and build pipeline
These terms distinguish creating a Scheme in C# from the runtime pipeline that builds Schemes regardless of how their source was authored.
Workflow as Code: The approach of creating or changing a Workflow Engine Scheme in C# rather than drawing it in Workflow Designer or writing its XML directly. The Programmatic Scheme Builder is the public API for this approach; Build Steps instead transform or validate definitions during runtime builds.
Programmatic Scheme Builder: The fluent C# API for creating or modifying a ProcessDefinition. Its exact public types are ProcessDefinitionBuilder and IProcessDefinitionBuilder. It is the main API used for Workflow as Code and is different from the runtime's Workflow Builder.
Workflow Builder: The runtime component that prepares a Scheme for execution. It creates and stores a built Scheme version when needed and reuses an existing stored or cached version when possible. Its exact public .NET class is WorkflowBuilder
Build Step: An ordered transformation or validation run by Workflow Builder when creating a built Scheme version. When a Scheme is saved, the pipeline runs on a copy to validate it and find Scheme Inlining dependencies. Loading an existing version skips it. Custom steps derive from BuildStep, receive a ProcessDefinition, and return a BuildStepResult.
Reuse and versioning
Reuse terms describe how one definition can include another, while versioning terms describe how stored definitions change over time and how those changes affect new or running Process Instances.
Process Versioning: The user-facing capability that lets existing Process Instances keep their current definition while newer instances use an updated definition.
Scheme Versioning: The storage and selection of multiple versions of a Scheme. Scheme Versioning is the technical mechanism behind Process Versioning and is unrelated to database schema versioning.
Scheme Update: An operation that moves an eligible running Process Instance to a newer Scheme version. Auto Scheme Update is the optional lazy form that can run before available Commands are returned; it requires the runtime setting and IsAutoSchemeUpdate on the current Activity. The same Activity flag normally gates an explicit UpdateSchemeIfObsoleteAsync call unless the call asks to ignore it. Scheme Update changes the definition used by a Process Instance; it is not a Workflow Engine package upgrade.
Workflow Templates: The user-facing feature name for reusable workflow fragments implemented through Scheme Inlining. A Workflow Template becomes part of one expanded ProcessDefinition; it is not a Designer starter Scheme or a template used to customize the Designer UI.
Scheme Inlining: A way to reuse one Scheme inside another. An Inline Activity in the parent Scheme refers to a reusable Scheme. When Workflow Builder prepares the parent, it includes the referenced Scheme in the parent definition. Everything then runs as one Process Instance; Scheme Inlining does not create a Subprocess.
- Inline Activity is the Activity that refers to the reusable Scheme.
- Inlinable Scheme, also called an Inline Scheme, is the Scheme being reused.
See also
These pages explain how the design terms work in the product.
- Workflow Engine Concepts connects the foundational model terms.
- Workflow Designer describes the visual editor.
- Process Versioning explains definition changes.
- Glossary overview links to the other terminology subjects.
Frequently asked questions
What is the difference between a Scheme and a Process Instance?
A Scheme is a stored definition. A Process Instance is one execution of it, identified by a Process ID. Process Status, timers, and history are separate persistence records.
What is the difference between an Activity and a State?
An Activity is a position in a Scheme. State is an optional business label on an Activity, so several Activities can share a State and an Activity can have no State.
Does Scheme Inlining create a Subprocess?
No. Scheme Inlining expands reusable Scheme content into one ProcessDefinition at build time. A Subprocess remains a separate persisted Process Instance with its own Process ID and Process Status, while its lifecycle is coordinated with its Parent Process and Root Process tree.