ACTION_ID: format_data_using_js_expression
NAME: Workflow Data Formatter
CATEGORY: Data Operations
CREDITS: 0

⚠ LEGACY — superseded by `formula`. Read action-detail/formula.txt instead. That
file is the full reference (inputs, outputs, key notes, pattern library) and
every word of it applies to this action too; only the two field names differ.
This file exists so workflows that already contain this action stay documented.

Run a single JavaScript expression over upstream variables and emit the result.
Same evaluator, same expression semantics, and the same credit cost (0) as
`formula`.

1. WHAT'S DIFFERENT FROM `formula`

Field names — the only thing that changes on the wire:

                      format_data_using_js_expression      formula
  input field         input                                formula
  output field        formatted_data                       result
  downstream ref      {{format_data_using_js_expression_1  {{formula_1.result}}
                        .formatted_data}}

⚠ The input field is `input`, NOT `formula`. Sending `formula` — or any other
unrecognized key — returns HTTP 200 with a `warnings` entry
(`code: "unknown_field"`) and is SILENTLY IGNORED: the action then runs with no
expression and outputs empty. Always send `input` for this action. Verified live
2026-07-09.

Behaviour — one real difference:

  `formatted_data` is a read-only per-action value. `formula` writes an ordinary
  editable column instead, so its cells can be overwritten by hand in the UI and
  are matched by both value filters and per-action status filters. If that
  matters, use `formula`.

Availability:

  Hidden in the builder's action palette — new workflows built in the UI get
  `formula` instead. Still fully supported over the public API: an existing chain
  keeps running, Get Action / Get Action Graph return it, Configure Action still
  accepts it, and Add Action can still add it. Nothing about it has been removed.
  Prefer `formula` for new work.

2. HOW TO CONFIGURE

Configure Action body
(PATCH /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}):

{
  "inputs": {
    "input": "{{input.first_name}} + ' ' + {{input.last_name}}"
  }
}

Three lookalike names, don't conflate them:

  - `inputs` (plural) — the Configure Action body envelope (`{"inputs": {…}}`),
    identical for every action.
  - `input` (singular) — THIS action's one field: the JS expression.
  - `{{input.<col>}}` — the reference namespace for sheet input columns, used
    INSIDE the expression value.

For everything beyond this — the two evaluation modes, the variable substitution
traps, the string-typed-output gotcha, and the full pattern library
(structured_array reads, JSON parsing, URL/name normalization, array
filter/sort/dedupe, defensive patterns) — see action-detail/formula.txt,
substituting `input` for `formula` and `formatted_data` for `result`.

Last updated: 2026-08-12.