Workflow

The workflow service drives interactive customer flows (retention prompts, dunning, onboarding). It speaks to a backend execution engine via a request/response API and exposes the running flow as reactive state — current step, available responses, completion outcome.

Setup

import {
  provideContext,
  createWorkflowService,
  createWorkflowApiAdapter,
  createMockWorkflowApiAdapter,
  WorkflowServiceContext,
} from "@juo/blocks";

provideContext(
  root,
  WorkflowServiceContext,
  createWorkflowService({
    adapter: createWorkflowApiAdapter(sdk),
    // ...other dependencies (translations, theme state)
  }),
);

For local development, swap the adapter:

createWorkflowService({ adapter: createMockWorkflowApiAdapter() });

Shape (key surface)

type WorkflowService = {
  // Reactive state
  isActive: ReadonlySignal<boolean>;
  isLoading: ReadonlySignal<boolean>;
  isCompleted: ReadonlySignal<boolean>;
  hasError: ReadonlySignal<boolean>;
  canRespond: ReadonlySignal<boolean>;
  currentStepInfo: ReadonlySignal<WorkflowStepInfo | null>;
  currentInteraction: ReadonlySignal<PendingInteraction | null>;

  // Lifecycle
  startFlow(flowType: string, params?: Record<string, unknown>): Promise<void>;
  respond(responseType: string, data?: Record<string, unknown>): Promise<void>;
  cancel(): Promise<void>;
};

WorkflowStepInfo carries the current step’s actionType, actionConfig, and the list of availableResponses the customer can pick from.

Execution model

Workflows are deterministic request/response — no websockets, no in-memory timers. Each customer action becomes a respond() call; the backend advances the state machine and returns the next step. Timeouts are orchestrator-driven (the backend schedules them).

Example: workflow action block

A typical action block reads the current step config and offers a response button per available choice:

import {
  defineBlock,
  effect,
  untracked,
  injectContext,
  WorkflowServiceContext,
} from "@juo/blocks";
import { html, render } from "lit-html";

defineBlock("DiscountOffer", {
  group: "action",
  schema: { /* ... */ } as const,
  initialValue: () => ({ props: {} }),
  renderer(block) {
    const el = document.createElement("div");
    const workflow = injectContext(el, WorkflowServiceContext);

    effect(() => {
      const info = workflow.currentStepInfo.value;
      const loading = workflow.isLoading.value;
      const canRespond = workflow.canRespond.value;
      const value = (info?.actionConfig?.discountValue as string) ?? "10";

      untracked(() => {
        render(
          html`
            <h2>Take ${value}% off your next order?</h2>
            ${(info?.availableResponses ?? []).map(
              (r) => html`
                <button
                  ?disabled=${loading || !canRespond}
                  @click=${() => workflow.respond(r.type)}
                >
                  ${r.label}
                </button>
              `,
            )}
          `,
          el,
        );
      });
    });

    return el;
  },
});

Starting a flow

The host page typically starts a flow in response to a customer action — such as canceling a subscription or initiating a retention offer.

await workflow.startFlow("cancel_subscription", {
  subscriptionId: current.id,
  layout: "modal",
});

flowType is a stable client identifier. The backend selects the published workflow definition that matches the flow type for the trigger source.

Overview

Concepts

Services

Frameworks

Guides

Setup

Shape (key surface)

Execution model

Example: workflow action block

Starting a flow

​Setup

​Shape (key surface)

​Execution model

​Example: workflow action block

​Starting a flow

Setup

Shape (key surface)

Execution model

Example: workflow action block

Starting a flow