Attachable Forms
Attachable Forms bind form definitions to workflow activities through the FormsPlugin. Each activity renders the correct form with fields mapped to process parameters. The plugin manages form versions, draft persistence, and command execution through FormsRuntimeApi. Forms can be versioned independently of process schemes, and each form version is stored in the persistence provider alongside process data.
Without attachable forms, you build a custom data entry screen for every activity in every workflow scheme. An expense report with three approval steps needs three different UIs, each hardcoded to that step's fields. Adding a step means building another UI and redeploying.
Attachable forms is a plugin system that ties form definitions to workflow activities so that each activity renders the right form, with fields mapped to process parameters, without custom UI code per step.
With attachable forms, you can define a form once on each activity in the scheme and have your application render it automatically. For example, an expense approval workflow defines an "Expense Details" form on the submit activity, a "Manager Review" form on the approval activity, and a "Finance Approval" form on the final sign-off - each with fields mapped to process parameters, each served by the runtime without per-activity UI code.
What it is
Think of an airport departure board. Each gate shows the right flight information for that gate - passengers at gate A see gate A's flight details, passengers at gate B see gate B's. Attachable forms work the same way: each activity in a workflow scheme has its own form definition, and when a process instance reaches that activity, the runtime surfaces the correct form for that step.
The Forms Plugin adds a "Show Form" custom activity type to the Designer. When you add this activity to a scheme, you configure which form it should display, which process parameters the form reads from and writes to, and which commands (approve, reject, submit) the form should expose. Form definitions are stored in the database through the IFormDataProvider persistence interface - the same provider that stores schemes and process instances.
On the frontend, your application calls the FormsRuntimeApi to discover which forms are available for the current activity, retrieve the form definition, and submit filled forms back. The plugin handles parameter mapping, draft persistence, and command execution.
For developers: Install the WorkflowEngine.NETCore-FormsPlugin NuGet package. Create a FormsPluginSettings instance (requires the FormsManagerUrl pointing to your form manager frontend) and register FormsPlugin with WorkflowRuntime:
var formsSettings = new FormsPluginSettings{ FormsManagerUrl = "https://forms.example.com"};runtime.WithPlugin(new FormsPlugin(formsSettings));Use FormsRuntimeApi to interact with forms at runtime: GetFormAsync() to load a form definition, GetExecutableFormsAsync() to discover forms available for the current activity, SaveFormAsync() to persist draft data, and ExecuteFormAsync() to submit form data and execute the associated command. Forms use versioned definitions stored via IFormDataProvider.
Why it matters
Attachable forms deliver these outcomes:
- No per-activity UI code - Define forms on activities in the Designer instead of building custom screens for workflow steps that need user input. The runtime surfaces the right form automatically.
- Forms evolve with schemes - Change a form definition or add a new activity with its own form without redeploying your application. The Designer stores form versions, and the plugin resolves the current version at runtime.
- Parameter mapping is built in - Form fields map directly to process parameters. Submit a form and the runtime writes field values to parameters and executes the associated command in one operation.
- Draft support out of the box - The plugin manages draft data per form and per activity. A user can start filling a form, save progress, and return later without losing data.
Who it is for
Evaluator (CEO, CTO, PM): Attachable forms remove the bottleneck of building custom UIs for workflow steps that need user input. Your team designs forms in the Designer alongside the process flow, not in a separate frontend sprint.
Developer: Create a FormsPluginSettings with the FormsManagerUrl, register FormsPlugin with WorkflowRuntime, and add the "Show Form" custom activity in schemes. Call FormsRuntimeApi methods from your frontend to fetch forms, save drafts, and submit data. No controller code per form is needed.
Enterprise architect: Forms are stored as versioned definitions in the same persistence provider as process data. The plugin integrates with the runtime's existing rule provider for permission checks on form field access and command execution.
When to use it
Use attachable forms when some activities in your workflow need user input and you want the form-to-activity mapping managed by the runtime instead of hardcoded in your application. Typical examples:
- Structured approval workflows - An expense report shows an "Expense Details" form at submission, a "Manager Review" form at approval, and a "Finance Approval" form at final sign-off. Each form has different fields and different associated commands.
- Onboarding sequences - A new employee onboarding workflow shows a "Personal Details" form, then a "Department Setup" form, then an "IT Access Request" form - each at a different activity in the same scheme.
- Case management - A customer support workflow presents different forms depending on the case type. The scheme routes to the appropriate activity, and the plugin resolves the form definition for that activity.
- Multi-version form deployments - Update a form definition while instances are running. Previous instances use the form version that was current when they reached the activity; new instances use the updated version.
How it compares
The table below shows the tradeoffs between the Workflow Engine approach and the alternative.
| Approach | What it requires | Result |
|---|---|---|
| Build custom UIs per activity | Build, test, and deploy a separate data entry screen for every workflow step | High development effort, tightly coupled to scheme changes, redeployment required for each form change |
| Workflow Engine attachable forms | Define forms on activities in the Designer; use FormsRuntimeApi to render and submit | Forms managed alongside the scheme, parameter mapping built in, no per-activity UI code |
The Forms Plugin gives you the flexibility of the schema-driven approach without forcing you into a specific frontend framework. Your application decides how to render forms; the plugin handles discovery, parameter mapping, validation, and persistence.
Frequently asked questions
Does attachable forms require a specific license?
Yes. The Forms Plugin is a license-gated feature. Your license must include the "Forms" capability. See Workflow Engine Editions for licensing details.
Which databases support the Forms Plugin?
Any database that has a persistence provider implementing IFormDataProvider. All six built-in providers - SQL Server, PostgreSQL, MySQL, MongoDB, Oracle, and SQLite - include form storage support. The form schema and version data are stored in a forms table created during provider migration.
How do form fields relate to process parameters?
Each form defines input parameters (data loaded into the form), output parameters (data written when a command executes), and draft parameters (progress saved mid-form). These are configured in FormSettings when setting up the "Show Form" activity. The plugin reads and writes the named process parameters automatically on form submission.
Can I use the Forms Plugin with a custom frontend framework?
Yes. The plugin ships with frontend packages (@optimajet/workflow-forms-manager and @optimajet/workflow-forms-viewer) for React. You can also build a custom frontend using any framework - the FormsRuntimeApi returns form definitions as structured data, not pre-rendered HTML.
What happens to in-progress forms when the form definition is updated?
The plugin stores form versions. A process instance that has already loaded a form uses the definition version that was current when the form was displayed. Only new form loads (new process instances reaching the activity after the update) use the latest version. You can manage versions through the Designer's form management actions.