PSA/ee/docs/plans/2026-03-13-workflow-reference-scope-selector-design.md

Workflow Reference Scope Selector Design

Summary

Replace the flat Reference field picker with a staged selection flow:

1. Choose source scope
2. If needed, choose source group or step
3. Choose a field from that scope

This keeps the reference UI aligned with the actual workflow data model and reduces the number of irrelevant choices shown at once.

Goals

• Reduce cognitive load in Reference mode.
• Avoid presenting a single flat list of every possible workflow path.
• Let step outputs use a step-first flow.
• Allow field lists to be filtered to compatible target types.
• Keep Browse sources as the secondary/manual tree browser.

Source Model

The first selector is Source scope.

Supported scopes:

• Payload
• Step output
• Workflow meta
• Error
• Loop context

Scope visibility rules:

• Error only appears when the current step is inside a catch block.
• Loop context only appears when the current step is inside a for-each block.
• Step output appears whenever prior saved outputs exist.

Selection Flow

Payload

• Show payload-backed fields directly.
• Filter to exact/coercible target types by default.

Step output

• Show a second selector for the saved step output (vars.<saveAs>).
• After selecting a step, show that step’s available fields.
• Filter to exact/coercible target types by default.

Workflow meta

• Show metadata fields directly.

Error

• Show catch-context error fields directly.

Loop context

• Show loop item and loop index references directly.

Filtering

• Default field list shows exact and coercible matches first.
• Incompatible fields are hidden by default.
• If needed later, add a Show all fields affordance as an escape hatch.

Browse Sources

• Browse sources remains available in Reference mode.
• It is no longer the default primary flow.
• It should open scoped to the currently selected source scope when possible.

Persistence

• The staged selector still writes the same persisted value shape:
  • { $expr: "payload.foo" }
  • { $expr: "vars.ticketResult.ticket_id" }
  • { $expr: "meta.traceId" }

No runtime contract changes are required.

Component Impact

• InputMappingEditor
  • Replace the flat reference picker with staged selectors.
  • Track source scope and selected step for each reference field.
• MappingPanel
  • Continue to pass grouped source context.
• SourceDataTree
  • Remains the secondary browser surface.

Testing

• Reference mode renders Source scope first.
• Choosing Step output reveals the step selector.
• Choosing a step reveals only that step’s fields.
• Field lists prefer compatible types.
• Payload/meta/error/loop scopes only show valid options for the current context.
• Existing saved $expr references rehydrate into the correct staged scope.