Basic Plugin Overview

Jevgenije Betin Updated 2026-08-10 18 min read 3,449 words

development plugins workflow Additional

Every workflow scheme needs basic operations - sending HTTP requests, notifying users by email, creating independent process instances, managing subprocesses, checking parameters, and restricting commands to specific roles. Without BasicPlugin, each of these requires a custom IWorkflowActionProvider or IWorkflowRuleProvider implementation. BasicPlugin solves this by registering actions, conditions, and rules with WorkflowRuntime through a single runtime.WithPlugin(new BasicPlugin()) call, so you assign actions to activities and conditions and rules to transitions without writing custom providers.

What BasicPlugin provides

BasicPlugin is included in OptimaJet.Workflow.Core and does not require a separate NuGet package or license. Once registered, its actions, conditions, and rules are available for use in workflow schemes.

In the Designer

When you select an activity in the Workflow Designer and open its Implementation section, the available actions appear in a dropdown. BasicPlugin registers its actions so they show up in this dropdown alongside code actions defined in the scheme. The same applies to Conditions in transition settings and Rules in actor restrictions - BasicPlugin populates the dropdown lists with its registered capabilities.

The Designer discovers registered actions, conditions, and rules through the IWorkflowActionProvider and IWorkflowRuleProvider interfaces at runtime. When you register a plugin, the runtime exposes its capabilities to the Designer API automatically - no additional configuration is needed.

BasicPlugin also implements ICustomActivityProvider. During plugin registration, it creates a custom activity type for each non-excluded synchronous and asynchronous action. The Designer API returns these types to the Elements panel, where they appear on the Activities tab. Adding one to the scheme creates an activity that invokes the corresponding BasicPlugin action at runtime; the values configured in its form are stored in the activity annotations. This provides an alternative to adding the same action manually in Implementation.

Available capabilities

Actions: send HTTP requests, send emails, create independent process instances, set parameters, remove parameters, set activity, set state, execute commands on other processes, delete subprocesses, fill approvers by users, fill approvers by roles, clear approvers.

Conditions: check all subprocesses completed, check HTTP request response, check approved by users, check approved by roles, check if process is finished, check if approval is complete, check parameter value, check if approvers exist.

Rules: approver-based authorization (Approver), role-based authorization (CheckRole), and application-defined actor authorization (Predefined).

The FillApproversRoles action, IsApprovedByRoles condition, and CheckRole rule require the UsersInRoleAsync delegate. When this delegate is not set, these capabilities are not registered and do not appear in the Designer dropdowns.

Predefined actors are registered in application code and use the built-in Predefined rule. WorkflowRuntime adds their actor definitions to each applicable scheme.

Register and configure BasicPlugin

Register BasicPlugin after completing the base WorkflowRuntime configuration and before calling runtime.StartAsync(). The shortened example below focuses only on BasicPlugin delegates and registration.

using Microsoft.Extensions.DependencyInjection;using OptimaJet.Workflow.Core.Runtime;using OptimaJet.Workflow.Plugins;public class WorkflowInit{    public async Task<WorkflowRuntime> CreateRuntimeAsync(        IServiceProvider services)    {        // --- Required: create the plugin (no delegates needed) ---        var basicPlugin = new BasicPlugin();        // --- Optional: pick the features you need, remove the rest ---        // Feature: role-based authorization        // Required for: CheckRole rule, FillApproversRoles action,        //               IsApprovedByRoles condition        var userRepository = services.GetRequiredService<IUserRepository>();        basicPlugin.UsersInRoleAsync = async (role, processInstance) =>        {            var users = await userRepository.GetUsersInRoleAsync(role);            return users.Select(u => u.Id.ToString());        };        // Feature: approval stages        // Required for: FillApproversUsers with        //               GetUsersFrom = FromApproversInStage        var approvalService = services.GetRequiredService<IApprovalService>();        basicPlugin.ApproversInStageAsync = async (stage, processInstance) =>        {            var approvers = await approvalService.GetApproversAsync(                processInstance.ProcessId, stage);            return approvers.Select(a => a.IdentityId);        };        // Feature: external state sync        // Called when process becomes Idled or Finalized        var documentService = services.GetRequiredService<IDocumentService>();        basicPlugin.UpdateDocumentStateAsync = async (            processInstance, stateName, localizedStateName) =>        {            await documentService.UpdateStateAsync(                processInstance.ProcessId, stateName);        };        // --- Register and start ---        // Additional WorkflowRuntime configuration is required before startup.        var runtime = new WorkflowRuntime()            .WithPlugin(basicPlugin);        await runtime.StartAsync();        return runtime;    }}

How BasicPlugin integrates with the runtime

BasicPlugin subscribes to the OnProcessStatusChangedAsync runtime event. When a process transitions to Idled or Finalized status, and the UpdateDocumentStateAsync delegate is set, the plugin calls the delegate with the process instance, the current state name, and the localized state name. Use this to synchronize an external document status with the workflow state.

The subscription is scoped: if the plugin was registered with a schemes filter, only processes belonging to those schemes trigger the callback. Subprocesses are ignored.

Reference

The tables below summarize the workflow-scheme actions, conditions, rules, and common configuration properties registered by BasicPlugin. They are not a complete list of its public .NET members. See the BasicPlugin API reference for constructors, properties, methods, and fields.

Actions

BasicPlugin registers actions that you can assign to any activity in your workflow scheme.

SetActivity action

Sets the current activity of the process directly.

SetState action

Sets the process state string.

SetParameter action

Writes a value to a process parameter. With expression compilation enabled (the default), Value must contain a non-empty C# expression. To store an empty string, use the explicit C# string literal \"\" in the action JSON.

RemoveParameter action

Deletes a parameter from the process.

HTTPRequest action

Sends an HTTP GET or POST request and optionally stores the response.

SendEmail action

Sends an email using the configured SMTP settings.

CreateProcess action

Creates an independent process instance from the specified scheme and parameters. CreateProcess does not assign parent or subprocess metadata; fork transitions create child subprocesses.

ExecuteCommand action

Executes a command on another process instance.

FillApproversUsers action

Populates the approvers list with specific user IDs.

FillApproversUsers requires Separator at runtime when GetUsersFrom is FromParameters. The Designer supplies ,, but the action has no runtime default when the parameter is omitted. FromApproversInStage requires the ApproversInStageAsync delegate.

FillApproversRoles action

Populates the approvers list with users from roles.

Requires UsersInRoleAsync delegate.

DeleteSubprocesses action

Removes all subprocesses of the current process. No parameters.

ClearApprovers action

Keeps every identity in the Approvers parameter and resets each stored approval flag to false. It also sets ActivityWithApprovers to null. The action has no parameters.

Conditions

BasicPlugin registers conditions that evaluate to true or false and control whether a transition fires.

CheckParameter condition

Checks whether a process parameter matches a value using a comparison operator.

Supported CompareType values: Equal, NotEqual, Contains, StartWith, EndWith, NotContains, StartAndEndWith, NotStartWith, NotEndWith, NotStartAndEndWith, Greater, Less, GreaterOrEqual, LessOrEqual, In, NotIn.

CheckAllSubprocessesCompleted condition

Returns true when all subprocesses of the current process have completed.

CheckMode values: AllSubprocesses (only direct children), AllSubprocessesAndParent (includes parent process).

IsProcessFinish condition

Returns true when the process status is Finalized.

IsApprovedByUsers condition

Returns true when every specified user appears as ExecutorIdentityId or ActorIdentityId in at least one process-history item whose TransitionClassifier is not Reverse. The condition does not require the history item to use a command trigger.

IsApprovedByRoles condition

Resolves every specified role through UsersInRoleAsync, then returns true only when every resolved user appears as ExecutorIdentityId or ActorIdentityId in at least one process-history item whose TransitionClassifier is not Reverse. The condition does not require the history item to use a command trigger.

Requires UsersInRoleAsync delegate.

CheckHTTPRequest condition

Sends an HTTP request and compares the response against a condition.

IsApproveComplete condition

Reads the Approvers process parameter and returns its approval state. When RequiredApprovalsNumber is greater than 0, the condition returns true after at least that many stored flags become true. When the threshold is 0, every stored approver flag must be true. The condition has no parameters and does not track a separate response or rejection state.

CheckApproversExist condition

Returns true when the runtime resolves at least one participant identity from Allow restrictions on command-triggered transitions that match the selected activity and transition classifiers. Actor definitions alone are insufficient: a matching actor whose rule resolves no identities does not satisfy the condition.

TransitionClassifier accepts NotSpecified, Direct, and Reverse. Separate multiple values with a comma followed by one space.

Rules

BasicPlugin provides rules that restrict which identities can execute a command. Rules are referenced by actors, which are part of restrictions on transitions that have a command trigger. When a user executes a command, the runtime checks the restrictions on the matching transition by calling the rule provider to determine which identities satisfy the rule.

Approver authorizes the current identity only while it is present in the process's Approvers parameter with an approval flag of false. RuleGetApprovers calls GetAvailiableApprovers, which filters out identities whose flag is already true, so an approver who has already approved is no longer returned for authorization. The parameter is populated by FillApproversUsers or FillApproversRoles.

CheckRole checks whether the current identity belongs to a named role. This rule requires the UsersInRoleAsync delegate to resolve role membership from your application's data store. When UsersInRoleAsync is null, the CheckRole rule is not registered.

For Approver and CheckRole, create actors in the workflow scheme that reference the rule name, then add restrictions to command-triggered transitions that reference those actors.

Predefined actors

The Predefined rule authorizes actors registered in application code. WorkflowRuntime injects an actor definition for each applicable registration and uses the actor name as the rule parameter.

CheckPredefinedActorAsync determines whether one identity satisfies the predefined actor named by the rule parameter. GetPredefinedIdentitiesAsync returns all identity IDs that satisfy that actor. Configure both delegates when the application uses both identity checks and participant enumeration.

Predefined is excluded from ordinary Designer rule choices, but it remains registered for runtime execution. Runtime authorization uses the full rule catalog, including excluded rules, so the generated actor definitions can invoke Predefined.

When a transition has multiple Allow restrictions, the default AllowConcatenationType="And" requires the identity to satisfy every Allow rule. Set AllowConcatenationType="Or" on the transition to accept an identity that satisfies any Allow rule.

Configuration properties

Setting_DontCompileExpressions is obsolete and intended only for compatibility, but it still affects behavior. When set to true, SetParameter uses the action's string value without compiling it as an expression, and CreateProcess parses or deserializes parameter values instead of evaluating them as expressions.

See also

• HTTP Requests

  Call external APIs from your workflow and validate responses.

• Sending Emails

  Notify users at specific workflow stages via SMTP.

• Managing Subprocesses

  Check whether child subprocesses created by fork transitions have completed, or delete all child subprocesses during cleanup.

• Managing Parameters

  Store, delete, and branch on parameter values.

• Process Control

  Jump between activities and control process state.

• Parallel Approval

  Set up multi-user approval without explicit branches.

• Role-Based Authorization

  Restrict commands to users in specific roles.

Frequently asked questions

What does BasicPlugin add to Workflow Engine?

BasicPlugin adds actions, conditions, and rules to WorkflowRuntime. These cover common operations - HTTP requests, email, independent process creation, subprocess management, parameter manipulation, and role-based authorization - without writing custom action or rule providers.

Do I need to set all delegates on BasicPlugin?

No. Only set the delegates for the capabilities you use. If you do not use role-based authorization, leave UsersInRoleAsync unset and the CheckRole rule, FillApproversRoles action, and IsApprovedByRoles condition are excluded automatically.

Can I use BasicPlugin actions without its rules?

Yes. Actions and rules are independent. You can use SendEmail, HTTPRequest, or any other action without configuring any rule delegates.

How do I configure SMTP for the SendEmail action?

Set Setting_Mailserver, Setting_MailserverPort, Setting_MailserverFrom, Setting_MailserverLogin, Setting_MailserverPassword, and Setting_MailserverSsl on the BasicPlugin instance before registering it. The SendEmail action can also override these per-call.