Sample project

The Forms Plugin sample is a complete ASP.NET and React application that uses the standard Workflow Engine Web API Forms integration. The root README in that repository contains the current prerequisites, configuration, and launch commands.

The sample models a weekly report workflow. A developer creates and submits a report; a manager can accept, reject, or return it for revision. Each workflow state exposes the appropriate form and commands.

The application includes a report list, Forms Manager, Workflow Designer, and a demo user selector.

The Forms Manager is used to edit versioned forms and reusable templates.

Project structure

The repository has one solution and two application parts:

• WorkflowApi contains the ASP.NET backend, workflow setup, migrations, validation, and sample-specific controllers.
• frontend contains the React application and its Forms Manager and Forms Viewer dependencies.
• WorkflowApi.IntegrationTests verifies the standard HTTP contract against MSSQL.

The backend maps the standard /workflow-api/forms/* endpoints. Only report data and demo users require application-specific controllers; the sample does not duplicate the Forms Plugin runtime API in a custom forms controller.

Backend registration

The essential registration is in WorkflowApi/AppBuilder.cs:

Builder.Services.AddWorkflowApiMssql();
Builder.Services.AddWorkflowApiCore(options =>
    CopyCoreOptions(configuration.WorkflowApiCoreOptions, options));
Builder.Services.AddWorkflowRuntime(options =>
{
    options.PersistenceProviderId = configuration.WorkflowTenantCreationOptions.PersistenceProviderId;
    options.ConnectionString = configuration.WorkflowTenantCreationOptions.ConnectionString;
    options.WorkflowRuntimeCreationOptions.ConfigureWorkflowRuntime = runtime =>
        ConfigureWorkflowRuntime(runtime, actionProvider, ruleProvider, parameterProvider);
});
Builder.Services.AddFormsPlugin(options =>
{
    options.FormsManagerUrl = configuration.Forms.FormsManagerUrl;
    options.FormVersionPropertyName = nameof(WeeklyReportData.Version);
    options.FormValidator = validator;
});
Builder.Services.AddFormDataPipelineStep<CamelCaseFormsApiFormDataPipeline>();

The application then calls app.MapWorkflowApi(). AddFormsPlugin attaches the Forms Plugin to every configured runtime and adds its operations to the common API surface. The camel-case pipeline step converts dynamic form data and validation field names at the HTTP boundary; business models can keep normal .NET property casing.

See Forms Plugin Web API integration for endpoint contracts, error codes, multitenancy, and pipeline customization.

Storing form data

The sample stores weekly-report data in an external business table instead of a persisted process parameter. This is implemented by:

• WeeklyReportData, the typed dynamic-parameter model;
• WeeklyReportParameterProvider, which connects workflow parameters to application storage;
• WeeklyReportRepository, which persists the business record.

Applications that do not need separate business tables can store form data in ordinary persisted workflow parameters.

Validation and optimistic concurrency

WeeklyReportValidator validates submitted data. A validation failure is returned as the common HTTP 400 Error envelope with Code = "ValidationError" and field messages in Errors.

The report model also contains a version field. The Forms Plugin compares it with the current stored value before saving or executing a command, so concurrent edits produce a typed FormVersionMismatch error instead of silently overwriting newer data.

Frontend integration

frontend/src/api.ts is the small adapter between React components and the standard Web API. It unwraps response envelopes, maps only ValidationError responses to Forms Viewer field errors, and adds the optional Workflow-Api-Tenant-ID header.

The report page supplies this adapter to FormsViewer; the manager page supplies the same tenant-aware fetch function to FormsManager. When no executable form remains after the final transition, the sample requests a configured read-only fallback form.

The sample intentionally has no authentication and uses a user selector only for demonstration. A production application must derive identity and tenant from an authenticated context and enable Workflow Engine Web API security.

Running and testing

Follow the sample README to create the MSSQL container, configure licenses, run the API and frontend, and execute the focused backend and frontend tests.