[Internal]: Workflow step docs — Cases (20 registered steps)

[nastasha-solomon]

Summary

Diff between Cases workflow step metadata in the Kibana cases plugin common layer and the published Kibana action steps doc. The page today covers generic kibana.request and a single named-action example; it does not reference the cases.* step types registered from common.

Source (Kibana):

• Registration: x-pack/platform/plugins/shared/cases/server/workflows/index.ts
• Common definitions: x-pack/platform/plugins/shared/cases/common/workflows/steps/*.ts
• i18n strings: x-pack/platform/plugins/shared/cases/common/workflows/translations.ts

Existing docs page: explore-analyze/workflows/steps/kibana.md

---

Changes detected (family-level)

Area	Change type	Details
Named action example	Modified / clarify	Doc example uses step type kibana.createCaseDefaultSpace. Cases plugin registers cases.createCase (OAS-driven kibana.createCase* may coexist in product). Writer should confirm which type(s) appear in the workflow UI and document the canonical user-facing names (and any aliases).
Case-related steps	Added (undocumented)	20 step types are registered in registerCaseWorkflowSteps (2 definitions exist in common but are not registered: cases.createCaseFromTemplate, cases.setCustomField — see server index.ts comments/TODO). None of the cases.* steps below are described on kibana.md beyond the single create-case example.
Step reference	Added	Consider a table or subpages listing each cases.* step with label, short description, and pointers to with / config / output (from Zod + bundled types), aligned with how other workflow step families are documented.
Category metadata	Info	All listed steps use StepCategory.Kibana in common.

---

Registered cases.* steps (20)

Step type	Label (from i18n defaultMessage)	Short description (from i18n)
cases.getCase	Cases - Get case by ID	Retrieves a case using its unique identifier
cases.createCase	Cases - Create case	Creates a new case with the specified attributes
cases.updateCase	Cases - Update case	Updates a case with the provided fields
cases.updateCases	Update cases	Updates multiple cases in one step
cases.addComment	Cases - Add comment	Adds a user comment to a case
cases.findCases	Find cases	Searches and filters cases
cases.setSeverity	Set case severity	Sets severity for an existing case
cases.setStatus	Set case status	Sets status for an existing case
cases.closeCase	Close case	Closes an existing case
cases.deleteCases	Delete cases	Deletes one or more cases
cases.assignCase	Assign case	Sets assignees for an existing case
cases.unassignCase	Unassign case	Removes assignees from an existing case
cases.addAlerts	Add alerts to case	Adds one or more alerts as case attachments
cases.addEvents	Add events to case	Adds one or more events as case attachments
cases.findSimilarCases	Find similar cases	Finds cases similar to the provided case ID
cases.setDescription	Set case description	Sets description for an existing case
cases.setTitle	Set case title	Sets title for an existing case
cases.addObservables	Add observables to case	Adds one or more observables to a case
cases.addTags	Add case tag	Sets tags for an existing case
cases.setCategory	Add case category	Sets category for an existing case

---

Present in common but not registered (writer / PM follow-up)

Step type	Notes
cases.createCaseFromTemplate	Server registration commented (TODO references elastic/security-team#15982).
cases.setCustomField	Server registration commented.

---

Expanded “how to use” text (from documentation.details — for writer reference only)

Use these as source hints; do not treat as final docs copy.

• createCase: This step creates a new case in the cases system. You can specify title, description, tags, assignees, severity, category, connector configuration, sync settings, and custom fields. The step returns the complete created case object.
• updateCase: This step updates a case using the provided fields. If a version is provided, it is used directly. Otherwise, the step fetches the case to resolve the latest version before updating.
• updateCases: This step updates multiple cases at once. Each case can provide a version directly or let the step fetch the latest version before applying updates.
• addComment: This step appends a new user comment to the selected case.
• getCase: This step retrieves a complete case object from the cases system using its ID. You can optionally include comments and attachments in the response.
• findCases: This step searches cases and returns matching results, including pagination metadata and case status counters.
• setSeverity / setStatus / setDescription / setTitle: Each sets only that field on an existing case; if version is not provided, the latest case version is resolved automatically.
• closeCase: Closes an existing case by setting its status to closed; version resolution same as above.
• deleteCases: Deletes the provided cases, including their comments and user action history.
• assignCase: Sets the assignees array on an existing case; provided assignees are the full source of truth for assignment.
• unassignCase: Removes the given assignees; empty array clears all assignees.
• addAlerts: Adds alert attachments; each alert needs alertId and source index; rule metadata optional.
• addEvents: Adds event attachments; each event needs eventId and source index.
• findSimilarCases: Returns cases similar to the given case based on shared observables, with pagination metadata.
• addObservables: Adds observables using typeKey, value, and optional description.
• addTags: Sets the full tags array on an existing case (provide all tags that should remain).
• setCategory: Sets the category field on an existing case.

---

Config / schema notes (high level)

• Many steps share CasesStepBaseConfigSchema: optional push-case (boolean, default false in schema intent — see shared.ts comments on partial/default).
• cases.createCase config extends base with optional connector-id (drives connector resolution in server handler).
• Single-case outputs generally return case shaped by CaseResponseProperties (Zod from bundled types). Multi-case / find steps differ per their outputSchema in each common file — writer to derive field tables from source.

---

Error states

Server handlers use thrown errors and translated server messages in server/workflows/steps/translations.ts (e.g. update/delete failures). Not found in common as a unified error-state table — writer to follow up with engineering if a dedicated error catalog is needed.

---

Metadata for issue template

Field	Value
Doc set	Kibana / Workflows (stack & serverless per kibana.md frontmatter)
Version	To be confirmed.
Collaboration model	The documentation team
Point of contact	To be confirmed.

Suggested labels: workflow-steps, cases

[nastasha-solomon]

Since we're still deciding where to host the workflow reference docs and their toc location, I'm moving this issue to the next sprint.