Website · Documentation · GitHub · Changelog

Overview

@bpmnkit/user-tasks is a zero-dependency widget for rendering and interacting with Camunda 8 user tasks. Mount it into any HTML element to get a complete task UI — form rendering via @bpmnkit/plugins/form-viewer, claim/unclaim, complete, and optional reject actions.

It connects to the @bpmnkit/proxy local server to fetch task forms and submit completions via the Camunda REST API.

Features

• Form rendering — loads the task's linked Camunda Form and renders it via @bpmnkit/plugins/form-viewer
• Claim / Unclaim — assigns or removes the task assignee
• Complete — submits collected form variables to the Camunda API
• Reject — optional reject/return action with a reason prompt
• Metadata display — assignee, due date (with overdue highlight), and priority
• Theme support — light, dark, or neon via @bpmnkit/ui design tokens
• Zero dependencies — no framework required; mounts into any HTMLElement

Installation

npm install @bpmnkit/user-tasks @bpmnkit/proxy

Quick Start

import { createUserTaskWidget } from "@bpmnkit/user-tasks"

const widget = createUserTaskWidget({
  container: document.getElementById("task-panel")!,
  task: {
    userTaskKey: "2251799813685281",
    name: "Review order",
    assignee: "alice",
    dueDate: "2025-06-01T12:00:00Z",
    priority: 50,
  },
  proxyUrl: "http://localhost:3033",  // default
  theme: "dark",
  onComplete(variables) {
    console.log("Task completed with", variables)
  },
  onClaim() {
    console.log("Task claimed")
  },
  onUnclaim() {
    console.log("Task unclaimed")
  },
  onReject(reason) {
    console.log("Task rejected:", reason)
  },
})

// Later: update the displayed task
widget.setTask({ userTaskKey: "2251799813685999", name: "Approve invoice" })

// Clean up
widget.destroy()

API Reference

createUserTaskWidget(options)

interface UserTaskWidgetOptions {
  /** The container element to render the widget into. */
  container: HTMLElement
  /** The user task to display. */
  task: UserTask
  /** Base URL of the proxy server. Default: "http://localhost:3033" */
  proxyUrl?: string
  /** Active profile name for x-profile header. */
  profile?: string | null
  /** Visual theme. Default: "neon" */
  theme?: "light" | "dark" | "neon"
  /** Called when the user completes the task. */
  onComplete(variables: Record<string, unknown>): void
  /** Called when the user claims the task. */
  onClaim(): void
  /** Called when the user unclaims the task. */
  onUnclaim(): void
  /** Called when the user rejects/returns the task. Optional — hides the Reject button if omitted. */
  onReject?(reason: string): void
}

Returns a UserTaskWidgetApi:

interface UserTaskWidgetApi {
  /** Update the displayed task and reload its form. */
  setTask(task: UserTask): void
  /** Remove the widget from the DOM and clean up. */
  destroy(): void
}

UserTask

interface UserTask {
  userTaskKey: string
  name?: string
  assignee?: string
  candidateGroups?: string[]
  dueDate?: string          // ISO 8601 date string
  priority?: number
  processInstanceKey?: string
  processDefinitionKey?: string
  formKey?: string
}

Related Packages

| Package | Description | |---------|-------------| | @bpmnkit/core | BPMN/DMN/Form parser, builder, layout engine | | @bpmnkit/canvas | Zero-dependency SVG BPMN viewer | | @bpmnkit/editor | Full-featured interactive BPMN editor | | @bpmnkit/engine | Lightweight BPMN process execution engine | | @bpmnkit/feel | FEEL expression language parser & evaluator | | @bpmnkit/plugins | 22 composable canvas plugins | | @bpmnkit/operate | Monitoring and operations frontend for Camunda 8 | | @bpmnkit/api | Camunda 8 REST API TypeScript client | | @bpmnkit/ascii | Render BPMN diagrams as Unicode ASCII art | | @bpmnkit/ui | Shared design tokens and UI components | | @bpmnkit/profiles | Shared auth, profile storage, and client factories for CLI & proxy | | @bpmnkit/connector-gen | Generate connector templates from OpenAPI specs | | @bpmnkit/cli | Camunda 8 command-line interface (casen) | | @bpmnkit/proxy | Local AI bridge and Camunda API proxy server | | @bpmnkit/cli-sdk | Plugin authoring SDK for the casen CLI | | @bpmnkit/create-casen-plugin | Scaffold a new casen CLI plugin in seconds | | @bpmnkit/casen-report | HTML reports from Camunda 8 incident and SLA data | | @bpmnkit/casen-worker-http | Example HTTP worker plugin — completes jobs with live JSONPlaceholder API data | | @bpmnkit/casen-worker-ai | AI task worker — classify, summarize, extract, and decide using Claude |

License

MIT © BPMN Kit — made by u11g