workflows-custom-triggers

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:

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.

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:

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

Quick rule reference

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

Additional resources

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