@celigo/api-specs 0.2.213 → 0.2.215

package/dist/connection.yml

@@ -1028,7 +1028,7 @@ paths:
         | `/autoRecoverRateLimitErrors` | Rate-limit auto-recovery toggle. Turning it on copies the current level into the target; turning it off unsets the target and leaves the level at its current value |
         | `/http/rateLimit/failStatusCode`, `/http/rateLimit/failPath`, `/http/rateLimit/failHeaders` | Rate-limit detection rules. Send `failHeaders` as the whole array; on one element only `replace` of an existing entry works (e.g. `/http/rateLimit/failHeaders/0`), and `add` or `remove` on an element fails with 422 |
         | `/http/rateLimit/limit` | Wait between consecutive requests, in milliseconds. Accepted only at a concurrency of 1: set `/http/targetConcurrencyLevel` (while `autoRecoverRateLimitErrors` is true) or `/http/concurrencyLevel` (while it is false) to 1 in the same patch; at any other level it fails with 422 `invalid_concurrency_level` |
-        | `/endUserProvidedFields` | Dot-paths MCP end users must supply on their own child copy of this connection. `replace` with `[]` or `remove` clears the list, and `add` on `/endUserProvidedFields/-` appends one path; a path the account owns (`type`, `_agentId`, `wrapper._stackId`, any `<adaptor>._iClientId`) is rejected |
+        | `/endUserProvidedFields` | Dot-paths MCP end users must supply on their own child copy of this connection. `replace` with `[]` or `remove` clears the list, and `add` on `/endUserProvidedFields/-` appends one path; a path the account owns (`type`, `_agentId`, `_agentGroupId`, `wrapper._stackId`, any `<adaptor>._iClientId`) is rejected |
 
         `replace` and `add` both set the value (a currently unset field is fine);
         `remove` unsets it. A `null` value is rejected. Any other path — including
@@ -4175,11 +4175,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
@@ -6957,8 +6968,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:
@@ -7009,16 +7022,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:
@@ -7041,7 +7055,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).
@@ -7266,7 +7280,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
@@ -7732,9 +7746,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
@@ -8434,8 +8448,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:
@@ -8481,9 +8495,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: |
@@ -8957,13 +8972,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.'
@@ -9910,12 +9929,32 @@ components:
           format: objectId
           x-celigo-refModel: agents
           description: |-
-            Reference to a Celigo on-premise Agent. Required for types that need local network or
-            filesystem access (filesystem, jdbc agent/activedirectory, Oracle rdbms, and on-premise
-            mongodb). The agent establishes a secure tunnel between the on-premise environment and
-            integrator.io.
+            Reference to a Celigo on-premise Agent. Types that run on an agent (filesystem, jdbc
+            agent/activedirectory, Oracle rdbms, and on-premise mongodb) need one binding — this
+            agent, or an agent group through `_agentGroupId`; either satisfies the requirement
+            (live-verified for filesystem, jdbc `agent` and `activedirectory`, and Oracle: with
+            neither id the POST answers 422 `agent_mode_only`; with `_agentGroupId` alone it does not).
+            The agent establishes a secure tunnel between the on-premise environment and
+            integrator.io. The connection form writes one of the two ids and omits the other; a
+            connection never carries both.
           examples:
             - 5f8d43a1b9e5a80011a35f2c
+        _agentGroupId:
+          type: string
+          format: objectId
+          x-celigo-refModel: agentgroups
+          description: |-
+            On-premise agent group that serves this connection instead of a single
+            `_agentId`; a connection binds one or the other, never both — the connection
+            form writes one id and omits the other. Requests go to the first healthy
+            member in the group's priority order (source-only: the dispatch rule the
+            platform implements), so one host failing does not stop the flow. On an
+            account whose license does not include agent groups, sending it fails with
+            422 `agent_groups_subscription_required` — "Your license does not support
+            the agent groups feature." (live-verified); an id that names no group adds
+            422 `invalid_ref` on `_agentGroupId` to the same response.
+          examples:
+            - 6650a1b2c3d4e5f60718293a
         _borrowConcurrencyFromConnectionId:
           type: string
           format: objectId
@@ -10001,9 +10040,10 @@ components:
           x-celigo-ai-guidance:
             - |-
               List only the credential and tenant fields that differ per end user, never a path the
-              account owns: `type`, `_agentId`, `wrapper._stackId`, or any `<adaptor>._iClientId`
+              account owns: `type`, `_agentId`, `_agentGroupId`, `wrapper._stackId`, or any `<adaptor>._iClientId`
               (e.g. `http._iClientId`) fails the save with 422
-              `mcp_end_user_provided_field_not_allowed`.
+              `mcp_end_user_provided_field_not_allowed` (live-verified for `_agentGroupId`:
+              "_agentGroupId is managed by the account owner and cannot be requested from an end user.").
             - |-
               This is the only MCP end-user field writable through `/v1/connections`; the child
               connections themselves are created by the end-user setup page, and `connectionRole:
@@ -10216,7 +10256,11 @@ components:
                       then:
                         required:
                           - filesystem
-                          - _agentId
+                        anyOf:
+                          - required:
+                              - _agentId
+                          - required:
+                              - _agentGroupId
                       else:
                         if:
                           properties:
@@ -10260,8 +10304,11 @@ components:
                                 required:
                                   - jdbc
                               then:
-                                required:
-                                  - _agentId
+                                anyOf:
+                                  - required:
+                                      - _agentId
+                                  - required:
+                                      - _agentGroupId
                             else:
                               if:
                                 properties:

package/dist/enduser.yml

@@ -2200,11 +2200,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
@@ -4982,8 +4993,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:
@@ -5034,16 +5047,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:
@@ -5066,7 +5080,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).
@@ -5291,7 +5305,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
@@ -5757,9 +5771,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
@@ -6459,8 +6473,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:
@@ -6506,9 +6520,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: |
@@ -6982,13 +6997,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/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: