@celigo/api-specs 0.2.214 → 0.2.215

package/dist/ai-agent.yml

@@ -5679,12 +5679,16 @@ components:
                     - |-
                       On a grouped record (the export groups rows, so the record is an
                       array) only `create` can author output — build it from the rows with
-                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`
+                      (`$.rows[0].field` and `$.rows[*]` with `inputContext: envelope`).
                       `modify` has no object to overlay onto an array: the record passes
-                      through untouched and the processor reports success. Either mode
-                      reshapes the inside of one record; neither changes how many records
-                      the page carries (that is the export's `preSavePage` hook) or whether
-                      the export groups at all (that is its grouping setting).
+                      through untouched and the processor reports success. Paths written
+                      for one object record (`$.field`, an entry `$.lines[*]`) resolve
+                      nothing there, so `create` returns `{}` for each record, also with
+                      no error (live, 2026-10-30). Either mode reshapes the inside of one
+                      record; neither changes how many records the page carries (that is
+                      the export's `preSavePage` hook) or whether the export groups at all
+                      (that is its grouping setting).
                   examples:
                     - create
                     - modify
@@ -5749,8 +5753,8 @@ components:
                     - record
                     - envelope
                   x-enumDescriptions:
-                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
-                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
+                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment; a grouped record is the array of rows, `$[0].field`) — the default when absent.
+                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), and a grouped record sits under `rows` instead (`$.rows[0].field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
                   description: |
                     Controls the JSON shape the transformTwoDotZero processor
                     evaluates `mappings[].extract` JSONPath values against at
@@ -5766,24 +5770,38 @@ components:
                         processor sees the FLAT record as its evaluation root.
                         `mappings[].extract` JSONPath MUST anchor directly at
                         `$` with NO `record.` segment — e.g. `"$.orderId"`,
-                        `"$.customer.email"`; PLACEHOLDER extracts use
+                        `"$.customer.email"` on an object record, `"$[0].orderId"`
+                        on a grouped one; PLACEHOLDER extracts use
                         `"$.PLACEHOLDER_<field>"`.
                         This is the dominant Celigo idiom and the right choice for new transforms.
                       - `envelope`: the processor sees a wrapped object
                         `{record: {...}, job, testMode, settings, headers,
                         queryParams}` (plus `fileMeta` on file-provider steps).
                         `mappings[].extract` JSONPath MUST include the
-                        `record.` segment for record fields — e.g.
-                        `"$.record.orderId"` — and reads `headers` and
+                        `record.` segment for an object record's fields — e.g.
+                        `"$.record.orderId"`; a grouped record sits under `rows`
+                        instead (`"$.rows[0].orderId"`) — and reads `headers` and
                         `queryParams` beside it (`$.headers['X-Id']`);
                         PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
                         Pick this only when the transform was authored against
                         the envelope shape on purpose.
                     - |-
-                      Handlebars expressions inside `extract`
-                      (`{{record.field}}`, `{{dateFormat ... record.field}}`)
-                      ALWAYS reference the `record` root regardless of
+                      Handlebars expressions inside `extract` reference the
+                      `record` root on an object record (`{{record.field}}`,
+                      `{{dateFormat ... record.field}}`) and `rows` on a
+                      grouped one (`{{rows.0.field}}`), regardless of
                       `inputContext` — only JSONPath anchoring flips.
+                    - |-
+                      ## Grouped records
+
+                      When the export groups rows, each record is an array of
+                      rows. In `record` mode JSONPath roots at that array
+                      (`$[0].field`, `$[*]`); `envelope` binds it as `rows`,
+                      not `record` — `$.rows[0].field`, and an entry
+                      `$.rows[*]` whose children read `$.rows.field` — while
+                      `$.record[0].field` and `$.record[*]` resolve nothing,
+                      with no error (live, 2026-10-30). Handlebars extracts
+                      read it as `rows` in both modes (`{{rows.0.field}}`).
                     - |-
                       In `envelope` mode the output is still a bare record: a
                       `modify` transform returns the record with its mapped
@@ -5804,7 +5822,8 @@ components:
                         ``mappings[].extract`` JSONPath values MUST anchor
                         directly at ``$`` with NO ``record.`` segment — for
                         example ``"$.orderId"`` or
-                        ``"$.customer.email"``.  PLACEHOLDER extracts use
+                        ``"$.customer.email"`` on an object record, and
+                        ``"$[0].orderId"`` on a grouped one.  PLACEHOLDER extracts use
                         ``"$.PLACEHOLDER_<field>"``.  This is the dominant
                         Celigo idiom and the right choice for new transforms.
 
@@ -5816,9 +5835,10 @@ components:
                         ``record``) — the
                         same runtime-context envelope Handlebars / SQL /
                         GraphQL templates render against.  ``mappings[].extract``
-                        JSONPath values for record fields MUST include the
+                        JSONPath values for an object record's fields MUST include the
                         ``record.`` segment — for example ``"$.record.orderId"``
-                        or ``"$.record.customer.email"`` — while ``headers`` and
+                        or ``"$.record.customer.email"``; a grouped record's rows
+                        sit under ``rows`` instead (``"$.rows[0].orderId"``) — while ``headers`` and
                         ``queryParams`` are read beside it
                         (``"$.headers['X-Id']"``).  PLACEHOLDER extracts
                         use ``"$.record.PLACEHOLDER_<field>"``.  Pick this
@@ -5831,8 +5851,9 @@ components:
 
                       Handlebars expressions inside ``extract``
                       (``{{record.field}}``,
-                      ``{{dateFormat ... record.field}}``, etc.) ALWAYS
-                      reference the runtime context's ``record`` root
+                      ``{{dateFormat ... record.field}}``, etc.) reference the
+                      runtime context's ``record`` root on an object record,
+                      and ``rows`` (``{{rows.0.field}}``) on a grouped one,
                       regardless of ``inputContext`` — the Handlebars runtime
                       always sees the wrapped envelope.  Only JSONPath
                       behavior flips with this field.

package/dist/api.yml

@@ -5263,12 +5263,16 @@ components:
                     - |-
                       On a grouped record (the export groups rows, so the record is an
                       array) only `create` can author output — build it from the rows with
-                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`
+                      (`$.rows[0].field` and `$.rows[*]` with `inputContext: envelope`).
                       `modify` has no object to overlay onto an array: the record passes
-                      through untouched and the processor reports success. Either mode
-                      reshapes the inside of one record; neither changes how many records
-                      the page carries (that is the export's `preSavePage` hook) or whether
-                      the export groups at all (that is its grouping setting).
+                      through untouched and the processor reports success. Paths written
+                      for one object record (`$.field`, an entry `$.lines[*]`) resolve
+                      nothing there, so `create` returns `{}` for each record, also with
+                      no error (live, 2026-10-30). Either mode reshapes the inside of one
+                      record; neither changes how many records the page carries (that is
+                      the export's `preSavePage` hook) or whether the export groups at all
+                      (that is its grouping setting).
                   examples:
                     - create
                     - modify
@@ -5333,8 +5337,8 @@ components:
                     - record
                     - envelope
                   x-enumDescriptions:
-                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
-                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
+                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment; a grouped record is the array of rows, `$[0].field`) — the default when absent.
+                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), and a grouped record sits under `rows` instead (`$.rows[0].field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
                   description: |
                     Controls the JSON shape the transformTwoDotZero processor
                     evaluates `mappings[].extract` JSONPath values against at
@@ -5350,24 +5354,38 @@ components:
                         processor sees the FLAT record as its evaluation root.
                         `mappings[].extract` JSONPath MUST anchor directly at
                         `$` with NO `record.` segment — e.g. `"$.orderId"`,
-                        `"$.customer.email"`; PLACEHOLDER extracts use
+                        `"$.customer.email"` on an object record, `"$[0].orderId"`
+                        on a grouped one; PLACEHOLDER extracts use
                         `"$.PLACEHOLDER_<field>"`.
                         This is the dominant Celigo idiom and the right choice for new transforms.
                       - `envelope`: the processor sees a wrapped object
                         `{record: {...}, job, testMode, settings, headers,
                         queryParams}` (plus `fileMeta` on file-provider steps).
                         `mappings[].extract` JSONPath MUST include the
-                        `record.` segment for record fields — e.g.
-                        `"$.record.orderId"` — and reads `headers` and
+                        `record.` segment for an object record's fields — e.g.
+                        `"$.record.orderId"`; a grouped record sits under `rows`
+                        instead (`"$.rows[0].orderId"`) — and reads `headers` and
                         `queryParams` beside it (`$.headers['X-Id']`);
                         PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
                         Pick this only when the transform was authored against
                         the envelope shape on purpose.
                     - |-
-                      Handlebars expressions inside `extract`
-                      (`{{record.field}}`, `{{dateFormat ... record.field}}`)
-                      ALWAYS reference the `record` root regardless of
+                      Handlebars expressions inside `extract` reference the
+                      `record` root on an object record (`{{record.field}}`,
+                      `{{dateFormat ... record.field}}`) and `rows` on a
+                      grouped one (`{{rows.0.field}}`), regardless of
                       `inputContext` — only JSONPath anchoring flips.
+                    - |-
+                      ## Grouped records
+
+                      When the export groups rows, each record is an array of
+                      rows. In `record` mode JSONPath roots at that array
+                      (`$[0].field`, `$[*]`); `envelope` binds it as `rows`,
+                      not `record` — `$.rows[0].field`, and an entry
+                      `$.rows[*]` whose children read `$.rows.field` — while
+                      `$.record[0].field` and `$.record[*]` resolve nothing,
+                      with no error (live, 2026-10-30). Handlebars extracts
+                      read it as `rows` in both modes (`{{rows.0.field}}`).
                     - |-
                       In `envelope` mode the output is still a bare record: a
                       `modify` transform returns the record with its mapped
@@ -5388,7 +5406,8 @@ components:
                         ``mappings[].extract`` JSONPath values MUST anchor
                         directly at ``$`` with NO ``record.`` segment — for
                         example ``"$.orderId"`` or
-                        ``"$.customer.email"``.  PLACEHOLDER extracts use
+                        ``"$.customer.email"`` on an object record, and
+                        ``"$[0].orderId"`` on a grouped one.  PLACEHOLDER extracts use
                         ``"$.PLACEHOLDER_<field>"``.  This is the dominant
                         Celigo idiom and the right choice for new transforms.
 
@@ -5400,9 +5419,10 @@ components:
                         ``record``) — the
                         same runtime-context envelope Handlebars / SQL /
                         GraphQL templates render against.  ``mappings[].extract``
-                        JSONPath values for record fields MUST include the
+                        JSONPath values for an object record's fields MUST include the
                         ``record.`` segment — for example ``"$.record.orderId"``
-                        or ``"$.record.customer.email"`` — while ``headers`` and
+                        or ``"$.record.customer.email"``; a grouped record's rows
+                        sit under ``rows`` instead (``"$.rows[0].orderId"``) — while ``headers`` and
                         ``queryParams`` are read beside it
                         (``"$.headers['X-Id']"``).  PLACEHOLDER extracts
                         use ``"$.record.PLACEHOLDER_<field>"``.  Pick this
@@ -5415,8 +5435,9 @@ components:
 
                       Handlebars expressions inside ``extract``
                       (``{{record.field}}``,
-                      ``{{dateFormat ... record.field}}``, etc.) ALWAYS
-                      reference the runtime context's ``record`` root
+                      ``{{dateFormat ... record.field}}``, etc.) reference the
+                      runtime context's ``record`` root on an object record,
+                      and ``rows`` (``{{rows.0.field}}``) on a grouped one,
                       regardless of ``inputContext`` — the Handlebars runtime
                       always sees the wrapped envelope.  Only JSONPath
                       behavior flips with this field.

package/dist/asynchelper.yml

@@ -3158,12 +3158,16 @@ components:
                     - |-
                       On a grouped record (the export groups rows, so the record is an
                       array) only `create` can author output — build it from the rows with
-                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`
+                      (`$.rows[0].field` and `$.rows[*]` with `inputContext: envelope`).
                       `modify` has no object to overlay onto an array: the record passes
-                      through untouched and the processor reports success. Either mode
-                      reshapes the inside of one record; neither changes how many records
-                      the page carries (that is the export's `preSavePage` hook) or whether
-                      the export groups at all (that is its grouping setting).
+                      through untouched and the processor reports success. Paths written
+                      for one object record (`$.field`, an entry `$.lines[*]`) resolve
+                      nothing there, so `create` returns `{}` for each record, also with
+                      no error (live, 2026-10-30). Either mode reshapes the inside of one
+                      record; neither changes how many records the page carries (that is
+                      the export's `preSavePage` hook) or whether the export groups at all
+                      (that is its grouping setting).
                   examples:
                     - create
                     - modify
@@ -3228,8 +3232,8 @@ components:
                     - record
                     - envelope
                   x-enumDescriptions:
-                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
-                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
+                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment; a grouped record is the array of rows, `$[0].field`) — the default when absent.
+                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), and a grouped record sits under `rows` instead (`$.rows[0].field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
                   description: |
                     Controls the JSON shape the transformTwoDotZero processor
                     evaluates `mappings[].extract` JSONPath values against at
@@ -3245,24 +3249,38 @@ components:
                         processor sees the FLAT record as its evaluation root.
                         `mappings[].extract` JSONPath MUST anchor directly at
                         `$` with NO `record.` segment — e.g. `"$.orderId"`,
-                        `"$.customer.email"`; PLACEHOLDER extracts use
+                        `"$.customer.email"` on an object record, `"$[0].orderId"`
+                        on a grouped one; PLACEHOLDER extracts use
                         `"$.PLACEHOLDER_<field>"`.
                         This is the dominant Celigo idiom and the right choice for new transforms.
                       - `envelope`: the processor sees a wrapped object
                         `{record: {...}, job, testMode, settings, headers,
                         queryParams}` (plus `fileMeta` on file-provider steps).
                         `mappings[].extract` JSONPath MUST include the
-                        `record.` segment for record fields — e.g.
-                        `"$.record.orderId"` — and reads `headers` and
+                        `record.` segment for an object record's fields — e.g.
+                        `"$.record.orderId"`; a grouped record sits under `rows`
+                        instead (`"$.rows[0].orderId"`) — and reads `headers` and
                         `queryParams` beside it (`$.headers['X-Id']`);
                         PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
                         Pick this only when the transform was authored against
                         the envelope shape on purpose.
                     - |-
-                      Handlebars expressions inside `extract`
-                      (`{{record.field}}`, `{{dateFormat ... record.field}}`)
-                      ALWAYS reference the `record` root regardless of
+                      Handlebars expressions inside `extract` reference the
+                      `record` root on an object record (`{{record.field}}`,
+                      `{{dateFormat ... record.field}}`) and `rows` on a
+                      grouped one (`{{rows.0.field}}`), regardless of
                       `inputContext` — only JSONPath anchoring flips.
+                    - |-
+                      ## Grouped records
+
+                      When the export groups rows, each record is an array of
+                      rows. In `record` mode JSONPath roots at that array
+                      (`$[0].field`, `$[*]`); `envelope` binds it as `rows`,
+                      not `record` — `$.rows[0].field`, and an entry
+                      `$.rows[*]` whose children read `$.rows.field` — while
+                      `$.record[0].field` and `$.record[*]` resolve nothing,
+                      with no error (live, 2026-10-30). Handlebars extracts
+                      read it as `rows` in both modes (`{{rows.0.field}}`).
                     - |-
                       In `envelope` mode the output is still a bare record: a
                       `modify` transform returns the record with its mapped
@@ -3283,7 +3301,8 @@ components:
                         ``mappings[].extract`` JSONPath values MUST anchor
                         directly at ``$`` with NO ``record.`` segment — for
                         example ``"$.orderId"`` or
-                        ``"$.customer.email"``.  PLACEHOLDER extracts use
+                        ``"$.customer.email"`` on an object record, and
+                        ``"$[0].orderId"`` on a grouped one.  PLACEHOLDER extracts use
                         ``"$.PLACEHOLDER_<field>"``.  This is the dominant
                         Celigo idiom and the right choice for new transforms.
 
@@ -3295,9 +3314,10 @@ components:
                         ``record``) — the
                         same runtime-context envelope Handlebars / SQL /
                         GraphQL templates render against.  ``mappings[].extract``
-                        JSONPath values for record fields MUST include the
+                        JSONPath values for an object record's fields MUST include the
                         ``record.`` segment — for example ``"$.record.orderId"``
-                        or ``"$.record.customer.email"`` — while ``headers`` and
+                        or ``"$.record.customer.email"``; a grouped record's rows
+                        sit under ``rows`` instead (``"$.rows[0].orderId"``) — while ``headers`` and
                         ``queryParams`` are read beside it
                         (``"$.headers['X-Id']"``).  PLACEHOLDER extracts
                         use ``"$.record.PLACEHOLDER_<field>"``.  Pick this
@@ -3310,8 +3330,9 @@ components:
 
                       Handlebars expressions inside ``extract``
                       (``{{record.field}}``,
-                      ``{{dateFormat ... record.field}}``, etc.) ALWAYS
-                      reference the runtime context's ``record`` root
+                      ``{{dateFormat ... record.field}}``, etc.) reference the
+                      runtime context's ``record`` root on an object record,
+                      and ``rows`` (``{{rows.0.field}}``) on a grouped one,
                       regardless of ``inputContext`` — the Handlebars runtime
                       always sees the wrapped envelope.  Only JSONPath
                       behavior flips with this field.

package/dist/export.yml

@@ -15412,12 +15412,16 @@ components:
                     - |-
                       On a grouped record (the export groups rows, so the record is an
                       array) only `create` can author output — build it from the rows with
-                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`
+                      (`$.rows[0].field` and `$.rows[*]` with `inputContext: envelope`).
                       `modify` has no object to overlay onto an array: the record passes
-                      through untouched and the processor reports success. Either mode
-                      reshapes the inside of one record; neither changes how many records
-                      the page carries (that is the export's `preSavePage` hook) or whether
-                      the export groups at all (that is its grouping setting).
+                      through untouched and the processor reports success. Paths written
+                      for one object record (`$.field`, an entry `$.lines[*]`) resolve
+                      nothing there, so `create` returns `{}` for each record, also with
+                      no error (live, 2026-10-30). Either mode reshapes the inside of one
+                      record; neither changes how many records the page carries (that is
+                      the export's `preSavePage` hook) or whether the export groups at all
+                      (that is its grouping setting).
                   examples:
                     - create
                     - modify
@@ -15482,8 +15486,8 @@ components:
                     - record
                     - envelope
                   x-enumDescriptions:
-                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
-                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
+                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment; a grouped record is the array of rows, `$[0].field`) — the default when absent.
+                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), and a grouped record sits under `rows` instead (`$.rows[0].field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
                   description: |
                     Controls the JSON shape the transformTwoDotZero processor
                     evaluates `mappings[].extract` JSONPath values against at
@@ -15499,24 +15503,38 @@ components:
                         processor sees the FLAT record as its evaluation root.
                         `mappings[].extract` JSONPath MUST anchor directly at
                         `$` with NO `record.` segment — e.g. `"$.orderId"`,
-                        `"$.customer.email"`; PLACEHOLDER extracts use
+                        `"$.customer.email"` on an object record, `"$[0].orderId"`
+                        on a grouped one; PLACEHOLDER extracts use
                         `"$.PLACEHOLDER_<field>"`.
                         This is the dominant Celigo idiom and the right choice for new transforms.
                       - `envelope`: the processor sees a wrapped object
                         `{record: {...}, job, testMode, settings, headers,
                         queryParams}` (plus `fileMeta` on file-provider steps).
                         `mappings[].extract` JSONPath MUST include the
-                        `record.` segment for record fields — e.g.
-                        `"$.record.orderId"` — and reads `headers` and
+                        `record.` segment for an object record's fields — e.g.
+                        `"$.record.orderId"`; a grouped record sits under `rows`
+                        instead (`"$.rows[0].orderId"`) — and reads `headers` and
                         `queryParams` beside it (`$.headers['X-Id']`);
                         PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
                         Pick this only when the transform was authored against
                         the envelope shape on purpose.
                     - |-
-                      Handlebars expressions inside `extract`
-                      (`{{record.field}}`, `{{dateFormat ... record.field}}`)
-                      ALWAYS reference the `record` root regardless of
+                      Handlebars expressions inside `extract` reference the
+                      `record` root on an object record (`{{record.field}}`,
+                      `{{dateFormat ... record.field}}`) and `rows` on a
+                      grouped one (`{{rows.0.field}}`), regardless of
                       `inputContext` — only JSONPath anchoring flips.
+                    - |-
+                      ## Grouped records
+
+                      When the export groups rows, each record is an array of
+                      rows. In `record` mode JSONPath roots at that array
+                      (`$[0].field`, `$[*]`); `envelope` binds it as `rows`,
+                      not `record` — `$.rows[0].field`, and an entry
+                      `$.rows[*]` whose children read `$.rows.field` — while
+                      `$.record[0].field` and `$.record[*]` resolve nothing,
+                      with no error (live, 2026-10-30). Handlebars extracts
+                      read it as `rows` in both modes (`{{rows.0.field}}`).
                     - |-
                       In `envelope` mode the output is still a bare record: a
                       `modify` transform returns the record with its mapped
@@ -15537,7 +15555,8 @@ components:
                         ``mappings[].extract`` JSONPath values MUST anchor
                         directly at ``$`` with NO ``record.`` segment — for
                         example ``"$.orderId"`` or
-                        ``"$.customer.email"``.  PLACEHOLDER extracts use
+                        ``"$.customer.email"`` on an object record, and
+                        ``"$[0].orderId"`` on a grouped one.  PLACEHOLDER extracts use
                         ``"$.PLACEHOLDER_<field>"``.  This is the dominant
                         Celigo idiom and the right choice for new transforms.
 
@@ -15549,9 +15568,10 @@ components:
                         ``record``) — the
                         same runtime-context envelope Handlebars / SQL /
                         GraphQL templates render against.  ``mappings[].extract``
-                        JSONPath values for record fields MUST include the
+                        JSONPath values for an object record's fields MUST include the
                         ``record.`` segment — for example ``"$.record.orderId"``
-                        or ``"$.record.customer.email"`` — while ``headers`` and
+                        or ``"$.record.customer.email"``; a grouped record's rows
+                        sit under ``rows`` instead (``"$.rows[0].orderId"``) — while ``headers`` and
                         ``queryParams`` are read beside it
                         (``"$.headers['X-Id']"``).  PLACEHOLDER extracts
                         use ``"$.record.PLACEHOLDER_<field>"``.  Pick this
@@ -15564,8 +15584,9 @@ components:
 
                       Handlebars expressions inside ``extract``
                       (``{{record.field}}``,
-                      ``{{dateFormat ... record.field}}``, etc.) ALWAYS
-                      reference the runtime context's ``record`` root
+                      ``{{dateFormat ... record.field}}``, etc.) reference the
+                      runtime context's ``record`` root on an object record,
+                      and ``rows`` (``{{rows.0.field}}``) on a grouped one,
                       regardless of ``inputContext`` — the Handlebars runtime
                       always sees the wrapped envelope.  Only JSONPath
                       behavior flips with this field.
@@ -16426,8 +16447,8 @@ components:
         **Structure**
 
         The mock output must follow the integrator.io canonical format, which consists of a
-        `page_of_records` array containing record objects. Each record object has a `record`
-        property that contains the actual data fields.
+        `page_of_records` array of items. On an export that does not group rows, each item has a
+        `record` property that contains the actual data fields:
 
         ```json
         {
@@ -16444,6 +16465,19 @@ components:
         }
         ```
 
+        An export that groups rows (`groupByFields`) produces records that are arrays of rows, and
+        each item then carries `rows` instead of `record`, holding the rows of one grouped record. A
+        flow test run saves a grouped export's records in this form:
+
+        ```json
+        {
+          "page_of_records": [
+            { "rows": [ { "field1": "value1" }, { "field1": "value2" } ] },
+            ...
+          ]
+        }
+        ```
+
         **Usage**
 
         In a flow test run, and for an upstream lookup during a page-processor preview
@@ -16476,7 +16510,8 @@ components:
 
         - Maximum of 10 records
         - Maximum size of 1 MB
-        - Must follow the canonical format shown above
+        - Must follow one of the canonical formats shown above: every item `{"record": {...}}`, or
+          on a grouped export every item `{"rows": [...]}`
 
         Mock output can be populated automatically from preview data (which is the parsed response,
         before `transform` / `filter`) or entered manually.
@@ -16518,6 +16553,22 @@ components:
                   categories:
                     - Electronics
                     - Accessories
+              rows:
+                type: array
+                description: |
+                  The rows of one grouped record, present instead of `record` when the export
+                  groups rows (`groupByFields`). Every item of a grouped export's mock carries
+                  `rows`.
+                items:
+                  type: object
+                  additionalProperties: true
+                example:
+                  - orderId: SO-1001
+                    sku: SKU-100
+                    quantity: 2
+                  - orderId: SO-1001
+                    sku: SKU-200
+                    quantity: 1
       example:
         page_of_records:
           - record: