PSA/ee/docs/plans/2026-03-13-workflow-designer-grouped-palette-inline-inputs-transform-actions/PRD.md

# PRD — Workflow Designer Grouped Palette, Inline Action Inputs, and Transform Actions

- Slug: `workflow-designer-grouped-palette-inline-inputs-transform-actions`
- Date: `2026-03-13`
- Status: Draft

## Summary
Refactor the workflow designer so builders no longer start from a sprawling per-action palette or a mapping-first input editor. Instead, they add a smaller set of grouped business-object or app tiles, choose the specific action inside the step, configure the action through an inline field-by-field editor, and use first-class transform steps for common data shaping rather than expanding expression syntax.

This work keeps workflow runtime execution stable in v1. Action steps still execute as `action.call`, selected actions still persist through `config.actionId` and `config.version`, and action inputs still persist through `config.inputMapping`. The refactor is primarily an authoring and designer-model overhaul, plus additive metadata for grouped catalogs, typed pickers, and transform actions.

## Problem
The current workflow authoring model has three compounding problems:

1. The palette grows linearly with every action. This creates search friction, categorization sprawl, and a poor path for future pluggable units.
2. The current action-input authoring flow is mapping-centric instead of task-centric. Users must understand the previous-output-to-current-schema mapping model before they can simply fill out the current action’s required fields.
3. Expression authoring is too programmer-oriented for common data-shaping tasks. Each new “simple” transformation risks expanding the expression surface and training users on a mini-language instead of providing guided workflow tooling.

These issues make workflows harder to discover, harder to author, and harder to extend safely.

## Goals
- Replace the per-action palette with a grouped object/app palette that scales cleanly as actions increase.
- Make action authoring start from the selected action’s accepted fields, not from an abstract mapping canvas.
- Let users choose the action after dropping a grouped tile, so the step model aligns with business objects and future plugins.
- Provide typed pickers for known fields so users choose valid business records rather than entering raw GUIDs.
- Introduce a `Transform` grouping with first-class transformation actions for common text/value/object shaping.
- Preserve runtime compatibility for existing workflows and existing `action.call` execution.
- Keep advanced expressions available as an escape hatch, but make them secondary to structured authoring.

## Non-goals
- Replacing the runtime `action.call` execution contract in v1.
- Replacing `config.inputMapping` with a new persisted action-input model in v1.
- Introducing a generalized visual transformation chain per field in v1.
- Converting every action in the system to typed pickers in the first pass.
- Creating a new full plugin packaging system in this plan; this plan only prepares the designer catalog and grouping model so plugins can slot in.
- Removing advanced expressions entirely.
- Reworking trigger payload mapping as part of this effort.

## Users and Primary Flows
### Users
- MSP admin building automations in the workflow designer
- Internal Alga PSA engineers extending the workflow action catalog
- Future extension/plugin authors who need grouped entry points in the designer

### Primary flows
1. **Add a business action**
   - User opens the palette.
   - User drags `Ticket` into the workflow.
   - Step appears as a grouped action step with `Ticket` selected as its group.
   - User chooses `Create Ticket`, `Find Ticket`, `Update Ticket`, or another allowed ticket action from the step’s action dropdown.
   - The properties panel shows only the fields accepted by the chosen action.

2. **Configure an action input**
   - User selects a step.
   - User sees each target field directly in the properties panel.
   - For each field, user chooses a source mode:
     - reference workflow data
     - choose a fixed value
     - use advanced expression/secret fallback
   - Required field completion updates live.

3. **Use a business-record picker**
   - User configures a field such as `board_id`, `client_id`, or `priority_id`.
   - Workflow designer presents a domain-specific picker instead of a raw string field.
   - User can either choose a fixed business record or map the field dynamically from prior workflow data.

4. **Shape data without writing expressions**
   - User drags `Transform` into the workflow.
   - User chooses a transform action such as truncate text, concatenate values, pick fields, rename fields, or build object.
   - Step output becomes a named workflow value that later business steps can reference.

5. **Edit an existing workflow created before this refactor**
   - Existing `action.call` steps still load.
   - Designer infers their group from `actionId`.
   - User edits them through the new grouped-step and field-based UI without migration.

6. **Use future app/plugin actions**
   - User drags an app tile from the palette.
   - Inside the step, user chooses from actions exposed by that app.
   - App actions reuse the same grouped-step and field-editor model.

## UX / UI Notes
### Palette Model
- Replace one-tile-per-action palette items with a smaller grouped palette.
- Keep control blocks as dedicated items.
- Built-in business functionality appears as domain-object tiles such as Ticket, Contact, Client, Communication, Scheduling, Project, Time, CRM, and Transform.
- External/pluggable functionality appears as app tiles.
- Search must continue to match contained action names and relevant field names.

### Step Properties Model
- Action steps are edited inline in the right-side properties panel.
- A grouped action step first shows:
  - the group/app label
  - the action dropdown
  - step naming/output controls
- Once an action is selected, the properties panel shows:
  - action summary
  - required-field completion state
  - inline field editors
  - output/save-as controls
  - advanced sections only where needed

### Field Authoring Model
- The action input editor is field-first, not mapping-first.
- Each top-level action input field appears as a visible row or group.
- Nested object and array inputs appear as expandable field groups.
- Source-mode selection is explicit per field.
- Structured reference selection should be the default path.
- Expression and secret editing should be visually de-emphasized as advanced options.

### Picker UX
- Known entity identifiers should render pickers with readable labels.
- Fixed-value pickers should store only the resolved identifier in the workflow definition.
- Dynamic reference mode must remain available even when a fixed picker exists.
- Dependent pickers should narrow their options when enough upstream fixed values exist.
- When a dependency is dynamic and cannot be statically resolved, the dependent picker should explain why it cannot provide a fixed selection.

### Transform UX
- `Transform` behaves like a first-class grouped action, not like a special-case modal or hidden utility.
- Transform actions should use the same properties-panel affordances as business actions.
- Transform steps should make their output shape clear so downstream reference pickers/autocomplete stay understandable.

## Requirements

### Functional Requirements
#### Grouped Palette and Designer Action Catalog
- Introduce a designer-facing action catalog that groups actions into core business objects, transform actions, and app/plugin tiles.
- Keep runtime action registry intact; grouped catalog is a designer abstraction layered above it.
- Each grouped tile defines:
  - stable group key
  - display label
  - icon
  - tile kind (`core-object`, `transform`, `app`)
  - list of allowed actions
  - optional default action
- Built-in action groups must be inferred from action IDs/modules where possible, with explicit overrides where module naming is insufficient.
- Existing palette search must continue working against grouped tiles, including matches on contained action names.

#### Grouped Action Step Model
- Dropping a grouped tile creates an `action.call` step scoped to that tile’s group/app.
- The selected action is stored through the existing action config fields.
- Group/app metadata may be stored additively for authoring convenience but must not be required for runtime execution.
- Existing workflows without additive group metadata must still hydrate into the correct grouped-step UI.
- Changing the selected action inside a grouped step must refresh:
  - action label/description
  - input schema-driven fields
  - output schema-driven data context
  - required-field completion state
  - picker metadata and dependencies

#### Inline Field-Based Action Input Editor
- Replace the current action-input dialog as the primary authoring surface with an inline field-based editor.
- Render top-level action input fields directly from the chosen action schema.
- Preserve nested object/array editing using expandable nested field groups.
- Provide explicit per-field source modes:
  - reference
  - fixed value
  - advanced
- Continue serializing into the existing `config.inputMapping` contract.

#### Reference Source Model
- Reference mode must allow selecting values from:
  - workflow payload
  - previous step outputs
  - workflow metadata
  - catch-block error context
  - forEach item/index context
- Reference selection should generate the existing expression-backed mapping values under the hood.
- Output schemas from prior steps must continue to drive autocomplete and source browsing.

#### Picker Metadata and Fixed Value Authoring
- Action schemas must support additive designer metadata that marks fields as known picker-backed entities.
- Registry/catalog responses must carry enough metadata for the designer to render these pickers.
- Fixed picker mode must support readable selection and persist the literal identifier value.
- Dynamic reference mode must still be available on picker-backed fields.
- Ticket-core pickers in v1 must cover:
  - client
  - contact
  - board
  - ticket status
  - ticket priority
  - user/team assignee
  - category
  - subcategory
  - location

#### Transform Actions
- Add a `Transform` grouped tile with first-class actions for common data shaping.
- Transform actions must execute through the same `action.call` mechanism as other actions.
- Transform actions must expose explicit input and output schemas so downstream steps can reference their results.
- Initial transform library must cover:
  - string truncation
  - string concatenation
  - string replacement
  - string split/join
  - string case conversion
  - trim/coalesce/defaulting
  - field picking
  - field renaming
  - object construction from named inputs
- Transform outputs must be referenceable via normal workflow output/save-as behavior.

#### Advanced Expressions
- Existing expression support remains available as an advanced fallback.
- The new authoring model must not require users to learn expressions for common shaping use cases covered by transform actions.
- New common transformations should prefer first-class transform actions over expanding the expression grammar.

#### Plugin/App Support
- Designer action catalog must support app/plugin tiles alongside built-in object tiles.
- App tiles must be able to expose a filtered action dropdown inside the grouped step.
- App actions should be able to participate in the same field-editor and picker-metadata model if they provide the necessary schema annotations.

#### Compatibility, Save/Load, and Validation
- Existing workflows must load, save, publish, and execute without runtime migration.
- Existing `action.call` steps must render in the grouped-step UI even if they were created before grouped tiles existed.
- Required-field and type-compatibility validation must continue working after the editor refactor.
- Changing an action inside an existing grouped step must handle stale input mappings safely and predictably.
- Designer save/reload must preserve selected group, selected action, input values, and save-as outputs.

### Non-functional Requirements
- Grouped palette search and grouped-step rendering should remain responsive even as the action catalog grows.
- The designer model should reduce, not increase, the amount of custom one-off UI needed for each action.
- Additive schema metadata must not break runtime consumers that only care about JSON schema semantics.
- Transform actions should be deterministic and schema-driven so they remain inspectable and debuggable.

## Data / API / Integrations
### Designer Catalog Data
- Add a designer-facing catalog or equivalent registry projection for grouped tiles and contained actions.
- The catalog may be derived server-side from the action registry and additive group metadata.

### Action Schema Metadata
- Extend action schema export or metadata projection so input fields can carry:
  - picker kind
  - optional dependency information
  - optional fixed-value UI hints

### Runtime Compatibility
- Keep runtime step execution on `action.call`.
- Keep action input persistence on `config.inputMapping`.
- Keep existing output schema inference driven by the chosen action’s output schema.

## Security / Permissions
- Existing workflow permissions remain the authority for editing grouped steps and action inputs.
- Read-only users may inspect grouped steps but may not alter selected action or field values.
- Picker-backed fixed selections must only expose data the current workflow authoring user is allowed to see through existing server actions/endpoints.
- Plugin/app tiles must not bypass normal workflow authoring permissions.

## Observability
- No new observability scope is required for v1 beyond preserving current save/publish/run debugging behavior.
- Validation messages in the designer should clearly indicate:
  - missing selected action
  - missing required field values
  - invalid advanced expression/secret usage
  - stale or incompatible mappings after action changes

## Rollout / Migration
- No runtime migration is required for existing workflow definitions.
- Existing workflows continue to persist the same execution contract.
- Group metadata and picker metadata are additive.
- Designer hydration must infer grouped presentation for legacy `action.call` steps using the existing `actionId`.
- Import/export behavior should remain compatible as long as runtime step definitions remain unchanged.

## Open Questions
- Whether app tiles will eventually need a second-level object chooser inside the step. Default for this plan: no second chooser unless a specific app cannot be represented by a single filtered action dropdown.
- Whether some transform actions should later collapse into inline per-field helpers. Default for this plan: no inline transformation chains in v1.
- Whether more built-in pickers beyond ticket-core fields should follow in later phases. Default for this plan: no, keep first pass to ticket-core only.

## Acceptance Criteria (Definition of Done)
- The workflow palette no longer renders one tile per action for built-in business actions.
- Builders can add a grouped business-object tile, choose its action inside the step, and configure its fields inline.
- Action inputs are authored primarily through field rows/groups, not through a mapping dialog.
- Ticket-core identifier fields support fixed pickers and dynamic references.
- Builders can use `Transform` steps for common text/value/object shaping without writing expressions.
- Existing `action.call` workflows created before the refactor still load, save, publish, and execute correctly.
- Advanced expressions remain available for unsupported edge cases but are not required for common authoring flows.