OpenParable
Skip to content
← Back to skills

Workflows Managed Workflows

Development
workflows-managed-workflows

Workflows Managed Workflows is an Agent Skill for development published in the elastic/kibana repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/elastic/kibana/blob/HEAD/src/platform/plugins/shared/workflows_extensions/.claude/skills/workflows-managed-workflows/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/workflows-managed-workflows, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

WhatPath
Definition typessrc/platform/packages/shared/kbn-workflows/managed/types.ts
Registrysrc/platform/packages/shared/kbn-workflows/managed/definitions/index.ts
Plugin-scoped clientsrc/platform/plugins/shared/workflows_extensions/server/types.ts
Runtime API typessrc/platform/packages/shared/kbn-workflows/server/types.ts
Global space constantGLOBAL_WORKFLOW_SPACE_ID from @kbn/workflows/server
Registry testssrc/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/managed
  • registerManagedWorkflowOwner(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

LocationPurpose
src/platform/packages/shared/kbn-workflows/managed/definitions/<plugin>.tsDefinition + exported id const(s)
src/platform/packages/shared/kbn-workflows/managed/definitions/index.tsAdd 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.tsregisterManagedWorkflowOwner (setup), client + installs (start)

Inspect existing plugins for conventions already in use (flat file vs subdirectory, e.g. streams_ki/, significant_events/).

Quick rule reference

See MANAGED_WORKFLOWS.md for rationale and examples. High-signal rules:

ConcernRule
Definition idMust start with system-; stable once shipped — import id const at call sites
pluginIdSame id in definition, registerManagedWorkflowOwner, and client init
RegistryDefinition in managedWorkflowDefinitions + id re-exported from definitions/index.ts
managementExplicit lifecycle, versionStrategy, enablement — no runtime default
yaml / yamlTemplateExactly one; bump version on content changes
setup()registerManagedWorkflowOwner only — never install
start()initManagedWorkflowsClient → static installs → ready()
spaceIdRequired on every operation; use GLOBAL_WORKFLOW_SPACE_ID explicitly for global
Multi-instanceUse workflowIdSuffix or full workflowId — bare id overwrites
executeReal request + requesting user's space in options (not '*')
TemplatesAdd representative values to templateRepresentativeValuesById in registry tests

Author checklist

When adding a managed workflow:

  1. Plugin id

    • User's plugin.id confirmed from kibana.jsonc
    • Same id on definition, registerManagedWorkflowOwner, and initManagedWorkflowsClient
  2. Definition (kbn-workflows/managed/definitions/) — see §7–§8 in MANAGED_WORKFLOWS.md

    • Id starts with system-; exported as a const
    • pluginId matches owning plugin
    • version: 1 (bump on YAML changes)
    • Exactly one of yaml or yamlTemplate
    • Explicit management policy chosen intentionally
    • Template defs use as const satisfies ManagedWorkflowDefinition<TValues>
    • Added to managedWorkflowDefinitions in definitions/index.ts
    • Id re-exported from definitions/index.ts
  3. Tests (managed_workflow_definitions.test.ts)

    • Representative values added for new yamlTemplate definitions
  4. Owner plugin — see §1–§3 in MANAGED_WORKFLOWS.md

    • workflowsExtensions in requiredPlugins
    • registerManagedWorkflowOwner in setup() only
    • initManagedWorkflowsClient in start()
    • Static workflows installed in start() before ready()
    • ready() called after all static installs
    • Dynamic/on-demand installs use deterministic suffixes
    • Every install / execute passes explicit spaceId
    • Install/execute sites import id consts — no string literals
  5. Review

    • CODEOWNERS on @kbn/workflows/managed notified
    • Global vs space-scoped choice documented if non-obvious

Reviewer checklist

When reviewing a PR that adds or modifies managed workflows:

  • Definition id uses system- prefix; id const exported and used at call sites
  • pluginId matches the plugin that calls registerManagedWorkflowOwner
  • Definition appears in managedWorkflowDefinitions and id is re-exported
  • management policy matches install pattern (static + ready() vs dynamic on-demand)
  • No install calls in setup()
  • Static installs happen before ready(); dynamic workflows not expected to survive reconciliation alone
  • Multi-instance installs use suffix or full workflowId — not bare definition id repeated for different entities
  • spaceId explicit everywhere; global installs use GLOBAL_WORKFLOW_SPACE_ID, not omitted
  • execute passes request and requesting space (not '*' for execution stamping)
  • Template definitions updated in templateRepresentativeValuesById when added/changed
  • YAML references triggers/steps the owning plugin (or dependencies) actually register

Reference implementations

Plugin / packagePathNotable pattern
Workflows examplekbn-workflows/managed/definitions/workflows_extensions_example.ts + examples/workflows_extensions_example/server/plugin.tsyamlTemplate + static install at global space + ready()
Streamskbn-workflows/managed/definitions/streams_ki/ + x-pack/platform/plugins/shared/streams/server/plugin.tsMultiple workflows; YAML in separate files; static + auto + enforced; dedicated install helper
SigEventskbn-workflows/managed/definitions/significant_events/Multi-workflow subdirectory registry

Before finishing

  • Plugin id confirmed; definition and owner plugin aligned
  • Full registration and rollout steps verified against MANAGED_WORKFLOWS.md
  • Public Slack channel for questions: #one-workflow