OpenParable
Skip to content
← Back to skills

Workflows Custom Triggers

Development
workflows-custom-triggers

Workflows Custom Triggers 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 implement custom workflow triggers from an external Kibana plugin using `@kbn/workflows-extensions`. Use when adding or modifying an event-driven trigger with `registerTriggerDefinition`, designing `eventSchema` Zod schemas, writing `documentation` and KQL `snippets`, wiring `emitEvent` via request context or `getClient`, choosing sync vs async public loader registration, updating `APPROVED_TRIGGER_DEFINITIONS`, or reviewing PRs that touch any of these. Always ask for the user's plugin id first to locate the correct plugin and 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-custom-triggers/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/workflows-custom-triggers, 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 — Custom Trigger Registration

Custom triggers let workflows subscribe to domain events from your plugin. A misconfigured trigger can break workflows on every restart, emit invalid payloads that fail at runtime, cause infinite event chains, 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, emit patterns, guardrails, and approval workflow in:

dev_docs/TRIGGERS.md

Sections to use while implementing:

TaskTRIGGERS.md section
Define common trigger (id, eventSchema, docs, snippets)Step 1
Server registrationStep 2
Public registration (icon, async loader)Step 3
Emit via request context or direct clientStep 4
Approval gateTrigger Definition Approval Process
Event-chain depth and loop preventionEvent-driven guardrails
Loop demo workflowEvent-chain depth (loop) demo

Overview

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

A trigger lives in three layers:

  • Common — id, eventSchema, title, description, stability, optional documentation / snippets. Imported by both server and public to keep them in sync. Set stability to 'tech_preview', 'beta', or 'stable' based on the trigger's maturity.
  • Server — registers the same common definition via registerTriggerDefinition; emits events with emitEvent.
  • Public — spreads the common definition and adds icon only (browser-only UI).

Both sides register through the workflowsExtensions setup contract:

  • Server: registerTriggerDefinition(commonDefinition)
  • Public: registerTriggerDefinition(definition | () => Promise<definition>)

Additional references:

  • Worked example: examples/workflows_extensions_example/
  • Common base type: src/platform/plugins/shared/workflows_extensions/common/trigger_registry/types.ts (CommonTriggerDefinition, TriggerDocumentation, TriggerSnippets)
  • Public trigger types: src/platform/plugins/shared/workflows_extensions/public/trigger_registry/types.ts (PublicTriggerDefinition)
  • Emit API: src/platform/packages/shared/kbn-workflows/server/types.ts (WorkflowsClient, WorkflowsApiRequestHandlerContext, emitEvent)
  • Event-chain guardrails: src/platform/plugins/shared/workflows_extensions/server/event_chain_context.ts
  • Approval fixture: src/platform/plugins/shared/workflows_extensions/test/scout/api/fixtures/approved_trigger_definitions.ts

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, 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

Find the plugin directory by searching for the id in kibana.jsonc:

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 trigger or workflow extension layout. Follow conventions already used in that plugin rather than inventing new paths.

If the plugin already has…Add files there
common/workflows/triggers/ (e.g. cases)common/workflows/triggers/<trigger_name>.ts
common/triggers/ (e.g. example plugin)common/triggers/<trigger_name>.ts
No trigger files yetUse common/triggers/<trigger_name>.ts and mirror under server/triggers/ and public/triggers/

Also check for existing registration hooks:

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

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

Derive the trigger namespace

Trigger ids use <namespace>.<event> (kebab-case namespace, camelCase event). Prefer the namespace already used by that plugin's triggers. If none exist, derive kebab-case from plugin.id (e.g. workflowsExtensionsExample → workflows-extensions-example) and confirm with the user if ambiguous.

File layout

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

your-plugin/
├── common/triggers/<trigger_name>.ts       # common definition (id + eventSchema + title + description)
├── server/triggers/index.ts                # registerTriggerDefinitions(setup)
├── public/triggers/<trigger_name>.ts       # spread common + icon
└── public/triggers/index.ts                # registerTriggerDefinitions(setup)

Keep id, eventSchema, title, description, documentation, and snippets in the common file only. Re-importing them on the public side is how server/public stay locked together.

Agent-specific rules (beyond TRIGGERS.md)

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

ConcernRule
id namespacecases.* is owned by the Cases plugin — do not add new cases.* triggers outside that plugin
Server registrationSetup phase only — never call registerTriggerDefinition from start()
Public iconMust be a React component via React.lazy from @elastic/eui/es/components/icon/assets/*. EUI icon name strings ('star') are not supported — the build will not fail, the icon will simply be missing
Public async loaderPrefer async import to keep zod out of the main bundle. Loaders that reject are caught and logged; one broken loader does NOT prevent other triggers from registering — verify the log when a trigger is silently missing
Public loader skipUnlike step loaders, trigger loaders do not support returning undefined to skip registration. Guard optional triggers by not calling registerTriggerDefinition
emitEvent requestAlways pass the same request used for attribution/space so event-chain depth tracking works. Emitting without a real request when guardrails matter is an anti-pattern
Loop demoUse kibana.request (not a generic HTTP connector) so event-chain headers propagate

For naming conventions, schema rules, registration templates, emit patterns, and approval steps, follow TRIGGERS.md.

Quick rule reference

ConcernRuleDefault if omittedWhen wrong
id<kebab-namespace>.<camelEvent>; stable for the life of the workflown/aRenames break user YAML
Common fileHolds id, eventSchema, title, description, documentation, snippetsn/aDrift between server and public
eventSchemaZod object; .describe() on every fieldn/aEmit throws; bad editor/agent docs
documentation.examplesOnly fields from eventSchemanoneAgents generate invalid YAML
snippets.conditionValid KQL on event.* onlynoneRegistration fails or bad UX
Server registrationRegister common definition in setup()n/aTrigger missing at runtime
Public registrationSpread common + React.lazy iconn/aMissing icon; duplicated strings
emitEventPayload matches eventSchema; use real requestn/aThrows; broken chain guardrails
Public loaderAsync import to keep zod out of main bundlesync inlineTrigger module inflates plugin bundle
APPROVED_TRIGGER_DEFINITIONSAdd new ID + schemaHash; sorted by IDtest failsCI blocks merge until updated

Author checklist

When adding a new trigger:

  1. Plugin location

    • User's plugin.id confirmed; plugin root resolved from kibana.jsonc
    • File paths follow the plugin's existing trigger/workflow layout
  2. Common file (common/triggers/<trigger>.ts or plugin convention) — see TRIGGERS.md Step 1

    • id is namespaced (<kebab>.<camel>) and exported as a const string
    • title, description, and any text in documentation use i18n.translate
    • Template syntax / trigger ids inside i18n strings go through values:
    • eventSchema declared with z from @kbn/zod/v4; every field has .describe()
    • documentation.examples[] reference only eventSchema fields
    • snippets.condition (if present) is valid KQL on event.* fields only
  3. Server — see TRIGGERS.md Step 2

    • Registers common definition unchanged via registerTriggerDefinition
    • Registration happens in setup(), never start()
    • Emit sites call emitEvent with payloads matching eventSchema
    • Emit uses request context or getClient(request) with the attribution request
  4. Public — see TRIGGERS.md Step 3

    • Spreads common definition — no duplicated title/schemas
    • Icon is a React.lazy import from @elastic/eui/es/components/icon/assets/<name>
    • Public registration uses async loader unless the module is trivially small
  5. Plugin wiring

    • workflowsExtensions in requiredPlugins in kibana.jsonc
    • Server and public both register the same trigger id
  6. Approval gate — see TRIGGERS.md approval process

    • Scout API test run or GET internal/workflows_extensions/trigger_definitions for schemaHash
    • Entry added to APPROVED_TRIGGER_DEFINITIONS (alphabetically sorted)
    • PR description requests review from @elastic/workflows-eng

Reviewer checklist

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

  • No new trigger definitions inside src/platform/plugins/shared/workflows_extensions/{server,public}/triggers/ — external triggers belong in the owning plugin
  • title, description, eventSchema, documentation, snippets live in the common file, not duplicated on public
  • id follows <kebab>.<camel>, has a fresh namespace, and does not collide with another plugin's prefix
  • Every eventSchema field has .describe(); examples/snippets only use declared fields
  • Server registers the common definition directly in setup(); no registration in start()
  • Public spreads common definition; icon uses React.lazy, not EUI icon name strings
  • emitEvent payloads match eventSchema; emit path uses the attribution request for chain guardrails
  • Public registration uses an async loader unless the module is trivially small
  • APPROVED_TRIGGER_DEFINITIONS is updated (sorted; new entry near related namespace); workflows-eng review requested
  • Event-chain implications considered when workflows can re-emit this trigger

Reference implementations

PluginPathNotable pattern
Workflows exampleexamples/workflows_extensions_example/Canonical layout; async public loaders; custom_trigger docs/snippets; loop_trigger + emit route for chain-depth demo
Casesx-pack/platform/plugins/shared/cases/common/workflows/triggers/Multiple triggers in one module; shared base schema; rich i18n documentation examples
Cases (public)x-pack/platform/plugins/shared/cases/public/workflows/triggers/Spread common + lazy icon per trigger
Alerting v2x-pack/platform/plugins/shared/alerting_v2/server/lib/workflow_extensions/register_trigger_definitions.tsSingle registration loop over a catalog shared with runtime emit mapping

Additional resources

  • Contributing guide (canonical): dev_docs/TRIGGERS.md
  • Public Slack channel for questions: #one-workflow