Plugin System
The plugin system packages common workflow patterns as IWorkflowPlugin assemblies. Plugins auto-register actions, rules, custom activities, conditions, autocomplete, parameter formats, and external parameter providers with the runtime. Shipped plugins include Basic (HTTP, email), Approval, Loop, Files, Active Directory, and Real-Time Tracking. Custom plugins follow the same IWorkflowPlugin interface.
Without a plugin system, every common workflow pattern - sending an email, routing an approval chain, assigning a task to a user - requires hand-written action code in every project. Developers write the same HTTP client, the same approval logic, the same task inbox queries, project after project.
The plugin system is a set of pre-built workflow capabilities packaged as .NET assemblies that register with the runtime at startup. Each plugin provides ready-to-use activity types, actions, and conditions that you can add to any scheme in the Designer.
With the plugin system, you install a NuGet package (or reference the assembly), register the plugin with a single line of configuration, and use its activities in any process model. For example, installing the Approval plugin and adding the "Approval" activity to a scheme turns a linear flow into a multi-step approval chain - no code written.
What it is
Think of a plugin as a pre-assembled toolkit for a specific workflow pattern. Instead of building an approval system from scratch - writing activities, actions, conditions, and Designer configuration - you install the Approval plugin and its activities appear in the Designer palette, ready to drag onto a scheme. The runtime knows how to execute them because the plugin registered the behavior during startup.
The following plugins ship with Workflow Engine. Plugins marked as in-project live in the Core assembly; plugins marked as separate ship as independent NuGet packages.
| Plugin | Where it lives | What it provides |
|---|---|---|
| Basic | In OptimaJet.Workflow.Core | HTTP request action, email sending, subprocess invocation, basic conditions and rules |
| Approval | In OptimaJet.Workflow.Core | Multi-step approval chains with sequential and parallel review, approval history |
| Loop | In OptimaJet.Workflow.Core | For and ForEach loop patterns for repeating activities and subprocess iteration |
| Files | OptimaJet.Workflow.FilesPlugin | File upload, download, and attachment actions for process instances |
| Active Directory | OptimaJet.Workflow.ActiveDirectoryPlugin | User and group lookup from Active Directory for rule evaluation |
| Real-Time Tracking | OptimaJet.Workflow.RealTimeTrackingPlugin | Real-time process state updates via SignalR |
All plugins follow the same registration pattern:
runtime.WithPlugin(new BasicPlugin()) .WithPlugin(new ApprovalPlugin()) .WithPlugin(new RealTimeTrackingPlugin());Each call to WithPlugin triggers IWorkflowPlugin.OnPluginAdd, which calls the plugin to register its activity types, action providers, rule providers, custom conditions, autocomplete providers, and parameter format providers with the runtime. The runtime aggregates these capabilities, making them available to both the execution engine and the Designer API.
For developers: Every plugin implements IWorkflowPlugin, which defines Name, Disabled, OnPluginAdd(WorkflowRuntime, List<string>), and OnRuntimeStartAsync(WorkflowRuntime). The runtime auto-detects the plugin's capabilities when it implements any of these interfaces:
IWorkflowActionProvider- registers actions and conditions for use in schemesIWorkflowRuleProvider- registers actor and role resolution rulesICustomActivityProvider- registers custom activity types that appear in the Designer paletteICustomConditionProvider- registers custom condition types for transitionsIDesignerParameterFormatProvider- registers custom parameter format providers for Designer property panelsIDesignerAutocompleteProvider- registers autocomplete suggestions for code action editorsIWorkflowExternalParametersProvider- registers external parameter lookups for process parameters
The runtime auto-detects these interfaces during WithPlugin() and registers each with the corresponding With*Provider method. During OnPluginAdd, the plugin can perform additional setup. See the Basic Plugin reference for an example implementation.
Why it matters
The plugin system delivers these outcomes:
- No re-implementation of common patterns - Approval chains, email notifications, HTTP calls, and file attachments are ready-to-use. A project that needs purchase order approval installs the Approval plugin and configures the steps - no custom activity code.
- Consistency across projects - Every team uses the same tested implementation of approval routing, email sending, and subprocess invocation. The surface area of custom code shrinks to project-specific actions and rules only.
- Extensible by design - You can write your own plugins that follow the same registration pattern as the shipped plugins. Package custom activities, actions, and conditions as a reuse unit and share them across projects, teams, or tenants.
- Designer integration out of the box - When a plugin registers custom activities via
ICustomActivityProvider, the Designer displays them as palette elements with their own SVG templates, forms, and parameter editors. Business users can add plugin-provided activities to schemes without developer involvement.
Who it is for
Evaluator (CEO, CTO, PM): The plugin system means faster initial integration and less custom code to maintain. Common workflow patterns are tested by the Workflow Engine team and ship with the product. Time to first running workflow drops from days to hours - install, register, and model.
Developer: You interact with plugins through the IWorkflowPlugin interface and the runtime.WithPlugin() registration method. Shipped plugins work out of the box. Custom plugins follow the same pattern: implement the interface, register your providers in OnPluginAdd, and use the activities in any scheme. See the Basic Plugin implementation for a code example.
Enterprise architect: Plugins can be scoped per scheme - register a plugin with a scheme list and it only provides activities to those schemes. This prevents cross-scheme interference when two workflows use plugins that register activities with the same name. Plugin dependencies (such as Active Directory integration) are managed through standard NuGet package references.
When to use it
Use a plugin when your scheme needs a capability that the plugin provides. Typical examples:
- Adding approval workflows - Your scheme needs a review-and-approve step where multiple reviewers vote sequentially or in parallel. Install the Approval plugin and add approval activities to the scheme with configurable roles and thresholds.
- Integrating with external systems - A scheme needs to call an HTTP API, send an email, or create a file. Use the Basic plugin's HTTP action or the Files plugin's upload/download actions instead of writing custom action code.
- Looking up identity sources - Scheme rules need to resolve users and groups from Active Directory. Register the Active Directory plugin as the rule provider, and scheme designers can reference AD groups directly in rule definitions.
- Building custom extensions as packages - You have a reusable pattern across multiple projects (for example, a credit-check subprocess with custom activities and rules). Package it as an
IWorkflowPluginassembly, distribute via NuGet or file share, and register withruntime.WithPlugin().
How it compares
The following table compares the Workflow Engine plugin system with the alternative of building every workflow pattern from scratch.
| Approach | What it requires | Result |
|---|---|---|
| Build every pattern from scratch | Write custom activities, actions, conditions, Designer forms, and SVG templates for each pattern. Write and maintain tests for all of them. | High initial cost. Ongoing maintenance across every project. Duplicate implementations of the same patterns. |
| Workflow Engine plugin system | Install a plugin package, register with runtime.WithPlugin(), and use the activities in the Designer. | Hours to integrate. Single maintained implementation per pattern. Activities available to any scheme immediately. |
Frequently asked questions
What plugins does Workflow Engine ship, and are they all included with the base license?
The Basic, Approval, and Loop plugins are part of the Core package (WorkflowEngine.NETCore-Core) and do not require a separate license. The Active Directory and Files plugins are separate packages that may have their own licensing terms. See Workflow Engine Editions for per-plugin license mapping.
How do I register a plugin with the runtime?
Call runtime.WithPlugin(instance) during initialization, where instance is an object implementing IWorkflowPlugin. For example: runtime.WithPlugin(new ApprovalPlugin()). The call must happen before runtime.Start(). See the WorkflowRuntime setup page for the complete configuration chain.
Can I write my own plugin?
Yes. Implement IWorkflowPlugin in a class. In OnPluginAdd, register custom activities, action providers, rule providers, and other capabilities with the runtime. Package the assembly as a NuGet package or distribute as a project reference.
Can I load plugins from an external DLL without recompiling?
Yes. Use Assembly.LoadFrom() to load the external assembly, find types implementing IWorkflowPlugin, instantiate each, and call runtime.WithPlugin(). The runtime auto-detects the plugin's capabilities - action providers, rule providers, custom activities, and conditions - and integrates them into the Designer and execution engine.
Can I restrict a plugin to specific schemes?
Yes. WithPlugin accepts an optional list of scheme codes. When provided, the plugin's activities, actions, and rules are only available in the specified schemes. This prevents name collisions when two plugins register activities with the same type name.