---
title: "Embedded UI Workflow Support Reference"
slug: "embedded-ui-workflow-support-reference"
tags: ["embedded-ui", "reference-guides"]
status: "update"
updated: 2026-10-13T18:19:25Z
published: 2026-10-13T18:19:25Z
canonical: "docs.unqork.io/embedded-ui-workflow-support-reference"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 UnqorkAI platform.

The Embedded UI supports:

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

## Mounting a Workflow

To embed a workflow, call `runtime.mountWorkflow()` with the workflow's 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.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `workflowPath` | `string` | Yes | The unique path identifier for the workflow, like `insurance-onboarding`. |
| `target` | `string` | Yes | The custom element tag name or CSS selector for the DOM element where the workflow renders. |
| `submissionId` | `string` | No | The ID of an existing submission to resume. If provided, the workflow loads at the step where the end-user left off. |
| `style` | `string` | No | An optional CSS style override applied to the workflow container. |

## 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.

![Diagram](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261013_181923_35232346a6b446dfb718ac2351192777.svg?sv=2026-02-06&spr=https&st=2026-11-08T10%3A25%3A49Z&se=2026-11-08T11%3A25%3A49Z&sr=c&sp=r&sig=XWExovUN25cd6zDd5Nl6mHGjF5GUuJkdJsmwTobCOwM%3D)

## 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.

![Diagram](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261013_181923_974120ffdee849b499eeb31d41c73121.svg?sv=2026-02-06&spr=https&st=2026-11-08T10%3A25%3A49Z&se=2026-11-08T11%3A25%3A49Z&sr=c&sp=r&sig=XWExovUN25cd6zDd5Nl6mHGjF5GUuJkdJsmwTobCOwM%3D)

## 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.

| Element | Description |
| --- | --- |
| Loader overlay | Displays a loading indicator during API calls. The overlay stays in the custom element's boundaries using `position: absolute` so it does not cover the host page. |
| Flash messages | Displays warnings and errors returned from the workflow API. |
| Header title | A configurable title pulled from the workflow definition. |
| `<workflow-navigation>` | Displays the end-user's current step in the workflow. |
| `<unqorkio>` | The content area where the current step's module renders. |
| Navigation buttons | The Save and Exit, Previous, and Next buttons for moving through the workflow. |

## 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.

| Error Type | Source | Description |
| --- | --- | --- |
| `workflow` | `DisplayWorkflow.error()` | The workflow API returned an error status, like a 4xx or 5xx response. |
| `workflow-fatal` | `DisplayWorkflow.handleError()` | A fatal error occurred while the workflow was processing the API response. |
| `workflow-navigation` | `onWorkflowNavigate()` catch | A navigation action (Next, Previous, or a direct jump) failed to complete. |

### 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.

```json
{
  "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](/unqorkai/docs/embedded-ui-error-surfacing-reference).

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-04-21 | Initial publication. |
| 2026-06-15 | Added Workflow Error Payloads section with per-type payload details, JSON example, and workflow-navigation vs. success event distinction. |
| 2026-06-11 | Editorial pass: fixed metadata title (was "Testing Reference"), fixed metadata description, removed HR dividers, added description paragraphs to all H2 sections and Mermaid diagrams, expanded parameter table and element table descriptions, updated internal links. |

The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

Rendering is the process of loading components and displaying the final result on the front-end screen.

HTML (Hyper Text Markup Language) is the standard markup language for for achieving font, color, graphic, and hyperlink effects when creating web pages.

The Document Object Model (DOM) is the data representation of objects that form the structure and content of a document on the web. The DOM represents the page.

Rendering is the process of loading components and displaying the final result on the front-end screen.

Cascading Style Sheets (CSS) is a style sheet language used for presenting how a HTML or XML document looks to end-users.

A definition

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

Elements are are what you use to build Unqork applications. Elements include modules, workflows, Data Collections, Data Schema, and Record Collections.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.

JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data.