Workflow Engine

Overview

The Workflow Engine (internally called the ServerJob / WorkflowActionRunner system) is the automation glue across MyGov. When a form is submitted, a webhook fires, or a cron schedule fires, the engine executes a sequence of configured actions in order. Each action is a call to a registered handler with a JSON config.

The engine does not maintain persistent state between runs — it is not a BPM (business process management) system. Each run is synchronous and stateless. Handlers share a Dictionary<string, object?> context that lives for the duration of one run only.

Trigger Types

FormAction schedule values

The Schedule column on organization.FormAction controls when an action fires within the form-response trigger:

Action Config Structure (V2)

Each action row has an ActionType string (handler name) and a Config JSON field:

{
  "Op": {
    "Action":  "SendMail",       // handler-specific operation name
    "Source":  "context.path",   // optional input from context
    "Target":  "recipient@..."   // optional target (mailbox, endpoint, etc.)
  },
  "Data": {
    // handler-specific payload — may be a template string or an object
    "Subject":  "New reservation request",
    "Body":     "Hello {{FirstName}}, ..."
  }
}

Handlebars templating ({{path.to.value}}) is supported in string fields. Values are resolved from the workflow context dictionary.

V1 vs V2 Architecture

FormAction has legacy "V1" fields from before the Config JSON approach:

New workflows should use V2 (Config JSON only). V1 fields are retained for backward compatibility but not recommended for new work.

Handler Library

All handlers implement IActionHandler and are registered in DI. The ActionHandlerFactory resolves by ActionType string (case-insensitive).

Workflow Context

The context is a Dictionary<string, object?> (WorkflowActionContext) scoped to a single run. It is initialized from the trigger payload (form response JSON, webhook payload JSON, or server job config). Handlers can read from and write to the context to pass data between steps.

• Form response trigger: context includes all form field values (keyed by field name), plus Id (response ID) and FormId.
• Webhook trigger: context is initialized from the raw webhook payload JSON.
• Server job trigger: context starts empty or with job config values.

Handlebars paths like {{FieldName}} or {{nested.property}} are resolved against this context when processing Config templates.

What's Needed for Reservation Approval

The current engine can support a basic reservation workflow, but two gaps exist relative to the design in Reservations:

1. Async pause state

The engine has no built-in "wait for staff approval" state. The multi-step pattern (described above in Trigger Types) requires the consuming code to explicitly re-trigger the workflow for each state change. For reservations, this means:

• On submit: run Schedule = null actions (notify staff, set status to Pending)
• When staff approves: call StartWorkflow(formResponse, "Status:Approved") from the approval endpoint
• When staff denies: call StartWorkflow(formResponse, "Status:Denied")

This is buildable with the current engine — the pattern just needs to be wired into the reservation controller.

2. Reservation-specific action handlers

The design calls for new workflow actions specific to reservations:

• CreateCalendarEntry — write a CalendarEvent for the confirmed reservation
• BlockExchangeRoom — write to Exchange resource mailbox via MSGraph (partially implemented in MSGraphHandler)
• SendCancellationLink — generate HMAC-signed cancellation token and email it (could use MailHandler with template)
• CheckConflict — query availability before confirming (would be a new MsSql or custom handler action)
• ValidateLibraryCard — patron ID lookup (new Http or MsSql action to an external API)

Most of these can be composed from existing handlers (MSGraph, Mail, MsSql, Http) with the right Config. The library card lookup needs a new Http or custom handler target.

Admin Portal — Forms Module

The my/js/modules/forms/ module manages forms and their workflow actions. The key page:

• FormActionsPage.js — renders the workflow-action-editor web component with foreignKey=formId, foreignKeyName='formId', createPath='/form/action', timingMode='schedule'. This is the UI for configuring which actions run for a form and when.

The workflow-action-editor web component is a shared component used across forms, webhooks, and server jobs — it knows how to render the Config JSON editor for each handler type.

Audit Findings

Codebase audited: api/Classes/Workflow/, api/Classes/Workflow/Handlers/, api/Models/organization/FormAction.cs, api/Controllers/forms/FormActionsController.cs, my/js/modules/forms/pages/FormActionsPage.js