# Plugins

Plugins extend [WorkflowRuntime](https://docs.workflowengine.io/get-started/concepts/workflow-runtime/) with pre-built
[actions](https://docs.workflowengine.io/get-started/concepts/action/), [rules](https://docs.workflowengine.io/get-started/concepts/rule/), and custom
[activities](https://docs.workflowengine.io/get-started/concepts/activity/). Instead of writing custom
[IWorkflowActionProvider](https://api.workflowengine.io/core/OptimaJet.Workflow.Core.Runtime/IWorkflowActionProvider/)
or [IWorkflowRuleProvider](https://api.workflowengine.io/core/OptimaJet.Workflow.Core.Runtime/IWorkflowRuleProvider/)
implementations for common patterns like HTTP requests, approval cycles, or LDAP integration, you register a plugin with
a single method call and assign its capabilities in your workflow schemes. Start with the [Basic Plugin](https://docs.workflowengine.io/plugins/basic-plugin/)
to get common actions and rules out of the box.

The registration snippets below omit the required base runtime setup. Complete
[Workflow Runtime configuration](https://docs.workflowengine.io/get-started/concepts/workflow-runtime/) before calling `StartAsync()`.

```csharp
// Required builder, persistence provider, and other base runtime setup are omitted.
var runtime = new WorkflowRuntime()
    .WithPlugin(new BasicPlugin());

await runtime.StartAsync();
```

## How plugins work

A plugin is a class that implements
[IWorkflowPlugin](https://api.workflowengine.io/core/OptimaJet.Workflow.Plugins/IWorkflowPlugin/).
When you call `runtime.WithPlugin(plugin)`, the runtime inspects which provider
interfaces the plugin also implements and registers each one automatically.
A single plugin can provide any combination of:

| Interface | What it adds |
|-----------|-------------|
| [IWorkflowActionProvider](https://api.workflowengine.io/core/OptimaJet.Workflow.Core.Runtime/IWorkflowActionProvider/) | [Actions](https://docs.workflowengine.io/get-started/concepts/action/) for activities and conditions for transitions |
| [IWorkflowRuleProvider](https://api.workflowengine.io/core/OptimaJet.Workflow.Core.Runtime/IWorkflowRuleProvider/) | [Rules](https://docs.workflowengine.io/get-started/concepts/rule/) for command authorization |
| [ICustomActivityProvider](https://api.workflowengine.io/core/OptimaJet.Workflow.Core.Runtime/ICustomActivityProvider/) | Custom activity types (gateways, events, tasks) |
| [ICustomConditionProvider](https://api.workflowengine.io/core/OptimaJet.Workflow.Plugins.CustomWorkflowProviders/ICustomConditionProvider/) | Custom condition types registered with `runtime.WithCustomConditions()` |
| [IDesignerParameterFormatProvider](https://api.workflowengine.io/core/OptimaJet.Workflow.Core.Runtime/IDesignerParameterFormatProvider/) | Parameter UI definitions for the Designer |
| [IDesignerAutocompleteProvider](https://api.workflowengine.io/core/OptimaJet.Workflow.Core.Runtime/IDesignerAutocompleteProvider/) | Autocomplete suggestions in the Designer |
| [IWorkflowExternalParametersProvider](https://api.workflowengine.io/core/OptimaJet.Workflow.Core.Runtime/IWorkflowExternalParametersProvider/) | External parameter storage on process instances |

The runtime registers the provider interfaces it detects, adds the plugin to its plugin list, and then calls
[OnPluginAdd][api-on-plugin-add] for plugin-specific handlers, build steps, or other setup. The
[OnRuntimeStartAsync][api-on-runtime-start] method is called when the runtime starts. Built-in plugins expose their capabilities through
the corresponding provider interfaces listed above.

### Register plugins

Register plugins after configuring the runtime and before calling `runtime.StartAsync()`. You can register multiple
plugins and optionally restrict them to specific schemes.

```csharp
var basicPlugin = new BasicPlugin();
var approvalPlugin = new ApprovalPlugin();

// Required builder, persistence provider, and other base runtime setup are omitted.
var runtime = new WorkflowRuntime()
    .WithPlugin(basicPlugin)
    .WithPlugin(approvalPlugin);

// Or restrict plugins to specific schemes:
// runtime.WithPlugin(basicPlugin,
//     schemes: ["OrderProcess", "InvoiceApproval"]);

await runtime.StartAsync();
```

Retrieve a registered plugin at any time with `runtime.GetPlugin<BasicPlugin>()`.

## Available plugins

Workflow Engine ships 8 built-in plugins that cover the most common workflow patterns.

### Actions and rules

Plugins that add actions, conditions, and rules.

- [Basic Plugin](https://docs.workflowengine.io/plugins/basic-plugin/): HTTP requests, email, independent process creation, subprocess checks and cleanup, parameter manipulation, and role-based authorization. Register this plugin to add these capabilities.
- [Approval Plugin](https://docs.workflowengine.io/plugins/approval-plugin/): Approval history with per-identity inbox tracking and derived outbox summaries.
- Loops Plugin: Foreach and counted loop constructs with break/continue state management.

### Integration

Plugins that connect Workflow Engine to external systems.

- File Plugin: File and directory operations, ZIP compression, and FTP transfers.
- Forms Plugin: External form builder integration with automatic parameter binding per activity. Requires license.
- Active Directory Plugin: LDAP group resolution for rule-based command authorization. Requires license.
- Real-Time Tracking Plugin: SignalR-based live process state notifications to browser clients.

### Notation

Plugins that add support for standard process notation.

- BPMN Plugin: BPMN 2.0 custom activity types and diagram import into native schemes. Requires license.

## Choose a plugin

Use this table to find the right plugin for your task.

Table: Plugin selection guide

| I need to...                                   | Plugin                                                         |
| ---------------------------------------------- | -------------------------------------------------------------- |
| Send HTTP requests or emails during process execution | [Basic Plugin](https://docs.workflowengine.io/plugins/basic-plugin/)                          |
| Create independent process instances or manipulate parameters | [Basic Plugin](https://docs.workflowengine.io/plugins/basic-plugin/)              |
| Check child subprocess completion or delete child subprocesses | [Basic Plugin](https://docs.workflowengine.io/plugins/basic-plugin/)            |
| Restrict commands to specific roles or users   | [Basic Plugin](https://docs.workflowengine.io/plugins/basic-plugin/)                          |
| Track approval history and identity worklists  | [Approval Plugin](https://docs.workflowengine.io/plugins/approval-plugin/)                    |
| Iterate over a list of values in a loop        | Loops Plugin                          |
| Work with files, directories, ZIP archives, or FTP | File Plugin                         |
| Display forms at specific workflow stages      | Forms Plugin                          |
| Resolve user roles from Active Directory       | Active Directory Plugin    |
| Push real-time updates to browser clients      | Real-Time Tracking Plugin |
| Import BPMN 2.0 diagrams into schemes          | BPMN Plugin                            |

## Plugin licensing

Table: License requirements per plugin

| Plugin                    | License                                      |
| ------------------------- | -------------------------------------------- |
| Basic Plugin              | Included in all editions                     |
| Approval Plugin           | Included in all editions                     |
| Loops Plugin              | Included in all editions                     |
| File Plugin               | Included in all editions                     |
| Real-Time Tracking Plugin | Included in all editions                     |
| Forms Plugin              | Requires a separate Forms license              |
| Active Directory Plugin   | Requires a separate Active Directory license   |
| BPMN Plugin               | Requires a separate BPMN license               |

Plugins that require a separate license throw an exception at registration if the license does not include the
feature.

## Frequently asked questions

**What is a plugin in Workflow Engine?**

A plugin is a class that implements `IWorkflowPlugin` and registers additional actions, rules, custom activities, or
designer extensions with WorkflowRuntime. You add a plugin by calling `runtime.WithPlugin(new MyPlugin())`. The runtime
auto-detects which provider interfaces the plugin implements and registers them automatically.

**How do I register multiple plugins?**

Call `runtime.WithPlugin()` for each plugin, or pass several plugins at once using `runtime.WithPlugins(schemes,
plugin1, plugin2)`. The `schemes` parameter is a `List<string>` of scheme codes that restricts the plugins to
only those schemes.

**Can I write my own plugin?**

Yes. Implement `IWorkflowPlugin` and optionally any provider interface the runtime detects. The runtime uses
type-pattern detection to register whichever of `IWorkflowActionProvider`, `IWorkflowRuleProvider`,
`IDesignerParameterFormatProvider`, `IDesignerAutocompleteProvider`, `ICustomActivityProvider`,
`ICustomConditionProvider`, or `IWorkflowExternalParametersProvider` your plugin implements. Implement only the
provider interfaces required by your plugin's capabilities.

**Do plugins require a license?**

Basic Plugin, Approval Plugin, Loops Plugin, File Plugin, and Real-Time Tracking Plugin are included in all editions.
Forms Plugin, Active Directory Plugin, and BPMN Plugin require a separate license.
Plugins that require a license throw an exception at registration if the license does not include the feature.

**What configuration do plugins need?**

Most plugins take configuration through constructor parameters or public properties set before registration. The
`PluginSettings` dictionary on `IWorkflowPlugin` is obsolete - use constructor-based configuration instead. Some plugins
require delegate functions to connect to your application's data layer, for example `UsersInRoleAsync` on BasicPlugin to
resolve role membership.

[api-on-plugin-add]: https://api.workflowengine.io/core/OptimaJet.Workflow.Plugins/IWorkflowPlugin/#method-onpluginadd-workflowruntime-list-string
[api-on-runtime-start]: https://api.workflowengine.io/core/OptimaJet.Workflow.Plugins/IWorkflowPlugin/#method-onruntimestartasync-workflowruntime