Customization
Without customization, the Visual Designer and runtime offer a fixed set of activity types, input controls, and condition options. They work for any domain but are not tailored to yours - activity types use generic names, input fields are plain text boxes, and autocomplete suggestions know nothing about your business terms.
Customization lets you keep the standard components while adapting them to your domain: register custom activity types that appear in the Designer palette, provide autocomplete suggestions for your business terms, replace plain text fields with domain-specific controls, and change the Designer's look and feel to match your brand.
With customization, you can give the Designer your application's look and feel, replace a generic text input with a user picker dropdown, and provide autocomplete suggestions for your domain terms so business analysts can write conditions without learning C#.
What it is
Think of a car dashboard. The manufacturer offers a standard layout and controls, but you can swap the radio for a touchscreen, change the gauge colors, and add a GPS unit. The dashboard stays the same shape and works the same way - you customize the parts that matter to you.
The Visual Designer exposes extension points that let you change how it looks and behaves without touching its source code. You configure these customizations when you initialize the Designer in your application.
The main extension points are CSS and template overrides for visual appearance, parameter format providers for custom input controls, autocomplete providers for domain-specific suggestions, action and rule providers for Designer selection lists, custom activity types that appear in the Designer palette, and custom condition types for transitions. Each extension point is opt-in - you customize only what you need and leave the defaults for everything else.
For developers: Implement IDesignerParameterFormatProvider to register custom input controls. Implement IDesignerAutocompleteProvider to supply domain-specific suggestions. Implement IWorkflowActionProvider to register actions and conditions, and implement IWorkflowRuleProvider to register rules. The names returned by GetActions(), GetConditions(), and GetRules() appear in the corresponding Designer lists. Implement ICustomActivityProvider to add custom activity types to the Designer palette. Implement ICustomConditionProvider to register custom condition types. Register providers with WorkflowRuntime.WithDesignerParameterFormatProvider(), WorkflowRuntime.WithDesignerAutocompleteProvider(), WorkflowRuntime.WithActionProvider(), WorkflowRuntime.WithRuleProvider(), or WorkflowRuntime.WithCustomActivities(). Custom styles are applied through CSS overrides at Designer initialization. Plugins that implement these interfaces are auto-detected and registered by WithPlugin().
Why it matters
Customization delivers these outcomes:
- Custom logo watermark - Add your company logo to the Designer canvas. Configure
settings.logowith an image URL andsettings.logoPositionto place it in any corner (top-left,top-right,bottom-left,bottom-right). The logo renders as a watermark on the scheme canvas. - On-brand user experience - Override CSS classes (
.WorkflowDesignerContainer,.WorkflowDesignerToolbar, and others) to apply your theme, color palette, and typography to the Designer so users do not perceive it as a separate tool. - Domain-specific input controls - Replace generic text fields with controls that match your domain. A cost-center selector instead of a free-text field, a user picker instead of a text input for assignee selection, a date range picker for deadline configuration.
- Business-user-friendly condition editing - Provide autocomplete suggestions for domain terms like department names, document types, or approval thresholds. Business analysts write conditions without knowing C# or the underlying parameter names.
- Custom activity types and conditions - Add custom activity types that appear in the Designer palette, and custom condition types that scheme designers can use on transitions. Both are registered through provider interfaces and auto-detected by plugins. Action and rule providers separately supply the action, condition, and rule names shown in Designer lists.
Who it is for
Evaluator (CEO, CTO, PM): Customization means the Designer feels like part of your product, not a third-party tool bolted on. Business users work with terms they already know, and the look matches your brand's design system.
Developer: Register custom providers at Designer initialization. The IDesignerParameterFormatProvider, IDesignerAutocompleteProvider, ICustomActivityProvider, and ICustomConditionProvider interfaces are simple - implement one or two methods and register the instance. Use IWorkflowActionProvider and IWorkflowRuleProvider with WithActionProvider() and WithRuleProvider() to supply executable Designer choices. CSS overrides go in a stylesheet you load alongside the Designer component. Plugins that implement these interfaces register them automatically through WithPlugin(). See the Customization Overview for the full API.
Enterprise architect: Each application instance can have its own set of customization providers. Two different teams embedding the Designer can configure different parameter controls and autocomplete sources without affecting each other. Customizations are scoped per WorkflowRuntime instance.
When to use it
Use customization when the Designer's default appearance or input controls do not match your application's requirements. Typical examples:
- Brand-aligned process designer - Your SaaS product embeds the Designer for customers to build their own workflows. The Designer must match your product's theme, not the Workflow Engine default look. Apply CSS overrides at Designer initialization.
- User picker for assignee fields - A workflow for a healthcare application needs a "Doctor" selector that queries the hospital's directory service. Implement
IDesignerParameterFormatProviderto register a custom user-picker control. - Simplified approval conditions - Business analysts configure approval routing without C#. Implement
IDesignerAutocompleteProviderto supply terms like "ApprovalLimit", "DepartmentHead", and "BudgetCode" as autocomplete candidates in the condition editor. UseIWorkflowActionProviderandIWorkflowRuleProviderwhen actions, conditions, and rules must be selected from lists. - Custom activity palette - A document review workflow needs a "Signature" activity type that is not part of the default palette. Implement
ICustomActivityProviderto register it, and it appears in the Designer alongside built-in activity types.
How it compares
The following table compares the Workflow Engine customization approach with the alternative of forking the Designer source code.
| Approach | What it requires | Result |
|---|---|---|
| Fork and modify the Designer source | Maintain a fork, track upstream changes, rebuild on every update | High maintenance cost, risk of divergence from upstream, complex upgrade path |
| Workflow Engine customization | Configure CSS, implement one or two provider interfaces, register at initialization | No fork to maintain, updates are non-breaking, customize only what you need |
The CSS and provider-based approach means you stay on the main Designer release while tailoring what matters to your users. New Designer features arrive with upgrades automatically.
Frequently asked questions
What parts of the Designer can I customize without modifying its source code?
You can customize the logo watermark (settings.logo and settings.logoPosition), CSS styles (toolbox, canvas, activity shapes, property panels), parameter input controls (via IDesignerParameterFormatProvider), autocomplete suggestions (via IDesignerAutocompleteProvider), custom activity types (via ICustomActivityProvider), and custom condition types (via ICustomConditionProvider). IWorkflowActionProvider and IWorkflowRuleProvider also populate the action, condition, and rule selection lists. You cannot change the scheme logic, serialization format, activity behavior, or runtime execution through the Designer.
How do I register a custom parameter control?
Implement IDesignerParameterFormatProvider which has a single method: GetFormat(CodeActionType type, string name, string schemeCode). Register it with WorkflowRuntime.WithDesignerParameterFormatProvider(). The Designer calls your provider when it needs to render a parameter input in the activity property panel.
Does each application instance get its own set of customizations?
Yes. Customization providers are registered per WorkflowRuntime instance. Two applications embedding the Designer in different parts of your system can use different providers, different styles, and different autocomplete sources - independently configured.
Can plugins add custom Designer providers?
Yes. The ActiveDirectoryPlugin ships with ActiveDirectoryDesignerParameterFormatProvider and ActiveDirectoryDesignerAutocompleteProvider implementations that register user and group selectors from Active Directory. Plugins register providers through WorkflowRuntime.WithDesignerParameterFormatProvider() just like application code.
What happens during Designer upgrades - do customizations break?
Provider interfaces (IDesignerParameterFormatProvider, IDesignerAutocompleteProvider) follow semantic versioning within Workflow Engine. CSS class names may change between major versions but are stable within a major version. Review the upgrade notes for CSS changes before each major upgrade.