@celigo/api-specs 0.2.99 → 0.2.101

package/dist/import.yml

@@ -677,11 +677,11 @@ paths:
 
         The integrator.io UI never calls this path — the import editor's
         "Preview" and "Send" buttons both go through
-        `POST /v1/pageProcessors/preview`. This endpoint is the API-only,
-        unscoped counterpart to
-        `POST /v1/integrations/{_integrationId}/flows/{_flowId}/imports/preview`
-        — prefer this variant when previewing a standalone import that is not
-        yet associated with a flow.
+        `POST /v1/pageProcessors/preview`. This is the only import preview
+        route on the public API: unlike exports, imports have no flow-scoped
+        sibling — `POST /v1/integrations/{_integrationId}/flows/{_flowId}/imports/preview`
+        answers 404 `resource_not_found`. To preview an import inside its
+        flow, use `POST /v1/pageProcessors/preview`.
       requestBody:
         required: true
         content:
@@ -934,82 +934,6 @@ paths:
                         message: _connectionId is required.
         '401':
           $ref: '#/components/responses/401-unauthorized'
-  /v1/integrations/{_integrationId}/flows/{_flowId}/imports/preview:
-    post:
-      x-internal: false
-      summary: Preview import data
-      description: |
-        Runs the import pipeline — field mappings, transformations, and hooks —
-        against the supplied sample data and returns the per-record results.
-        Treat the preview as capable of executing the composed destination
-        request: its unscoped sibling (`POST /v1/imports/preview`) is verified
-        to write real records to live destinations and offers no option to
-        disable the send, so do not preview create/update imports against
-        production systems with data you do not want written. For a
-        compose-only preview of the destination request, use
-        `POST /v1/pageProcessors/preview` with `{preview: true}` on the
-        target entry.
-      operationId: previewImportData
-      tags:
-        - Imports
-      parameters:
-        - in: path
-          name: _integrationId
-          required: true
-          schema:
-            type: string
-            format: objectId
-            x-celigo-refModel: integrations
-            examples:
-              - 60a2c4e6f321d800129a1a3c
-          description: Integration ID
-        - in: path
-          name: _flowId
-          required: true
-          schema:
-            type: string
-            format: objectId
-            x-celigo-refModel: flows
-            examples:
-              - 64ff4b22612a134bd2f45538
-          description: Flow ID
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/PreviewRequest'
-            examples:
-              one_record:
-                summary: Preview an existing import against one sample record
-                value:
-                  _importId: 5f8d43a1b9e5a80011a35f2c
-                  sampleData:
-                    name: Acme Corp
-                    email: contact@acme.com
-      responses:
-        '200':
-          description: Successfully previewed import data
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PreviewResponse'
-              examples:
-                mapped_record:
-                  summary: Mapped record as composed for the destination
-                  value:
-                    data:
-                      - name: Acme Corp
-                        email: contact@acme.com
-                    errors: []
-        '400':
-          $ref: '#/components/responses/400-bad-request'
-        '401':
-          $ref: '#/components/responses/401-unauthorized'
-        '404':
-          $ref: '#/components/responses/404-not-found'
-        '422':
-          $ref: '#/components/responses/422-unprocessable-entity'
   /v1/imports/{_id}/dependencies:
     get:
       x-internal: false
@@ -12363,7 +12287,11 @@ components:
             - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
             - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
             - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-            - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+            - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+              and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+              structure — see the array's description). A child-bearing wrapper and a source-only row that
+              already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+              name changes the output; it does not complete the row
 
             IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
             hierarchical structure with nested mappings:
@@ -12378,8 +12306,9 @@ components:
             }
             ```
 
-            When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-            within a parent array.
+            When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+            empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+            structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
           examples:
             - name
             - address
@@ -13360,6 +13289,12 @@ components:
         object-array row left with no source, no destination and no remaining child `mappings` or
         `buildArrayHelper` entries; a row with only one of the two, and a source-less, destination-less
         wrapper that still has children, are kept.
+
+        The shape of the array is the mapper's **JSON structure**. Named top-level items produce an object
+        record (`record { }`). Exactly one top-level item with `dataType: objectarray` and no `generate` is
+        the `rows [ ]` structure: the mapped record is an array — usually one element per element of the
+        source array that root's `buildArrayHelper` iterates — Handlebars templates such as `http.body`
+        bind it as `rows` instead of `record`, and the mapping editor shows that row's destination disabled.
       x-celigo-ai-guidance:
         - |-
           Rows that exist in the saved document — including `Draft` and `Inactive` rows and
@@ -13368,6 +13303,14 @@ components:
           them. Only a row with neither source nor destination — and, for an object or
           object-array row, no remaining children — can be left out; the save would drop it
           anyway. A wrapper with children but no `generate` is kept by the save, so keep it.
+        - |-
+          A single unnamed top-level `objectarray` item is the `rows [ ]` JSON structure, not a
+          missing destination: keep it unnamed when editing (naming it turns the output into an
+          object, and a template that iterates `rows` then renders nothing), and author that
+          shape only when the request body must be an array or a template iterates `rows`.
+          The editor's save check accepts the unnamed root only in the `rows [ ]` structure;
+          any other row with a source and no `generate` fails with "One or more destination
+          field values not entered".
       items:
         type: object
         properties:
@@ -13383,7 +13326,11 @@ components:
               - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
               - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
               - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-              - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+              - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+                and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+                structure — see the array's description). A child-bearing wrapper and a source-only row that
+                already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+                name changes the output; it does not complete the row
 
               IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
               hierarchical structure with nested mappings:
@@ -13398,8 +13345,9 @@ components:
               }
               ```
 
-              When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-              within a parent array.
+              When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+              empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+              structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
             examples:
               - name
               - address
@@ -16364,6 +16312,23 @@ components:
               per-mode contract.  Handlebars expressions in ``extract`` always
               reference ``{{record.field}}`` regardless — only JSONPath
               behavior flips with ``inputContext``.
+            - |-
+              ## JSON structure — record { } or rows [ ]
+
+              The shape of this array is the mapper's JSON structure. Named
+              top-level items produce an object record; ``http.body`` and the
+              other templates bind it as ``record``. Exactly one top-level item
+              with ``dataType: objectarray`` and no ``generate`` is the
+              ``rows [ ]`` structure: the mapped record is an array — one
+              element per element the item's ``buildArrayHelper`` iterates —
+              and templates bind it as ``rows`` (``{{#each rows}}``), with
+              ``record.*`` undefined. The mapping editor shows that row's
+              destination disabled; its save check accepts the unnamed root
+              only in the ``rows [ ]`` structure and fails any other row that
+              has a source and no ``generate`` with "One or more destination
+              field values not entered". Keep the root unnamed when editing a
+              ``rows [ ]`` mapping — naming it turns the output into an object
+              and a ``{{#each rows}}`` body renders nothing.
             - |-
               ## IMPORT-SPECIFIC BEHAVIOR
 
@@ -17081,13 +17046,11 @@ components:
     ImportPreviewResponse:
       type: object
       description: |-
-        Envelope returned by `POST /v1/imports/preview` (and the scoped
-        `/v1/integrations/{_integrationId}/flows/{_flowId}/imports/preview`
-        variant). Carries per-stage diagnostics alongside the sampled records
-        produced by running the supplied source data through the import's
-        mapping/transform/target pipeline. The target stage executes the
-        composed destination request — see the operation descriptions for the
-        write-safety warning.
+        Envelope returned by `POST /v1/imports/preview`. Carries per-stage
+        diagnostics alongside the sampled records produced by running the
+        supplied source data through the import's mapping/transform/target
+        pipeline. The target stage executes the composed destination request —
+        see the operation description for the write-safety warning.
       properties:
         data:
           type: array
@@ -17283,67 +17246,6 @@ components:
                 celigo_classname:
                   type: string
                   description: Internal engine class name for the result (e.g. `Celigo.integrator.mapping.model.MapToNetSuiteResult`).
-    PreviewRequest:
-      type: object
-      description: |
-        Request body for running sample data through an import's pipeline
-        (mappings, transformations, hooks). The preview can execute the
-        composed destination request — see the operation descriptions for the
-        write-safety warning.
-      properties:
-        _importId:
-          type: string
-          format: objectId
-          x-celigo-refModel: imports
-          description: The import to preview. Required when previewing within a flow.
-          examples:
-            - 5f8d43a1b9e5a80011a35f2c
-        sampleData:
-          description: |
-            Sample source record(s) to run through the import's mappings and transformations.
-            May be a single object or an array of objects depending on the adaptor.
-          oneOf:
-            - title: Single record
-              type: object
-              additionalProperties: true
-            - title: Array of records
-              type: array
-              items:
-                type: object
-                additionalProperties: true
-        options:
-          type: object
-          description: Optional overrides applied only for this preview.
-          additionalProperties: true
-      additionalProperties: true
-    PreviewResponse:
-      type: object
-      description: |
-        Result of running a preview against the configured import. Shows the
-        mapped/transformed records as composed for the destination.
-      properties:
-        data:
-          type: array
-          description: Mapped and transformed records produced by the import.
-          items:
-            type: object
-            additionalProperties: true
-        errors:
-          type: array
-          description: Any validation or transformation errors encountered while building the preview.
-          items:
-            type: object
-            properties:
-              code:
-                type: string
-                description: Machine-readable code identifying the type of preview error.
-              message:
-                type: string
-                description: Human-readable explanation of what went wrong while building the preview.
-              path:
-                type: string
-                description: Path to the field or configuration element the error relates to.
-      additionalProperties: true
     DependencyEntry:
       type: object
       description: A single resource that depends on the queried resource.

package/dist/integration.yml

@@ -365,8 +365,8 @@ paths:
       x-internal: false
       summary: Clone an integration
       description: |
-        Creates a copy of an existing integration.
-        Supports optionally remapping referenced connections (via connectionMap).
+        Creates a copy of an existing integration. When the source has registered
+        connections, remap each one via `connectionMap`; mapped connections are reused, not cloned.
       operationId: cloneIntegration
       tags:
         - Integrations
@@ -382,7 +382,7 @@ paths:
             examples:
               - 69680d7111d1437fbcbce534
       requestBody:
-        required: false
+        required: true
         content:
           application/json:
             schema:
@@ -397,8 +397,8 @@ paths:
                     626168f90b6ef816b50c82d7: 64a1234567890abcdef12345
                     6553ebdeda62bb22e7fa81ff: 64a1234567890abcdef12346
       responses:
-        '200':
-          description: Integration cloned successfully
+        '201':
+          description: Integration cloned successfully. Returns a manifest of the resources the clone created.
           content:
             application/json:
               schema:
@@ -4063,7 +4063,10 @@ components:
           description: |-
             UI grouping configuration that groups an integration's flows into named
             sections. Works on ANY integration — this is NOT an Integration-App-only
-            feature; a plain integration can define flow groupings too.
+            feature; a plain integration can define flow groupings too. Create groupings
+            here, then assign flows to them via `PUT /v1/flows/updateFlowGrouping`. A
+            grouping that still has member flows survives being removed from this array —
+            ungroup its flows first.
 
             Omit unless you are explicitly configuring flow grouping behavior.
           x-celigo-ai-guidance:
@@ -4071,6 +4074,17 @@ components:
               Set this ONLY when the user explicitly asks to group flows into named sections (e.g.
               "create the integration with flow groups Order Intake and Fulfillment").
               Otherwise omit it — do not synthesize groupings the user did not ask for.
+            - |-
+              `Unassigned` is a reserved name (422 `invalid_flowgrouping_name`) and names and `_id`s
+              must be unique within the integration (422 `duplicate_field`) — on POST, PUT and PATCH
+              alike.
+            - |-
+              Removing a grouping that still has member flows returns success but leaves the
+              grouping in place; move those flows with `PUT /v1/flows/updateFlowGrouping` first.
+            - |-
+              `POST` and `PUT` answer with the saved integration, so a new grouping's `_id` is
+              in the response; `PATCH` answers `204` with no body, so after a patch the `_id`
+              comes from a follow-up `GET`.
           items:
             type: object
             additionalProperties: true
@@ -4478,11 +4492,11 @@ components:
       type: object
       description: Request body for cloning an integration.
       required:
-        - connectionMap
+        - name
       properties:
         name:
           type: string
-          description: Name for the cloned integration. If omitted, the server generates "Clone - <original name>".
+          description: Name for the cloned integration.
           examples:
             - Clone - Integration 1
         description:
@@ -4506,6 +4520,9 @@ components:
             Mapping of original connection _ids to replacement connection _ids.
             Keys are source connection _ids on the original integration; values
             are target connection _ids in the destination environment.
+            Required when the source integration has registered connections — omitting it or
+            sending an empty map fails with 400 `invalid_connectionMap`. Map a connection to
+            itself to reuse it in the clone; omit the map when the source has none.
           additionalProperties:
             type: string
           example: