Embedded UI Workflow Support Reference

The Embedded UI supports full workflow execution, including multi-step sequences of modules with navigation, submission persistence, and step progress indicators. This reference covers how workflows are mounted, how navigation and submissions work, and the workflow state machine.

What Is Workflow Embedding?

A workflow is an ordered sequence of Unqork modules that an end-user moves through step by step, similar to a multi-page form. When a workflow is embedded in a host page, the entire step-by-step experience renders inside a single custom HTML element, without redirecting the end-user to the Unqork platform.

The Embedded UI supports:

• Step navigation (Next, Previous).
• Save and Exit.
• persistence across steps.
• Step progress indicators.

Mounting a Workflow

To embed a workflow, call runtime.mountWorkflow() with the workflow's path and the DOM target where it should render. The parameters below control how the workflow loads and whether an existing in-progress submission is resumed.

Workflow Flow

The diagram below shows the sequence of calls that happen when mountWorkflow() is called and when an end-user navigates between steps. Each participant represents a layer in the Embedded UI stack, from the host page down to the Unqork API.

sequenceDiagram
    participant Host as Host Page
    participant RT as UnqorkRuntime
    participant CE as CentauriRuntime
    participant SPA as spa-embed.js
    participant ANG as Angular (Shadow DOM)
    participant API as Unqork API

    Host->>RT: mountWorkflow({ workflowPath })
    RT->>CE: mountModule({ workflowPath })
    CE->>SPA: mount({ workflowPath })
    SPA->>ANG: $state.go('embedWorkflowStart', { workflowPath })
    ANG->>API: GET /fbu/uapi/workflow/{workflowPath}
    API-->>ANG: { form, navigation, submission, ... }
    Note over ANG: DisplayWorkflow controller processes response
    ANG->>ANG: $state.go('embedWorkflowPath', { workflowPath, stepPath })
    Note over ANG: Module renders inside workflow template

    Host->>ANG: User clicks Next
    ANG->>API: POST /fbu/uapi/workflow/{workflowPath}/navigate
    API-->>ANG: { nextStep form, navigation, submission }
    ANG->>ANG: $state.go('embedWorkflowPath', { stepPath: nextStep })

Workflow State Machine

The diagram below shows the states a workflow moves through from mount to completion. Each transition maps to a user action or an API response.

stateDiagram-v2
    [*] --> embedWorkflowStart: mountWorkflow()
    embedWorkflowStart --> embedWorkflowPath: API returns first step
    embedWorkflowPath --> embedWorkflowPath: Next or Previous
    embedWorkflowPath --> embedWorkflowStepSubmission: When submissionId exists
    embedWorkflowStepSubmission --> embedWorkflowPath: Continue navigation
    embedWorkflowPath --> [*]: Save and Exit or Complete

Workflow Template

Each embedded workflow renders using a built-in inline template. The template provides the structural elements that make the workflow work inside a host page, including navigation controls, a loading state, and the content area where each step's module renders.

Submission Persistence

Workflow submissions are stored on the server so data is not lost when an end-user moves between steps. The submission is created automatically the first time the user moves forward, and the same submission is reused for every subsequent step.

1. The end-user fills Step 1 and clicks Next.
2. A POST /navigate request creates a submission and returns a submissionId.
3. Step 2 loads with the submissionId in state params.
4. Data persists across forward and backward navigation.
5. Save and Exit persists current data and exits.

Workflow Errors

When something goes wrong during a workflow, like a failed API call or a navigation error, the Embedded UI sends an error payload to the host page. The table below lists each workflow-specific error type, where it originates, and what it means.

Workflow Error Payloads

All workflow errors include timestamp, type, message, and originalError. Additional fields depend on the error type:

• workflow: includes workflowPath, stepPath, and status (HTTP status code).
• workflow-fatal: includes workflowPath and stepPath. Also triggers an error dialog inside the embedded module.
• workflow-navigation: includes workflowPath, stepPath, and action. The action field is one of next, previous, or goto, indicating which navigation action failed.

{
  "timestamp": "2026-06-11T12:00:00.000Z",
  "type": "workflow-navigation",
  "message": "Workflow navigation failed (next)",
  "workflowPath": "insurance-onboarding",
  "stepPath": "step-1",
  "action": "next",
  "originalError": {}
}

Note: The workflow-navigation error is separate from the unqork-embed-workflow-navigate success event, which fires only on successful navigation and includes action, submissionId, stepPath, and workflowPath. The error fires in the catch block and does not include submissionId.

For full per-type payload details, see the Embedded UI Error Surfacing Reference.