workflows-custom-steps

Workflows — Custom Step Registration

Custom steps run inside the Kibana workflow engine and become part of the YAML the user writes. A misconfigured step can break workflows on every restart, pull heavy modules into the main bundle, leak resources on cancellation, or silently fail the approval gate. The defaults are not always right — verify each field below explicitly.

Canonical guide — read this for implementation steps

Follow the end-to-end steps, code templates, naming conventions, and approval workflow in:

dev_docs/STEPS.md

Sections to use while implementing:

Overview

A custom workflow step is owned and registered by a plugin other than workflows_extensions. The workflows-team plugin only hosts internal steps; everything external must live in the owning plugin.

A step lives in three layers:

• Common — id, label, description, category, inputSchema, outputSchema, optional configSchema / documentation / stability / deprecation. Imported by both server and public to keep them in sync.
• Server — wraps the common definition with a handler (and optional onCancel) via createServerStepDefinition.
• Public — wraps the common definition with an icon and optional editorHandlers via createPublicStepDefinition.

Both sides register through the workflowsExtensions setup contract: registerStepDefinition(definition | () => Promise<definition | undefined>).

Additional references:

• Extended code templates (full scaffold, selection handlers, dynamic schema): reference.md
• Worked example: examples/workflows_extensions_example/
• Common base type: src/platform/packages/shared/kbn-workflows/spec/step_definition_types.ts (BaseStepDefinition, StepCategory, StabilityLevel, StepDocumentation)
• Editor handler types: src/platform/packages/shared/kbn-workflows/types/v1.ts (EditorHandlers, StepPropertyHandler, PropertySelectionHandler, ConnectorIdSelectionHandler, DynamicSchema)
• Reusable index selection handler: src/platform/packages/shared/kbn-workflows-ui/src/lib/steps/editor_handlers/index_selection_handler.ts
• Server step types: src/platform/plugins/shared/workflows_extensions/server/step_registry/types.ts (ServerStepDefinition, StepHandler, StepHandlerContext, ContextManager, CallKibanaApiParams, OnCancelHandler)
• Public step types: src/platform/plugins/shared/workflows_extensions/public/step_registry/types.ts (PublicStepDefinition)
• ExecutionError: src/platform/packages/shared/kbn-workflows/server/errors/execution_error.ts
• Approval fixtures (one file per step): src/platform/plugins/shared/workflows_extensions/test/scout/api/fixtures/approved_step_definitions/

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. cases, agentBuilder, 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.

Resolve the plugin root

rg '"id": "<pluginId>"' --glob '**/kibana.jsonc'

The directory containing that kibana.jsonc is the plugin root. Read it to confirm plugin.server / plugin.browser and whether workflowsExtensions is already in requiredPlugins.

Choose file locations inside the plugin

Inspect the plugin root for existing step or workflow extension layout. Follow conventions already used in that plugin rather than inventing new paths.

Also check for existing registration hooks:

• server/**/step_types/index.ts or server/plugin.ts — server registration
• public/**/step_types/ or public/plugin.ts — public registration

Wire new steps into those existing index/setup files when present; only create new index files when the plugin has no step layout yet.

Derive the step namespace

Step ids use <namespace>.<action> (kebab-case namespace, camelCase action). Prefer the namespace already used by that plugin's steps. If none exist, derive kebab-case from plugin.id (e.g. agentBuilder → agent-builder) and confirm with the user if ambiguous. Reserved internal prefixes (ai, data, flowControl, external, elasticsearch, kibana, kibana.cases) must not be used outside workflows_extensions.

File layout

Mirror the layout used by examples/workflows_extensions_example/ so reviewers and the workflows team can find things:

your-plugin/
├── common/step_types/<step_name>.ts        # common definition (id + schemas + label + category)
├── server/step_types/<step_name>.ts        # createServerStepDefinition + handler
├── server/step_types/index.ts              # registerStepDefinitions(setup)
├── public/step_types/<step_name>.ts        # createPublicStepDefinition + icon + editorHandlers
└── public/step_types/index.ts              # registerStepDefinitions(setup, deps)

Keep id, inputSchema, outputSchema, configSchema in the common file only. Re-importing them on both sides is how server/public stay locked together.

Agent-specific rules (beyond STEPS.md)

These are easy to miss during implementation or review — they are not always spelled out in the contributing doc:

For the YAML naming conventions (the single most common mistake — only the step type action is camelCase, config/input keys we own never are), follow STEPS.md → Workflow YAML Naming Conventions.

Quick rule reference

Author checklist

When adding a new step:

1. Plugin location

   • User's plugin.id confirmed; plugin root resolved from kibana.jsonc
   • File paths follow the plugin's existing step/workflow layout
   • workflowsExtensions is in requiredPlugins in kibana.jsonc

2. Common file (common/step_types/<step>.ts or plugin convention) — see STEPS.md Step 1

   • id is namespaced (<kebab>.<camel>) and exported as a const string
   • category matches the actions-menu group users expect (use StepCategory from @kbn/workflows)
   • label, description, and any text in documentation use i18n.translate
   • Template syntax ({{ ... }}) inside i18n strings goes through values:
   • inputSchema / outputSchema declared with z from @kbn/zod/v4
   • configSchema declared only for behavior-controlling step-level properties; no reserved keys (if, foreach, on-failure, timeout)
   • Workflow-owned config keys are kebab-case; workflow-owned input keys (under with:) are kebab-case or snake_case — never camelCase; inherited keys (OpenAPI/connector) keep their original shape (see Workflow YAML Naming Conventions)

3. Server file (server/step_types/<step>.ts) — see STEPS.md Step 2

   • Uses createServerStepDefinition (no explicit ServerStepDefinition annotation)
   • Spreads myStepCommonDefinition — no duplicated label/category/schemas
   • context.abortSignal is passed to every ES query, fetch, and tight loop
   • Uses context.contextManager.getFakeRequest() with a real plugin client when available, falls back to callKibanaApi only otherwise
   • Errors with custom categories or structured detail use ExecutionError; raw errors are fine for everything else
   • onCancel is implemented only if the step allocates resources outside the signal's reach, and is idempotent

4. Public file (public/step_types/<step>.ts) — see STEPS.md Step 3 and Custom Property Selection

   • Uses createPublicStepDefinition
   • Spreads myStepCommonDefinition
   • Icon is a React.lazy import from @elastic/eui/es/components/icon/assets/<name>
   • If the step picks a Kibana connector, the property is config['connector-id'] and uses connectorIdSelection with an explicit connectorTypes (and enableCreation only when intentional)
   • If the step picks an index / alias / data stream, the property uses selection: getIndexSelectionHandler(services, options) from @kbn/workflows-ui, with dataViews and application injected via a public-side factory
   • For other catalogs, editorHandlers provides full selection: { search, resolve, getDetails } per dot path
   • Every sibling property read inside the handlers is listed in dependsOnValues
   • getDetails does not make a network call when option is non-null
   • Dynamic output shape (if any) is expressed via editorHandlers.dynamicSchema.getOutputSchema, not by varying outputSchema

5. Registration ({server,public}/step_types/index.ts) — see STEPS.md Step 4

   • Public side uses async loader (() => import('./...').then(...)) to keep zod + step module out of the main bundle
   • Conditional/feature-flagged steps return undefined from the loader; they do not throw
   • All registerStepDefinition calls happen in setup(), never start()

6. Approval gate — see STEPS.md Step Definition Approval Process

   • Local Scout API test was run; it printed an echo … > approved_step_definitions/<step.id>.txt command per offending step
   • Ran the printed echo command(s) from the kibana directory to create/update the per-step approval file(s)
   • PR description requests review from @elastic/workflows-eng

Reviewer checklist

When reviewing a PR that adds or modifies a custom step:

• No new top-level files inside src/platform/plugins/shared/workflows_extensions/{server,public}/steps/ — external steps belong in the owning plugin
• label, description, category, schemas live in the common file, not duplicated on server/public
• id follows <kebab>.<camel>, has a fresh namespace, and is not in a reserved prefix
• Workflow-owned config/input keys follow the naming conventions — config keys kebab-case, with: input keys kebab-case or snake_case, no camelCase for keys we own (inherited OpenAPI/connector shapes excepted)
• Server handler uses createServerStepDefinition; types are inferred, not restated
• abortSignal flows through every ES/HTTP call in the diff — search for new esClient.search( / fetch( without a signal:
• If callKibanaApi is used, check whether a request-scoped client from the target plugin would work instead
• Errors thrown inside the handler are either intentional plain errors or ExecutionError with a specific type
• Public file uses React.lazy for the icon; no inline <EuiIcon type="..." /> references
• If a connector ID is in scope, the property is config['connector-id'] and uses connectorIdSelection with explicit connectorTypes — not hand-rolled selection
• If an index / alias / data stream is in scope, the property uses selection: getIndexSelectionHandler(...) from @kbn/workflows-ui — not hand-rolled selection
• editorHandlers.selection.dependsOnValues covers every sibling field referenced inside search / resolve / getDetails
• getDetails does not call the network when option is present
• Public registration uses an async loader unless the step module is trivially small
• Conditional registration paths return undefined, not null or a rejected promise
• No registerStepDefinition call moved into start()
• Per-step approval file approved_step_definitions/<step.id>.txt is added or updated with the new definitionHash; workflows-eng review requested

Reference implementations

Additional resources

• Contributing guide (canonical): dev_docs/STEPS.md
• Extended code templates and selection/dynamic-schema examples: reference.md
• Public Slack channel for questions: #one-workflow