@celigo/api-specs 0.2.213 → 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.
@@ -8342,11 +8363,22 @@ components:
               format: objectId
               x-celigo-refModel: agents
               description: |
-                Reference to a Celigo on-premise Agent. Required for connection types that need
-                local network or filesystem access (JDBC, filesystem, Oracle RDBMS, and on-premise MongoDB).
+                Reference to a Celigo on-premise Agent. Connection types that need local network or
+                filesystem access (JDBC, filesystem, Oracle RDBMS, and on-premise MongoDB) carry one
+                binding — this agent, or an agent group in `_agentGroupId`; never both.
                 The agent establishes a secure tunnel between the on-premise environment and integrator.io.
               examples:
                 - 5f8d43a1b9e5a80011a35f2c
+            _agentGroupId:
+              type: string
+              format: objectId
+              x-celigo-refModel: agentgroups
+              description: |-
+                On-premise agent group serving this connection, when one is bound
+                instead of a single `_agentId`. Absent on connections that use a
+                single agent or none.
+              examples:
+                - 6650a1b2c3d4e5f60718293a
             _borrowConcurrencyFromConnectionId:
               type: string
               format: objectId
@@ -11124,8 +11156,10 @@ components:
       x-celigo-ai-guidance:
         - The POST is rejected with 422 if type-specific required fields are missing (see the per-type conditional rules).
         - |-
-          For Oracle, a placeholder connection cannot be created without a real connection-level _agentId
-          (validator error agent_mode_only) — direct the user to install a Celigo Agent first. All other
+          For Oracle, a placeholder connection cannot be created without a real on-premise binding — a
+          connection-level _agentId, or an agent group through _agentGroupId (validator error
+          agent_mode_only with neither; live-verified that a POST carrying only _agentGroupId is not
+          answered with it) — direct the user to install a Celigo Agent first. All other
           RDBMS types accept placeholder credentials that satisfy the per-type required fields.
         - |-
           Celigo has native support for these database systems:
@@ -11176,16 +11210,17 @@ components:
             `_iClientId` with `basic` auth is rejected. Both types share the
             `mssql` sub-object; `azuresynapse` is cloud-only, and the SQL Server
             connection form offers service-principal auth in Cloud mode only — it
-            saves `basic` for an on-premise connection (`_agentId` set).
-          - **Oracle** — runs in agent mode only, so requires `_agentId` on the
-            parent connection object. Uses `serviceName` instead of `database`.
+            saves `basic` for an on-premise connection (`_agentId` or `_agentGroupId` set).
+          - **Oracle** — runs in agent mode only, so requires an on-premise binding on
+            the parent connection object: `_agentId`, or an agent group's `_agentGroupId`
+            (one of the two, never both). Uses `serviceName` instead of `database`.
             Optionally also takes `serverType` and `instanceName`.
 
           ## PLACEHOLDER / DUMMY RDBMS CONNECTIONS
 
           For Oracle, placeholder connections cannot be created without a real
-          `_agentId` — the validator will reject them. Direct the user to install
-          a Celigo Agent first. For all other RDBMS types, a placeholder can be
+          `_agentId` or `_agentGroupId` — the validator will reject them. Direct the
+          user to install a Celigo Agent first. For all other RDBMS types, a placeholder can be
           created with dummy credentials matching the rules above.
       x-celigo-ui-override: 'Several requireds mirror the connection form rather than the API: snowflake.warehouse, redshift.clusterIdentifier, redshift.user, and mssql version. The API creates connections without them (live-verified 201), but the form requires them and a functional connection needs them. For mysql, postgresql, and mariadb the form makes password conditional — not required when a full SSL client certificate (ssl.ca, ssl.key, ssl.cert) is supplied instead; the conditional below keeps password required for the common (non-SSL) path, which is the only path the API enforces.'
       required:
@@ -11208,7 +11243,7 @@ components:
             postgresql: PostgreSQL database (default port 5432).
             mssql: Microsoft SQL Server (default port 1433).
             snowflake: Snowflake Data Cloud (requires snowflake.warehouse).
-            oracle: Oracle Database; runs in agent mode and requires a connection-level _agentId (default port 1521, uses serviceName instead of database).
+            oracle: Oracle Database; runs in agent mode and requires a connection-level _agentId or _agentGroupId (default port 1521, uses serviceName instead of database).
             bigquery: Google BigQuery; requires service account credentials in the bigquery sub-object.
             redshift: Amazon Redshift — provisioned clusters or Redshift Serverless; authenticates with static access keys or an AWS IAM role iClient (redshift.authType).
             mariadb: MariaDB database (default port 3306).
@@ -11433,7 +11468,7 @@ components:
                 iClient — a client secret, or on SQL Server a certificate — and
                 `_iClientId` must reference it. The SQL Server connection form
                 offers `azure-service-principal` in Cloud mode only and saves
-                `basic` for an on-premise connection (`_agentId` set).
+                `basic` for an on-premise connection (`_agentId` or `_agentGroupId` set).
               default: basic
               examples:
                 - basic
@@ -11899,9 +11934,9 @@ components:
           422 "Expected field: <field> to be present" if any of the three is missing. database is not
           required; when omitted, set it per operation instead.
         - |-
-          For an on-premise MongoDB instance, set the connection-level _agentId (the form's "On-premise"
-          mode) so traffic routes through a Celigo Agent. Cloud-reachable instances (including Atlas)
-          need no agent.
+          For an on-premise MongoDB instance, bind the connection to one agent (connection-level
+          _agentId) or to one agent group (_agentGroupId) — the form's "On-premise" mode — so traffic
+          routes through a Celigo Agent. Cloud-reachable instances (including Atlas) need no agent.
         - |-
           ## AUTHENTICATION
           Username and password are optional — only required when the MongoDB server has
@@ -12601,8 +12636,8 @@ components:
       description: |-
         Configuration for filesystem connections. Used when the connection type is "filesystem".
         Provides access to directories on a Celigo on-premise Agent's host or mounted network
-        drives, so a connection-level `_agentId` is required — cloud-only deployments cannot use
-        this type. File-based PGP encryption/decryption is configured through the connection-level
+        drives, so an on-premise binding is required — a connection-level `_agentId`, or an agent
+        group through `_agentGroupId` — and cloud-only deployments cannot use this type. File-based PGP encryption/decryption is configured through the connection-level
         `pgp` object.
       properties:
         ping:
@@ -12648,9 +12683,10 @@ components:
           mounted network drives.
 
           ## AGENT REQUIREMENT
-          A Celigo Agent is REQUIRED for filesystem connections (set _agentId on the parent
-          connection object). The agent provides the filesystem access — cloud-only
-          deployments cannot use this connection type.
+          A Celigo Agent is REQUIRED for filesystem connections: bind the parent connection
+          object to one agent (_agentId) or to one agent group (_agentGroupId) — one of the
+          two, never both. The agent provides the filesystem access — cloud-only deployments
+          cannot use this connection type.
     token:
       type: object
       description: |
@@ -13124,13 +13160,17 @@ components:
         Configuration for JDBC (Java Database Connectivity) connections. Used when the connection
         type is "jdbc". Provides access through Java JDBC drivers to databases not covered by the
         rdbms type — such as NetSuite SuiteAnalytics, Databricks, DB2, and Workday. The driver runs
-        on a Celigo on-premise Agent, so most jdbc connections need a connection-level _agentId.
+        on a Celigo on-premise Agent, so most jdbc connections need an on-premise binding — a
+        connection-level _agentId, or an agent group through _agentGroupId.
       x-celigo-ai-guidance:
         - The POST is rejected with 422 if type-specific required fields are missing (see the per-type conditional rules).
         - |-
-          The agent and activedirectory types require a real connection-level _agentId: the POST fails with
-          422 "The JDBC connection requires Agent. Expected field: _agentId to be present in the connection
-          doc." A placeholder cannot be created without one, so the user should install a Celigo Agent first.
+          The agent and activedirectory types require a real on-premise binding — a connection-level
+          _agentId, or an agent group through _agentGroupId (one of the two, never both; the agent-mode
+          check accepts either — live-verified for both agent and activedirectory: a POST carrying only
+          _agentGroupId is not answered with agent_mode_only): with neither, the POST fails with 422 "The JDBC
+          connection requires Agent. Expected field: _agentId to be present in the connection doc." A
+          placeholder cannot be created without one, so the user should install a Celigo Agent first.
           Other types commonly run on an agent too, but only these two are validator-enforced (live-verified
           celigo-labs-2 2026-06-11).
       x-celigo-ui-override: 'Two activedirectory requireds mirror the connection form rather than the API: password and port (default 389). The API creates an activedirectory connection without them (it auto-defaults port to 389), but the form requires both, so they are encoded to mirror the form. The workday user and password requireds are NOT form overrides — they are enforced by the API itself (POST returns 422 "Expected field: user/password to be present"). Per-type forms also require named entries inside jdbc.properties (netsuitejdbc AccountID + ServerDataSource; db2 AuthScheme; workday tenant/connectionType/authScheme; activedirectory LDAPVersion/BaseDN) — documented in prose since they live in the properties name/value array.'

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.