@celigo/api-specs 0.2.125 → 0.2.127

package/dist/import.yml

@@ -2951,6 +2951,12 @@ components:
             regardless of server OS — paths are case-sensitive on UNIX/Linux servers. Supports
             handlebars templates.
           x-celigo-ai-guidance:
+            - |-
+              A handlebars template here is rendered against the same context as `fileName`
+              (`fileMeta` is not a root key). An expression that renders empty fails the record
+              with `missing_s3_key` "Can not process upload file without
+              computedObject.fileLocation." — labeled source `internal` although the template is
+              the cause.
             - |-
               The path to the directory on the FTP server where files will be accessed,
               stored, or managed.
@@ -3007,13 +3013,28 @@ components:
           description: |-
             Name of the file written to the server, including its extension; do not include directory
             separators — the location comes from directoryPath. Supports handlebars placeholders such
-            as items-{{timestamp}}.csv to generate a unique name per run.
+            as items-{{timestamp}}.csv to generate a unique name per run. The template is rendered
+            against the incoming record: a file-transfer import from an FTP source kept the source
+            file's name with `{{record.fileMeta.fileName}}` set on `file.fileName` and this field left
+            unset — other source providers expose the name under their own `fileMeta` field.
           x-celigo-ai-guidance:
             - |-
               When the user does not specify a file naming convention,
               default to a timestamped filename such as "items-{{timestamp}}.csv" so each run
               produces a unique file and avoids overwriting previous files.
               Use a fixed filename only when the user explicitly requests overwriting or a fixed name.
+            - |-
+              `fileMeta` is not a root key of this template's context (it is one only on
+              file-provider export and lookup steps): `{{fileMeta.fileName}}` renders empty and the
+              upload fails with `missing_s3_key` "Can not process upload file without
+              computedObject.fileName." — an error the platform labels source `internal` although the
+              template is the cause. The run-time-proven way to keep the source file's name on a
+              `blob: true` import is `{{record.fileMeta.fileName}}` on `file.fileName` with this field
+              omitted (the production runs of one FTP blob import set exactly that); the same template
+              on this field has not been run. The field's editor preview (data version 1, its default)
+              exposes the record as `data` —
+              the `{blobKey, fileMeta}` record on a blob import, the page's record array otherwise —
+              so `record.` previews empty there; judge by a run.
             - |-
               The name of the file to be accessed, transferred,
               or manipulated via FTP (File Transfer Protocol).
@@ -3820,7 +3841,11 @@ components:
               field mapped to `internalid` is overridden by it. When the incoming record
               already carries the NetSuite internal ID, point the lookup at that field with
               the expression form — `["internalid","is","{{{id}}}"]` — rather than removing
-              the lookup.
+              the lookup. Only when every record carries it: on `restletVersion:
+              suiteapp2.0` a record whose field is empty does not fall through to
+              "create" on `addupdate` — the empty value is searched as `isempty` and
+              can match an existing record (see `expression`; SuiteBundle and SuiteApp
+              1.0 create in that case).
           properties:
             extract:
               type: string
@@ -3946,6 +3971,21 @@ components:
                   - DO NOT use `jsonSerialize` here — search expressions take
                     scalar literals, not serialized JSON.  Use `{{{id}}}` or
                     `{{{[Field Name]}}}` directly.
+                - |-
+                  ## A substitution that renders empty is not "no match"
+
+                  When the source field is absent or empty, `["internalid","is","{{{id}}}"]`
+                  renders `["internalid","is",""]`, and the SuiteApp rewrites an empty
+                  `is` / `equalto` / `internalid anyof` value to `isempty` before the
+                  search. On `restletVersion: suiteapp2.0` that search is not treated as
+                  "no match": it can return existing records, and `addupdate` then
+                  updates one of them — an unrelated record receives the mapping (seen
+                  in production as `cant_modify_sub` on a customer the record never
+                  named). SuiteBundle and SuiteApp 1.0 discard a blank `internalid`
+                  match and create. Design so the operational lookup never renders
+                  empty: key it on a value every record carries (the source id stored
+                  as `externalid`), or route records without a destination id to a
+                  separate `add` import.
                 - |-
                   ## Body-level only
 
@@ -8522,7 +8562,10 @@ components:
           description: |-
             **REQUIRED for file-based imports.**
 
-            The name of the file to be created/written. Supports Handlebars expressions for dynamic naming.
+            The name of the file to be created/written. Supports Handlebars expressions for dynamic naming,
+            rendered against the incoming record — a file-transfer import keeps the source file's name from
+            the record's `fileMeta`, whose field names are the exporting provider's
+            (`{{record.fileMeta.fileName}}` from an FTP source, `fileMeta.name` from Google Drive).
 
             **Default behavior**
             - When the user does not specify a file naming convention, **always default to timestamped filenames** using `{{timestamp}}` (e.g., `"items-{{timestamp}}.csv"`). This ensures each run produces a unique file and avoids overwriting previous exports.
@@ -8540,7 +8583,20 @@ components:
 
             **Important**
             - For S3 imports, this should typically match the `s3.fileKey` value
-            - For FTP imports, this should typically match the `ftp.fileName` value
+            - For FTP imports, this should typically match the `ftp.fileName` value; the one blob file-transfer run on record set only this field and left `ftp.fileName` unset
+          x-celigo-ai-guidance:
+            - |-
+              `fileMeta` is not a root key of this template's context (it is one only on
+              file-provider export and lookup steps): `{{fileMeta.fileName}}` renders empty and the
+              file has no name; on an FTP import the record then fails with `missing_s3_key` "Can not
+              process upload file without computedObject.fileName.", labeled source `internal`
+              although the template is the cause. The incoming record carries the source file's
+              metadata — on an FTP blob import `{{record.fileMeta.fileName}}` keeps the source file's
+              name at run time (the only spelling proven by a run). The field's editor preview
+              (data version 1, its default) exposes the record as `data` — the `{blobKey, fileMeta}`
+              record on a `blob: true` import, the page's record array otherwise — so `record.`
+              previews empty there; judge by a run. The metadata field names are the exporting
+              provider's — read them off the incoming sample record.
           examples:
             - customers-{{timestamp}}.json
             - orders-export.csv
@@ -16021,6 +16077,14 @@ components:
               On AiAgentImport, GuardrailImport and ToolImport the save fails with 422 `not_supported`
               ("Field "blobKeyPath" is not supported for this import type."); route file content
               through a blob-capable import (HTTP, FTP, S3) instead.
+            - |-
+              Optional on a `blob: true` file-provider import: when omitted the platform reads the
+              record's root `blobKey` — the field a blob export emits on its `{blobKey, fileMeta}`
+              record — so a file-transfer flow needs no `blobKeyPath`. Observed on an FTP import
+              (production runs writing files with no `blobKeyPath`) and on a Google Drive folder
+              upload (`http.type: file`, the marketplace file-transfer template's shape); other
+              file providers were not probed. Set it only when a response mapping placed the key
+              elsewhere; on those two providers its absence is not a cause of upload failures.
             - |-
               The value at this path must be a blobKey produced by an upstream blob
               export or blob lookup and carried onto the record via that step's
@@ -16049,7 +16113,8 @@ components:
             - ToolImport
           description: |-
             When true, this import transfers raw file content (blobs) to the destination rather than
-            structured records, reading each file through `blobKeyPath`. Not accepted on
+            structured records, reading each file through `blobKeyPath` (optional on FTP and Google
+            Drive file-provider imports, which fall back to the record's root `blobKey`). Not accepted on
             `AiAgentImport`, `GuardrailImport`, or `ToolImport` — those adaptors process records only
             and reject the flag with 422 `not_supported`.
           x-celigo-ai-guidance:

package/dist/tool.yml

@@ -14532,6 +14532,12 @@ components:
             regardless of server OS — paths are case-sensitive on UNIX/Linux servers. Supports
             handlebars templates.
           x-celigo-ai-guidance:
+            - |-
+              A handlebars template here is rendered against the same context as `fileName`
+              (`fileMeta` is not a root key). An expression that renders empty fails the record
+              with `missing_s3_key` "Can not process upload file without
+              computedObject.fileLocation." — labeled source `internal` although the template is
+              the cause.
             - |-
               The path to the directory on the FTP server where files will be accessed,
               stored, or managed.
@@ -14588,13 +14594,28 @@ components:
           description: |-
             Name of the file written to the server, including its extension; do not include directory
             separators — the location comes from directoryPath. Supports handlebars placeholders such
-            as items-{{timestamp}}.csv to generate a unique name per run.
+            as items-{{timestamp}}.csv to generate a unique name per run. The template is rendered
+            against the incoming record: a file-transfer import from an FTP source kept the source
+            file's name with `{{record.fileMeta.fileName}}` set on `file.fileName` and this field left
+            unset — other source providers expose the name under their own `fileMeta` field.
           x-celigo-ai-guidance:
             - |-
               When the user does not specify a file naming convention,
               default to a timestamped filename such as "items-{{timestamp}}.csv" so each run
               produces a unique file and avoids overwriting previous files.
               Use a fixed filename only when the user explicitly requests overwriting or a fixed name.
+            - |-
+              `fileMeta` is not a root key of this template's context (it is one only on
+              file-provider export and lookup steps): `{{fileMeta.fileName}}` renders empty and the
+              upload fails with `missing_s3_key` "Can not process upload file without
+              computedObject.fileName." — an error the platform labels source `internal` although the
+              template is the cause. The run-time-proven way to keep the source file's name on a
+              `blob: true` import is `{{record.fileMeta.fileName}}` on `file.fileName` with this field
+              omitted (the production runs of one FTP blob import set exactly that); the same template
+              on this field has not been run. The field's editor preview (data version 1, its default)
+              exposes the record as `data` —
+              the `{blobKey, fileMeta}` record on a blob import, the page's record array otherwise —
+              so `record.` previews empty there; judge by a run.
             - |-
               The name of the file to be accessed, transferred,
               or manipulated via FTP (File Transfer Protocol).
@@ -15401,7 +15422,11 @@ components:
               field mapped to `internalid` is overridden by it. When the incoming record
               already carries the NetSuite internal ID, point the lookup at that field with
               the expression form — `["internalid","is","{{{id}}}"]` — rather than removing
-              the lookup.
+              the lookup. Only when every record carries it: on `restletVersion:
+              suiteapp2.0` a record whose field is empty does not fall through to
+              "create" on `addupdate` — the empty value is searched as `isempty` and
+              can match an existing record (see `expression`; SuiteBundle and SuiteApp
+              1.0 create in that case).
           properties:
             extract:
               type: string
@@ -15527,6 +15552,21 @@ components:
                   - DO NOT use `jsonSerialize` here — search expressions take
                     scalar literals, not serialized JSON.  Use `{{{id}}}` or
                     `{{{[Field Name]}}}` directly.
+                - |-
+                  ## A substitution that renders empty is not "no match"
+
+                  When the source field is absent or empty, `["internalid","is","{{{id}}}"]`
+                  renders `["internalid","is",""]`, and the SuiteApp rewrites an empty
+                  `is` / `equalto` / `internalid anyof` value to `isempty` before the
+                  search. On `restletVersion: suiteapp2.0` that search is not treated as
+                  "no match": it can return existing records, and `addupdate` then
+                  updates one of them — an unrelated record receives the mapping (seen
+                  in production as `cant_modify_sub` on a customer the record never
+                  named). SuiteBundle and SuiteApp 1.0 discard a blank `internalid`
+                  match and create. Design so the operational lookup never renders
+                  empty: key it on a value every record carries (the source id stored
+                  as `externalid`), or route records without a destination id to a
+                  separate `add` import.
                 - |-
                   ## Body-level only
 
@@ -19834,7 +19874,10 @@ components:
           description: |-
             **REQUIRED for file-based imports.**
 
-            The name of the file to be created/written. Supports Handlebars expressions for dynamic naming.
+            The name of the file to be created/written. Supports Handlebars expressions for dynamic naming,
+            rendered against the incoming record — a file-transfer import keeps the source file's name from
+            the record's `fileMeta`, whose field names are the exporting provider's
+            (`{{record.fileMeta.fileName}}` from an FTP source, `fileMeta.name` from Google Drive).
 
             **Default behavior**
             - When the user does not specify a file naming convention, **always default to timestamped filenames** using `{{timestamp}}` (e.g., `"items-{{timestamp}}.csv"`). This ensures each run produces a unique file and avoids overwriting previous exports.
@@ -19852,7 +19895,20 @@ components:
 
             **Important**
             - For S3 imports, this should typically match the `s3.fileKey` value
-            - For FTP imports, this should typically match the `ftp.fileName` value
+            - For FTP imports, this should typically match the `ftp.fileName` value; the one blob file-transfer run on record set only this field and left `ftp.fileName` unset
+          x-celigo-ai-guidance:
+            - |-
+              `fileMeta` is not a root key of this template's context (it is one only on
+              file-provider export and lookup steps): `{{fileMeta.fileName}}` renders empty and the
+              file has no name; on an FTP import the record then fails with `missing_s3_key` "Can not
+              process upload file without computedObject.fileName.", labeled source `internal`
+              although the template is the cause. The incoming record carries the source file's
+              metadata — on an FTP blob import `{{record.fileMeta.fileName}}` keeps the source file's
+              name at run time (the only spelling proven by a run). The field's editor preview
+              (data version 1, its default) exposes the record as `data` — the `{blobKey, fileMeta}`
+              record on a `blob: true` import, the page's record array otherwise — so `record.`
+              previews empty there; judge by a run. The metadata field names are the exporting
+              provider's — read them off the incoming sample record.
           examples:
             - customers-{{timestamp}}.json
             - orders-export.csv
@@ -24890,6 +24946,14 @@ components:
               On AiAgentImport, GuardrailImport and ToolImport the save fails with 422 `not_supported`
               ("Field "blobKeyPath" is not supported for this import type."); route file content
               through a blob-capable import (HTTP, FTP, S3) instead.
+            - |-
+              Optional on a `blob: true` file-provider import: when omitted the platform reads the
+              record's root `blobKey` — the field a blob export emits on its `{blobKey, fileMeta}`
+              record — so a file-transfer flow needs no `blobKeyPath`. Observed on an FTP import
+              (production runs writing files with no `blobKeyPath`) and on a Google Drive folder
+              upload (`http.type: file`, the marketplace file-transfer template's shape); other
+              file providers were not probed. Set it only when a response mapping placed the key
+              elsewhere; on those two providers its absence is not a cause of upload failures.
             - |-
               The value at this path must be a blobKey produced by an upstream blob
               export or blob lookup and carried onto the record via that step's
@@ -24918,7 +24982,8 @@ components:
             - ToolImport
           description: |-
             When true, this import transfers raw file content (blobs) to the destination rather than
-            structured records, reading each file through `blobKeyPath`. Not accepted on
+            structured records, reading each file through `blobKeyPath` (optional on FTP and Google
+            Drive file-provider imports, which fall back to the record's root `blobKey`). Not accepted on
             `AiAgentImport`, `GuardrailImport`, or `ToolImport` — those adaptors process records only
             and reject the flag with 422 `not_supported`.
           x-celigo-ai-guidance:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.125",
+  "version": "0.2.127",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "5aa2524f",
+		"iasCommit": "2882b3ab",
 		"generatedAt": "2026-10-20"
 	},
 	"roots": {