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

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

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

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

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.

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

<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:

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.