| name | workflows-managed-workflows |
| description | Register and roll out managed workflows from a Kibana plugin using `@kbn/workflows-extensions` and `@kbn/workflows/managed`. Use when adding or modifying a code-owned workflow definition, `registerManagedWorkflowOwner`, `initManagedWorkflowsClient`, `install` / `uninstall` / `ready`, choosing `lifecycle` / `versionStrategy` / `enablement`, authoring `yaml` vs `yamlTemplate`, space-scoped vs global installs, `getWorkflowStatus`, or `execute`, or reviewing PRs that touch managed workflow definitions or rollout. Always ask for the user's plugin id first to locate the correct plugin and definition file paths. |
Workflows — Managed Workflow Registration
Managed workflows are code-owned workflow documents the platform installs and reconciles for you. A misconfigured definition can orphan documents at startup, wipe dynamic instances, install into the wrong space, or ship YAML that fails validation. The defaults are not always right — verify each field in the canonical guide explicitly.
Canonical doc: dev_docs/MANAGED_WORKFLOWS.md — registration, rollout, lifecycle policies, yaml / yamlTemplate, spaces, status, execute, and full code examples.
Worked example: examples/workflows_extensions_example/ + src/platform/packages/shared/kbn-workflows/managed/definitions/workflows_extensions_example.ts
Source files
| What | Path |
|---|
| Definition types | src/platform/packages/shared/kbn-workflows/managed/types.ts |
| Registry | src/platform/packages/shared/kbn-workflows/managed/definitions/index.ts |
| Plugin-scoped client | src/platform/plugins/shared/workflows_extensions/server/types.ts |
| Runtime API types | src/platform/packages/shared/kbn-workflows/server/types.ts |
| Global space constant | GLOBAL_WORKFLOW_SPACE_ID from @kbn/workflows/server |
| Registry tests | src/platform/packages/shared/kbn-workflows/managed/managed_workflow_definitions.test.ts |
Read MANAGED_WORKFLOWS.md for the full walkthrough. Use the sections below only for agent workflow and review gates.
0. Locate the owning plugin (do this first)
Before creating or editing any files, ask the user for their plugin id (plugin.id from kibana.jsonc, camelCase — e.g. streams, workflowsExtensionsExample). Do not guess or assume a plugin.
If the user already named their plugin in the request, confirm it matches plugin.id before proceeding. The same id must appear on:
definition.pluginId in @kbn/workflows/managedregisterManagedWorkflowOwner(pluginId) in plugin setup()initManagedWorkflowsClient(pluginId) in plugin start()
Resolve the plugin root
rg '"id": "<pluginId>"' --glob '**/kibana.jsonc'
Read that kibana.jsonc to confirm workflowsExtensions is in requiredPlugins.
Choose file locations
| Location | Purpose |
|---|
src/platform/packages/shared/kbn-workflows/managed/definitions/<plugin>.ts | Definition + exported id const(s) |
src/platform/packages/shared/kbn-workflows/managed/definitions/index.ts | Add to managedWorkflowDefinitions; re-export id(s) |
your-plugin/server/managed_workflows/ | Optional: re-export ids + PLUGIN_ID const for install code |
your-plugin/server/plugin.ts | registerManagedWorkflowOwner (setup), client + installs (start) |
Inspect existing plugins for conventions already in use (flat file vs subdirectory, e.g. streams_ki/, sig_events/).
Quick rule reference
See MANAGED_WORKFLOWS.md for rationale and examples. High-signal rules:
| Concern | Rule |
|---|
| Definition id | Must start with system-; stable once shipped — import id const at call sites |
pluginId | Same id in definition, registerManagedWorkflowOwner, and client init |
| Registry | Definition in managedWorkflowDefinitions + id re-exported from definitions/index.ts |
management | Explicit lifecycle, versionStrategy, enablement — no runtime default |
yaml / yamlTemplate | Exactly one; bump version on content changes |
setup() | registerManagedWorkflowOwner only — never install |
start() | initManagedWorkflowsClient → static installs → ready() |
spaceId | Required on every operation; use GLOBAL_WORKFLOW_SPACE_ID explicitly for global |
| Multi-instance | Use workflowIdSuffix or full workflowId — bare id overwrites |
execute | Real request + requesting user's space in options (not '*') |
| Templates | Add representative values to templateRepresentativeValuesById in registry tests |
Author checklist
When adding a managed workflow:
-
Plugin id
-
Definition (kbn-workflows/managed/definitions/) — see §7–§8 in MANAGED_WORKFLOWS.md
-
Tests (managed_workflow_definitions.test.ts)
-
Owner plugin — see §1–§3 in MANAGED_WORKFLOWS.md
-
Review
Reviewer checklist
When reviewing a PR that adds or modifies managed workflows:
Reference implementations
| Plugin / package | Path | Notable pattern |
|---|
| Workflows example | kbn-workflows/managed/definitions/workflows_extensions_example.ts + examples/workflows_extensions_example/server/plugin.ts | yamlTemplate + static install at global space + ready() |
| Streams | kbn-workflows/managed/definitions/streams_ki/ + x-pack/platform/plugins/shared/streams/server/plugin.ts | Multiple workflows; YAML in separate files; static + auto + enforced; dedicated install helper |
| SigEvents | kbn-workflows/managed/definitions/sig_events/ | Multi-workflow subdirectory registry |
Before finishing
