@celigo/api-specs 0.2.104 → 0.2.106

package/dist/connection.yml

@@ -1573,11 +1573,13 @@ paths:
         The step runs with the document's own `settings` only: hooks receive
         `options.settings` with an `import` key but no `integration` or `flow`
         key and no `_flowId` / `_integrationId`; `{{settings.integration.*}}`
-        and `{{settings.flow.*}}` templates render empty. A document that reads
-        integration- or flow-level settings behaves differently here than in a
-        flow run, and nothing in the request supplies that context. The
-        connection in the path is the one used; a `_connectionId` on the
-        document is ignored.
+        and `{{settings.flow.*}}` templates render empty. To run the document
+        with the context a real run of its parent supplies, use the
+        integration-scoped forms —
+        `POST /v1/integrations/{_integrationId}/flows/{_flowId}/connections/{_connectionId}/import`
+        and the `tools/{_toolId}` and `apis/{_apiId}` siblings. The connection
+        in the path is the one used; a `_connectionId` on the document is
+        ignored.
 
         `POST /v1/imports/{_id}/invoke` runs a saved import the same way with
         the same per-record shape; the read-side sibling is the virtual export,
@@ -1608,8 +1610,10 @@ paths:
                   The step gets the document's own settings only: hooks see `options.settings = {import}`
                   with no `integration` / `flow` key and no `_flowId` / `_integrationId`, and
                   `{{settings.integration.*}}` / `{{settings.flow.*}}` render empty. A step whose hooks or
-                  templates read those settings builds a different record here than in a flow run — do
-                  not send it this way.
+                  templates read those settings builds a different record here than in a flow run — send
+                  it through the integration-scoped form
+                  (`/v1/integrations/{_integrationId}/flows/{_flowId}/connections/{_connectionId}/import`,
+                  or the `tools` / `apis` sibling) instead, which resolves that context from the URL.
                 - |-
                   NetSuite and RDBMS documents run here, where `POST /v1/imports/preview` answers
                   `invalid_adaptor`. A record the input filter excludes comes back
@@ -1889,6 +1893,540 @@ paths:
                       - field: connection
                         code: invalid_ref
                         message: connection not found.
+  /v1/integrations/{_integrationId}/flows/{_flowId}/connections/{_connectionId}/import:
+    post:
+      x-internal: false
+      operationId: invokeVirtualImportForFlow
+      tags:
+        - Connections
+      summary: Run an import document through a connection as a step of a flow
+      description: |-
+        Runs an import document sent in the request body — a virtual import —
+        through the connection, with the flow and the integration in the
+        path supplying the execution context a real run gives the step — hooks receive `options.settings` with the flow's and the integration's settings (a resource with none contributes no key) plus `_flowId` / `_integrationId`, as on the flow's own preview chain.
+        Nothing is saved — the document can be an unsaved draft, a modified
+        copy, or a saved import as fetched — and the request executes against
+        the live destination: a real write; a saved
+        `mockResponse` does not substitute. Pipeline and per-record result are
+        those of `POST /v1/connections/{_id}/import`, which runs the document
+        with its own settings only. The flow must belong to the
+        integration, the connection must be registered to it, and the caller
+        needs manage access to the account or the integration.
+      parameters:
+        - in: path
+          name: _integrationId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6a0602a45927c70694e1092b
+          description: Integration whose settings feed the execution context; the flow and the connection must belong to it.
+        - in: path
+          name: _flowId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: flows
+            examples:
+              - 6ac3ee0a12b28806990380d3
+          description: Flow whose settings feed the execution context; must belong to the integration.
+        - in: path
+          name: _connectionId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 6a04b5309dc296c4efb1a6e0
+          description: Connection the import document runs through; must be registered to the integration.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ScopedVirtualImportRequest'
+            examples:
+              saved_import_one_record:
+                summary: Run a step's saved document against one record
+                value:
+                  import:
+                    adaptorType: HTTPImport
+                    mapping:
+                      fields:
+                        - extract: email
+                          generate: Email
+                      lists: []
+                    http:
+                      relativeURI:
+                        - /post
+                      method:
+                        - POST
+                      requestType:
+                        - CREATE
+                      requestMediaType: json
+                      successMediaType: json
+                      sendPostMappedData: true
+                      formType: http
+                  data:
+                    - email: contact@acme.com
+      responses:
+        '200':
+          description: |-
+            One result per input record, in input order — accepted, failed at
+            the destination, or ignored by the document's own input filter.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ImportRecordResult'
+              examples:
+                accepted:
+                  summary: Record accepted — the destination's response body in _json
+                  value:
+                    - statusCode: 200
+                      _json:
+                        Email: contact@acme.com
+                      _headers:
+                        content-type: application/json; charset=utf-8
+                destination_rejected:
+                  summary: Destination rejected the record
+                  value:
+                    - statusCode: 422
+                      _json: {}
+                      errors:
+                        - message: 'Failed to create, update/transform record because com.netledger.common.exceptions.NLUserError: The record type [CUSTOMRECORD_ZZ] is invalid.'
+                          code: javaexception
+                          source: application
+                          resolved: false
+                          occurredAt: 1791309460117
+                          stage: apiCall
+                          classification: missing
+        '400':
+          description: |-
+            `invalid_request`, in one of two shapes: the `errors[]` envelope when
+            the flow does not belong to the integration in the path (also
+            the answer for an unknown integration id), or the bare error array
+            `POST /v1/connections/{_id}/import` returns when the body is
+            malformed — the top-level `import` object or the `data` array is
+            missing.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/Error'
+                  - title: Body validation errors
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        code:
+                          type: string
+                        message:
+                          type: string
+              examples:
+                not_in_integration:
+                  summary: The flow is not in the integration
+                  value:
+                    errors:
+                      - code: invalid_request
+                        source: integrator
+                        message: The flow 6ace605a6ac2e65233ea4c3c does not belong to the integration 6a0215e99a09438890eb3e8b.
+                missing_data:
+                  summary: Malformed body — the data array is missing
+                  value:
+                    - code: invalid_request
+                      message: Request body should contain data which is to be imported.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            `invalid_request` — the connection is not registered to the
+            integration (an unknown connection id answers the same).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                connection_not_registered:
+                  value:
+                    errors:
+                      - code: invalid_request
+                        source: integrator
+                        message: The connection 6a0000000000000000000000 is not registered to the integration 6a0215e99a09438890eb3e8b.
+        '404':
+          description: '`invalid_ref` — no flow with the given id is visible to the account.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                flow_not_found:
+                  value:
+                    errors:
+                      - field: _flowId
+                        code: invalid_ref
+                        message: unable to find flow for the given id.
+  /v1/integrations/{_integrationId}/tools/{_toolId}/connections/{_connectionId}/import:
+    post:
+      x-internal: false
+      operationId: invokeVirtualImportForTool
+      tags:
+        - Connections
+      summary: Run an import document through a connection as a step of a tool
+      description: |-
+        Runs an import document sent in the request body — a virtual import —
+        through the connection, with the tool and the integration in the
+        path supplying the execution context a real run gives the step — hooks receive `options.settings` with the integration's settings (none when it carries none) plus `_integrationId`, and no flow.
+        Nothing is saved — the document can be an unsaved draft, a modified
+        copy, or a saved import as fetched — and the request executes against
+        the live destination: a real write, not a dry run; a saved
+        `mockResponse` does not substitute. Pipeline and per-record result are
+        those of `POST /v1/connections/{_id}/import`, which runs the document
+        with its own settings only. The tool must belong to the
+        integration, the connection must be registered to it, and the caller
+        needs manage access to the account or the integration.
+      parameters:
+        - in: path
+          name: _integrationId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6a0602a45927c70694e1092b
+          description: Integration whose settings feed the execution context; the tool and the connection must belong to it.
+        - in: path
+          name: _toolId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: tools
+            examples:
+              - 6ac3e6667968a10c70628911
+          description: Tool the step belongs to; must belong to the integration.
+        - in: path
+          name: _connectionId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 6a04b5309dc296c4efb1a6e0
+          description: Connection the import document runs through; must be registered to the integration.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ScopedVirtualImportRequest'
+            examples:
+              saved_import_one_record:
+                summary: Run a step's saved document against one record
+                value:
+                  import:
+                    adaptorType: HTTPImport
+                    mapping:
+                      fields:
+                        - extract: email
+                          generate: Email
+                      lists: []
+                    http:
+                      relativeURI:
+                        - /post
+                      method:
+                        - POST
+                      requestType:
+                        - CREATE
+                      requestMediaType: json
+                      successMediaType: json
+                      sendPostMappedData: true
+                      formType: http
+                  data:
+                    - email: contact@acme.com
+      responses:
+        '200':
+          description: |-
+            One result per input record, in input order — accepted, failed at
+            the destination, or ignored by the document's own input filter.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ImportRecordResult'
+              examples:
+                accepted:
+                  summary: Record accepted — the destination's response body in _json
+                  value:
+                    - statusCode: 200
+                      _json:
+                        Email: contact@acme.com
+                      _headers:
+                        content-type: application/json; charset=utf-8
+                destination_rejected:
+                  summary: Destination rejected the record
+                  value:
+                    - statusCode: 422
+                      _json: {}
+                      errors:
+                        - message: 'Failed to create, update/transform record because com.netledger.common.exceptions.NLUserError: The record type [CUSTOMRECORD_ZZ] is invalid.'
+                          code: javaexception
+                          source: application
+                          resolved: false
+                          occurredAt: 1791309460117
+                          stage: apiCall
+                          classification: missing
+        '400':
+          description: |-
+            `invalid_request`, in one of two shapes: the `errors[]` envelope when
+            the tool does not belong to the integration in the path (also
+            the answer for an unknown integration id), or the bare error array
+            `POST /v1/connections/{_id}/import` returns when the body is
+            malformed — the top-level `import` object or the `data` array is
+            missing.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/Error'
+                  - title: Body validation errors
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        code:
+                          type: string
+                        message:
+                          type: string
+              examples:
+                not_in_integration:
+                  summary: The tool is not in the integration
+                  value:
+                    errors:
+                      - code: invalid_request
+                        source: integrator
+                        message: The tool 6ace605a6ac2e65233ea4c3c does not belong to the integration 6a0215e99a09438890eb3e8b.
+                missing_data:
+                  summary: Malformed body — the data array is missing
+                  value:
+                    - code: invalid_request
+                      message: Request body should contain data which is to be imported.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            `invalid_request` — the connection is not registered to the
+            integration (an unknown connection id answers the same).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                connection_not_registered:
+                  value:
+                    errors:
+                      - code: invalid_request
+                        source: integrator
+                        message: The connection 6a0000000000000000000000 is not registered to the integration 6a0215e99a09438890eb3e8b.
+        '404':
+          description: '`invalid_ref` — no tool with the given id is visible to the account.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                tool_not_found:
+                  value:
+                    errors:
+                      - field: _toolId
+                        code: invalid_ref
+                        message: unable to find tool for the given id.
+  /v1/integrations/{_integrationId}/apis/{_apiId}/connections/{_connectionId}/import:
+    post:
+      x-internal: false
+      operationId: invokeVirtualImportForApi
+      tags:
+        - Connections
+      summary: Run an import document through a connection as a step of an API
+      description: |-
+        Runs an import document sent in the request body — a virtual import —
+        through the connection, with the API and the integration in the
+        path supplying the execution context a real run gives the step — hooks receive `options.settings` with the integration's settings (none when it carries none) plus `_integrationId`, and no flow.
+        Nothing is saved — the document can be an unsaved draft, a modified
+        copy, or a saved import as fetched — and the request executes against
+        the live destination: a real write, not a dry run; a saved
+        `mockResponse` does not substitute. Pipeline and per-record result are
+        those of `POST /v1/connections/{_id}/import`, which runs the document
+        with its own settings only. The API must belong to the
+        integration, the connection must be registered to it, and the caller
+        needs manage access to the account or the integration.
+      parameters:
+        - in: path
+          name: _integrationId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6a0602a45927c70694e1092b
+          description: Integration whose settings feed the execution context; the API and the connection must belong to it.
+        - in: path
+          name: _apiId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 6ac5966390f6ab94d6429012
+          description: API the step belongs to; must belong to the integration.
+        - in: path
+          name: _connectionId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 6a04b5309dc296c4efb1a6e0
+          description: Connection the import document runs through; must be registered to the integration.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ScopedVirtualImportRequest'
+            examples:
+              saved_import_one_record:
+                summary: Run a step's saved document against one record
+                value:
+                  import:
+                    adaptorType: HTTPImport
+                    mapping:
+                      fields:
+                        - extract: email
+                          generate: Email
+                      lists: []
+                    http:
+                      relativeURI:
+                        - /post
+                      method:
+                        - POST
+                      requestType:
+                        - CREATE
+                      requestMediaType: json
+                      successMediaType: json
+                      sendPostMappedData: true
+                      formType: http
+                  data:
+                    - email: contact@acme.com
+      responses:
+        '200':
+          description: |-
+            One result per input record, in input order — accepted, failed at
+            the destination, or ignored by the document's own input filter.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ImportRecordResult'
+              examples:
+                accepted:
+                  summary: Record accepted — the destination's response body in _json
+                  value:
+                    - statusCode: 200
+                      _json:
+                        Email: contact@acme.com
+                      _headers:
+                        content-type: application/json; charset=utf-8
+                destination_rejected:
+                  summary: Destination rejected the record
+                  value:
+                    - statusCode: 422
+                      _json: {}
+                      errors:
+                        - message: 'Failed to create, update/transform record because com.netledger.common.exceptions.NLUserError: The record type [CUSTOMRECORD_ZZ] is invalid.'
+                          code: javaexception
+                          source: application
+                          resolved: false
+                          occurredAt: 1791309460117
+                          stage: apiCall
+                          classification: missing
+        '400':
+          description: |-
+            `invalid_request`, in one of two shapes: the `errors[]` envelope when
+            the API does not belong to the integration in the path (also
+            the answer for an unknown integration id), or the bare error array
+            `POST /v1/connections/{_id}/import` returns when the body is
+            malformed — the top-level `import` object or the `data` array is
+            missing.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/Error'
+                  - title: Body validation errors
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        code:
+                          type: string
+                        message:
+                          type: string
+              examples:
+                not_in_integration:
+                  summary: The API is not in the integration
+                  value:
+                    errors:
+                      - code: invalid_request
+                        source: integrator
+                        message: The api 6ace605a6ac2e65233ea4c3c does not belong to the integration 6a0215e99a09438890eb3e8b.
+                missing_data:
+                  summary: Malformed body — the data array is missing
+                  value:
+                    - code: invalid_request
+                      message: Request body should contain data which is to be imported.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            `invalid_request` — the connection is not registered to the
+            integration (an unknown connection id answers the same).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                connection_not_registered:
+                  value:
+                    errors:
+                      - code: invalid_request
+                        source: integrator
+                        message: The connection 6a0000000000000000000000 is not registered to the integration 6a0215e99a09438890eb3e8b.
+        '404':
+          description: '`invalid_ref` — no API with the given id is visible to the account.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                api_not_found:
+                  value:
+                    errors:
+                      - field: _apiId
+                        code: invalid_ref
+                        message: unable to find api for the given id.
   /v1/connections/{_id}/debug:
     get:
       x-internal: false
@@ -9378,6 +9916,57 @@ components:
                 type: string
             additionalProperties: true
       additionalProperties: true
+    ScopedVirtualImportRequest:
+      type: object
+      description: |-
+        The import document to run and the records to run through it — the
+        same body as `POST /v1/connections/{_id}/import`. The parent (flow,
+        tool or API) and the integration in the URL supply the execution
+        context; the body carries no `settings`.
+      x-celigo-ai-guidance:
+        - |-
+          This executes the request against the live destination — a real write, even when the
+          document carries a saved `mockResponse`. Treat it like a run of the parent, never like a
+          preview.
+        - |-
+          Hooks and templates see the context a real run of the parent gives them: for a flow step,
+          `options.settings` carries `import`, `flow` and `integration` with `_flowId` /
+          `_integrationId` — identical to the flow's own preview chain; for a tool or an API step it
+          carries `import` and `integration` with `_integrationId` and no flow. A parent or
+          integration with no settings contributes no key at all (no `integration` key when the
+          integration carries none).
+        - |-
+          The connection in the path must be registered to the integration in the path (flows and
+          tools register the connections their steps use) — an unregistered or unknown connection is a
+          `403 invalid_request`; a parent that is not in the integration is a `400 invalid_request` in
+          the `errors[]` envelope (an unknown integration id answers the same, the membership check
+          running first); an unknown flow, tool or API id is a `404 invalid_ref` on the parent's path
+          field. NetSuite and RDBMS documents run here, where `POST /v1/imports/preview` answers
+          `invalid_adaptor`. A record the input filter excludes comes back
+          `{ignored: true, stage: "inputFilter"}` and was never sent; omitting `import` or `data` is a
+          `400 invalid_request` in the bare error array `POST /v1/connections/{_id}/import` returns.
+      required:
+        - import
+        - data
+      properties:
+        import:
+          type: object
+          description: |-
+            The import document to run (mirror of the `POST /v1/imports` body
+            shape); `name` and `_connectionId` are not needed, and a saved
+            import's `_id` and metadata may ride along unchanged.
+            Adaptor-specific blocks (`http`, `netsuite_da`, `rdbms`, …),
+            `mapping`, `filter` and `hooks` apply exactly as on a saved import.
+          additionalProperties: true
+        data:
+          type: array
+          description: |-
+            Records to run through the document, each becoming one result. An
+            empty array returns an empty array; omitting `data` is rejected.
+          items:
+            type: object
+            additionalProperties: true
+      additionalProperties: true
     ConnectionMetadataRequest:
       type: object
       description: |-