PSA/ee/docs/plans/2026-05-09-workflow-regex-transform-ai-authoring/PRD.md

PRD — Workflow Regex Transform + AI-Assisted Authoring

• Slug: 2026-05-09-workflow-regex-transform-ai-authoring
• Date: 2026-05-09
• Status: Draft

Summary

Add first-class regex transform actions to the workflow system so authors can match, extract, and replace text using deterministic JavaScript regular expressions. The feature should mirror the JSON transform pattern: pure Transform actions in the workflow runtime, normal action.call input mappings, normal saveAs outputs, useful Run Studio errors, designer-friendly inputs/outputs, and Quick Ask guidance for regex syntax and safe usage. AI should help authors write patterns, but saved workflow execution must remain deterministic and independent of AI.

Problem

Workflow authors frequently need to parse semi-structured text: email subjects, alert bodies, ticket descriptions, webhook text fields, hostnames, asset tags, invoice references, phone numbers, and vendor incident IDs. Today they can combine basic text transforms or expressions, but there is no workflow-native regex action with clear inputs, captures, replacement semantics, output schemas, and actionable runtime errors. This makes common automation patterns harder than necessary and encourages brittle ad hoc expressions.

Goals

• Add pure, side-effect-free regex Transform actions for matching, extracting captures, and replacing text.
• Use JavaScript RegExp syntax and flags so runtime behavior is predictable in TypeScript/Node.
• Return structured match/capture outputs that can be saved and referenced by downstream workflow steps.
• Provide guardrails for invalid patterns, unsupported flags, oversized inputs, excessive matches, and pathological regex risk where feasible.
• Improve designer behavior so regex pattern, flags, replacement, and saveAs outputs are clear to workflow authors.
• Preserve existing workflow runtime and designer behavior for all current actions.
• Add Quick Ask guidance that explains JavaScript regex syntax, capture groups, named groups, flags, replacement strings, and deterministic workflow-safe usage.

Non-goals

• No new workflow node type; use the existing action.call Transform action model.
• No external text loading from URLs/files/blobs.
• No AI-dependent runtime behavior.
• No full visual regex builder in this phase.
• No guarantee that every possible catastrophic JavaScript regex can be safely interrupted once execution starts; guardrails should prevent common risky inputs/patterns before execution.
• No PCRE-only syntax support beyond what JavaScript RegExp supports.

Users and Primary Flows

MSP workflow author: extract an incident ID from text

1. Adds a Transform action.
2. Selects Regex Extract.
3. Maps text from a workflow payload field such as payload.email.subject.
4. Enters a pattern such as INC-(\d{6}).
5. Saves output as payload.parsedIncident.
6. Uses payload.parsedIncident.first.groups[0] or named captures in a later ticket/client lookup action.

MSP workflow author: detect whether text matches a policy

1. Adds Regex Match.
2. Maps text from a ticket title or alert body.
3. Enters a pattern and flags.
4. Saves output as vars.regexResult.
5. Uses vars.regexResult.matched in a control.if branch.

MSP workflow author: normalize text

1. Adds Regex Replace.
2. Maps source text from a payload or previous action output.
3. Enters a pattern like \s+, replacement , and replace-all behavior.
4. Saves the normalized text for downstream actions.

AI-assisted workflow author

1. Opens existing Quick Ask or contextual workflow AI affordance if present.
2. Asks: “Write a workflow regex to extract the device hostname and serial number from this alert.”
3. Alga explains which regex Transform action to use, provides a JavaScript regex pattern, explains groups/flags, and tells the user where to paste it.
4. User stores deterministic action config in the workflow designer.

UX / UI Notes

• Regex actions appear under the existing Transform palette group.
• Inputs should render with helpful labels/descriptions:
  • text: source text to inspect or modify
  • pattern: JavaScript regular expression body, without surrounding /.../
  • flags: JavaScript regex flags, constrained to supported values
  • replacement: replacement string for replace action
  • maxMatches: match cap for extract
  • requireMatch: optional failure behavior for extract/match
• If the editor has specialized action input support, regex pattern fields should use multiline/text input with helper text rather than a tiny one-line generic field.
• Save output paths should continue to validate scoped paths such as payload.*, vars.*, and meta.*.
• Downstream reference trees should expose stable output fields such as matched, first, matches, text, and replacementCount. Named capture inference is desirable but can be implemented as a second step if generic outputs are shipped first.
• Run Studio should surface action-level regex errors first, especially invalid pattern/flag errors and require-match failures.

Requirements

Functional Requirements

1. Register transform.regex_match as a pure Transform action.
2. transform.regex_match accepts at least text, pattern, optional flags, and optional requireMatch.
3. transform.regex_match returns at least { matched, match, index, groups, namedGroups }, where missing match fields are null or empty in a consistent documented shape.
4. Register transform.regex_extract as a pure Transform action.
5. transform.regex_extract accepts at least text, pattern, optional flags, optional maxMatches, and optional requireMatch.
6. transform.regex_extract returns at least { matched, count, first, matches }, where each match contains { text, index, groups, namedGroups }.
7. transform.regex_extract supports numbered capture groups.
8. transform.regex_extract supports JavaScript named capture groups where the runtime supports them.
9. Register transform.regex_replace as a pure Transform action.
10. transform.regex_replace accepts at least text, pattern, optional flags, replacement, and optional replaceAll.
11. transform.regex_replace returns at least { text, replacementCount }.
12. transform.regex_replace supports JavaScript replacement tokens such as $1, $2, $<name>, and $$, or explicitly documents any limits.
13. Regex actions validate pattern syntax before execution and fail with actionable messages for invalid patterns.
14. Regex actions validate flags and reject unsupported or duplicate flags with actionable messages.
15. Regex actions enforce guardrails for max source text length, max pattern length, and max match count.
16. Regex actions avoid infinite loops for zero-width global matches.
17. No-match behavior is deterministic: by default no match is a successful result with matched: false / empty matches; requireMatch turns no match into an action failure.
18. All regex transform actions are sideEffectful: false and use engine-provided idempotency.
19. Action schemas are explicit enough for the catalog/designer to expose input and output field names.
20. Outputs save through existing action.call.saveAs; no new assignment behavior is required.
21. The workflow designer exposes regex transform outputs in downstream workflow references.
22. Run Studio displays useful regex action failure messages before generic wrapper errors.
23. Quick Ask guidance covers action names, JavaScript regex pattern syntax, flags, numbered captures, named captures, replacement strings, saveAs examples, guardrails, and deterministic runtime behavior.
24. Regex actions are available regardless of AI entitlement; AI assistance remains gated by existing AI Assistant/Quick Ask access.

Non-functional Requirements

• Runtime behavior must be deterministic and tenant-agnostic.
• Actions must not access the database, network, filesystem, or secrets directly.
• Regex execution must fail fast on invalid inputs and protect workflow workers from obvious expensive patterns/inputs.
• Error messages should distinguish invalid pattern, invalid flags, guardrail limit, no match with requireMatch, and replacement errors.
• Existing workflows and transform actions must remain backward-compatible.

Data / API / Integrations

• No database migration is required.
• Main runtime registration should live in shared/workflow/runtime/actions/registerTransformActions.ts, following existing transform action patterns.
• If EE has a separate workflow runtime action registration or exposure layer, mirror the JSON feature integration in ee/packages/workflows/src/actions/workflow-runtime-v2-actions.ts as needed.
• Designer work should follow the JSON transform/editor changes in:
  • ee/server/src/components/workflow-designer/WorkflowDesigner.tsx
  • ee/server/src/components/workflow-designer/actionInputEditorState.ts
  • ee/server/src/components/workflow-designer/workflowDataContext.ts
  • ee/server/src/components/workflow-designer/WorkflowStepSaveOutputSection.tsx
  • ee/server/src/components/workflow-designer/workflowSaveAsPath.ts
  • ee/server/src/components/workflow-designer/mapping/InputMappingEditor.tsx
• Run Studio error display should follow the JSON feature pattern in workflowRunDisplayError.ts and WorkflowRunDetailsPanel.tsx.
• AI guidance should follow the JSON guidance pattern, likely with a new regex-specific guidance module or an expanded workflow transform guidance module.

Security / Permissions

• Regex Transform actions are not AI-gated.
• Quick Ask/AI guidance remains gated by existing AI Assistant feature/add-on checks.
• Regex outputs may persist sensitive content into workflow state through saveAs; guidance should warn users not to save secret-derived or sensitive captures unless intentional.
• Regex patterns should be treated as workflow configuration, not executable code, but JavaScript regex can still be expensive; guardrails are required.

Observability

No new production observability is required for MVP. Existing workflow action failure logs and Run Studio details should be sufficient. Tests should assert the action-level error messages that users see.

Rollout / Migration

• No migration required.
• Existing workflows are unaffected.
• New actions appear in the Transform catalog after registration.
• AI guidance improvements apply automatically to entitled Quick Ask users.

Open Questions

• Do we include named capture output schema inference in the first implementation, or only generic namedGroups records?
• Should we add a safe-regex/static-analysis dependency, or rely on source length, pattern length, flags, and match-count limits?
• Should regex_match and regex_extract be separate actions, or should one action cover both? Current recommendation is separate for clearer authoring.
• Should regex_replace support both JavaScript replacement-token mode and literal replacement mode?

Acceptance Criteria (Definition of Done)

• Workflow authors can match text with regex and branch on a saved boolean result.
• Workflow authors can extract numbered and named captures and reference them downstream.
• Workflow authors can replace text with regex and save normalized output.
• Invalid patterns/flags and require-match misses fail with clear action-level messages in Run Studio.
• Regex actions appear under Transform with explicit input/output schemas and saveAs support.
• Quick Ask can explain how to author regex workflow transforms without implying AI runs inside workflow execution.
• Unit/integration tests cover happy paths, failures, guardrails, catalog registration, saveAs/downstream references, Run Studio error display, and Quick Ask guidance.