---
title: "Set Up an Embedded Workflow"
slug: "set-up-an-embedded-workflow"
tags: ["embedded-ui"]
status: "update"
updated: 2026-10-13T15:22:46Z
published: 2026-10-13T15:22:46Z
canonical: "docs.unqork.io/set-up-an-embedded-workflow"
---

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

# Set Up an Embedded Workflow

This guide walks through embedding a multi-step Unqork workflow in an external web page. By the end, a workflow with step navigation and submission persistence renders inside the host page.

## Prerequisites

Complete these steps before beginning:

- An Unqork environment with the Embedded UI feature enabled. The `embedded.js` script returns a 404 error if the feature is not active on the environment.
- The host page domain added as a CORS exception in **Environment Administration > Cross-Origin Resource Sharing (CORS)**. Browsers block cross-origin API requests by default. Without this exception, the runtime cannot reach the Unqork API from the host page.
- A published workflow application with a known workflow . The runtime identifies the workflow by its path segment from the application URL. The workflow must be published to be accessible.

## Step 1: Add the Embedded Script

Add the `embedded.js` script tag to the host page. The script loads the Embedded UI runtime.

```html
<script src="https://your-environment.unqork.io/embedded.js"></script>
```

## Step 2: Add a Mount Target

Add an element to the host page where the workflow will render. The runtime registers it as a Shadow DOM web component, keeping styles isolated between the workflow and the host page.

```html
<unqork-app></unqork-app>
```

## Step 3: Mount the Workflow

Write a script that initializes the runtime and mounts the workflow. Always call `initialize()` before `mountWorkflow()`. The runtime must complete its internal setup before it can handle workflow navigation and step management. Calling `mountWorkflow()` first returns an error.

```html
<script>
  (async () => {
    const runtime = window.unqork.runtimes.default
    await runtime.initialize()
    await runtime.mountWorkflow({
      workflowPath: 'insurance-onboarding',
      target: 'unqork-app'
    })
  })()
</script>
```

| Parameter | Description |
| --- | --- |
| `workflowPath` | The workflow path identifier from the Unqork application URL. |
| `target` | The custom element tag name (for example, `unqork-app`) where the workflow renders. |

## Step 4: Resume an Existing Workflow (Optional)

End-users who close the page mid-workflow lose their place if nothing saves their progress. Passing the `submissionId` from a previous session restores the end-user's saved answers and returns them to their last step, so they do not have to restart.

```html
<script>
  (async () => {
    const runtime = window.unqork.runtimes.default
    await runtime.initialize()
    await runtime.mountWorkflow({
      workflowPath: 'insurance-onboarding',
      target: 'unqork-app',
      submissionId: '69e13f32f8681734737a1a27'
    })
  })()
</script>
```

## Step 5: Handle Workflow Errors (Optional)

Workflows surface three categories of errors that require different responses. Navigation failures (like a failed step transition) are often recoverable by retrying. General workflow errors indicate an API failure during step processing. Fatal errors mean the workflow cannot continue and the runtime must be remounted. Distinguishing between them lets you respond appropriately in your UI.

```html
<script>
  window.addEventListener('unqork-embed-error', (event) => {
    const error = event.detail

    if (error.type === 'workflow-navigation') {
      // error.action is 'next', 'previous', or 'goto'
      // error.workflowPath and error.stepPath identify the workflow context
      console.warn('Navigation failed:', error.action, error.message)
    }

    if (error.type === 'workflow') {
      // error.status contains the HTTP status code from the workflow API
      console.warn('Workflow error:', error.status, error.message)
    }

    if (error.type === 'workflow-fatal') {
      // Fatal error — the embedded module also shows an error dialog
      console.error('Fatal workflow error:', error.message)
    }
  })
</script>
```

All three error types share these base fields: `timestamp`, `type`, `message`, and `originalError`. The additional fields per type are:

| Type | Additional Fields |
| --- | --- |
| `workflow-navigation` | `action` (`next`, `previous`, or `goto`), `workflowPath`, `stepPath` |
| `workflow` | `status` (HTTP status code from the workflow API), `workflowPath`, `stepPath` |
| `workflow-fatal` | `workflowPath`, `stepPath` |

## Determining the workflowPath

The `workflowPath` is the path segment from the Unqork application preview URL. For example, given:

```
http://env.unqork.io/app/insurance-onboarding?preview=true#/workflow/insurance-onboarding/step-1
```

The `workflowPath` is `insurance-onboarding`.

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-09-11 | Fixed broken See Also links. |
| 2026-06-11 | Expanded Step 5 to cover all three workflow error types; replaced individual payload table with consolidated per-type fields table; added inline field comments to code example (from PR #7395). |
| 2026-06-08 | Added "why" context to Prerequisites, Steps 2–5. |
| 2026-04-21 | Initial publication. |

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

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.

A functionality of a software. For example, Copy and Paste is a feature of a computer's operating system.

Cross-Origin Resource Sharing (CORS) lets you control access to resources located outside a given domain.

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.

A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address.

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

The Shadow DOM is a web standard that allows you to create encapsulated, hidden DOM subtrees for your web components. It provides a way to scope CSS styles and JavaScript behavior within a component, preventing them from leaking out and interfering with the rest of the page.

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.