@celigo/api-specs 0.2.111 → 0.2.112

package/dist/import.yml

@@ -3943,6 +3943,15 @@ components:
                   - DO NOT use `jsonSerialize` here — search expressions take
                     scalar literals, not serialized JSON.  Use `{{{id}}}` or
                     `{{{[Field Name]}}}` directly.
+                - |-
+                  ## Body-level only
+
+                  This lookup identifies the record being imported, so bare
+                  body fields are the right paths here. A per-field lookup
+                  attached to a sublist row (`lookups[]` referenced from
+                  `mapping.lists[].fields[].lookupName`) is different: its
+                  expression addresses the current line with
+                  `<array>[*].<field>` — see `lookups[].expression`.
         hooks:
           type: object
           description: |
@@ -4288,6 +4297,13 @@ components:
                               scalar extracts tag along.
                               If no child uses `[*]` and none set `extract` at all (every child is a `hardCodedValue`),
                               the sublist renders a single static line.
+                            - |-
+                              A row that resolves its value through `lookupName`
+                              (typically `extract: ""`) is driven by the sibling
+                              rows' `[*]` extracts, and the lookup's `expression`
+                              addresses the current line with the same
+                              `<array>[*].<field>` path — see
+                              `netsuite_da.lookups[].expression`.
                         generate:
                           type: string
                           description: NetSuite sublist field ID to write to.
@@ -4524,10 +4540,69 @@ components:
                   - internalid
               expression:
                 type: string
+                x-celigo-agent:
+                  - handlebars
                 description: |-
                   Optional advanced-search expression (NetSuite saved-search
                   DSL) for multi-criterion lookups. When present, supersedes
                   `searchField` / `operator` — those fields are ignored.
+                  Handlebars inside the expression is rendered against the
+                  whole source record before the search runs; a lookup on a
+                  sublist row reaches the current line through
+                  `<array>[*].<field>` (for example `line_items[*].sku`).
+                x-celigo-ai-guidance:
+                  - |-
+                    ## Evaluation context — the whole source record, no `record.` prefix
+
+                    The expression's Handlebars renders against the incoming
+                    source record as the context root (the record is NOT
+                    wrapped under `record`), then the rendered JSON array is
+                    sent to NetSuite as the search criteria. Body-level fields
+                    are addressed bare: `{{{id}}}`, `{{{email}}}`.
+                  - |-
+                    ## Sublist-row lookups address the line with `<array>[*].<field>`
+
+                    A lookup referenced from a sublist mapping row
+                    (`mapping.lists[].fields[].lookupName`) still receives the
+                    whole record; the current line's fields are reached with the
+                    same bracket-star path the sublist extracts use —
+                    `{{{line_items[*].sku}}}` resolves the line's item (one line
+                    per sublist row). A bare line field (`{{sku}}`,
+                    `{{#contains sku "_"}}`) is undefined at the record root: a
+                    helper that receives it fails every record with
+                    `INVALID_HANDLE_BAR_EXPRESSION` — `Could not compile handle
+                    bar "<expression>" because "Cannot call method "indexOf" of
+                    undefined"` — before anything reaches NetSuite. When an
+                    audit diff shows `<array>[*].` removed from the expression
+                    right before such errors began, that edit is the cause; do
+                    not look for a line missing the field.
+                  - |-
+                    ## Rendered unmatched
+
+                    A rendered value NetSuite does not match fails the record
+                    with `VALUE_LOOKUP_FAILED` — `Could not find a match for
+                    "<rendered criteria>" for the record type "<recordType>"`
+                    — quoting the criteria exactly as rendered, so the message
+                    shows what the expression produced for that line. With
+                    `allowFailures: true` the `default` value is used instead
+                    and no error is raised. Give every branch an output.
+                  - |-
+                    ## The mapping preview cannot evaluate `[*]` inside a block-helper argument
+
+                    `PUT /v1/netsuiteDA/previewImportMappingFields` (the mapping
+                    editor's Preview) evaluates lookups for real — resolved
+                    internal ids appear in `nlobjSublistIds`, misses and
+                    compile errors in `data.mappingErrors[]` — and handles
+                    `[*]` in plain substitutions and inside a branch's output.
+                    It does NOT apply the per-line evaluation to `[*]` used as a
+                    block-helper ARGUMENT (`{{#if line_items[*].x}}`,
+                    `{{#contains line_items[*].sku "_"}}`): the sublist comes
+                    back EMPTY with no error, whatever the expression would do
+                    in a run. An empty preview is therefore no evidence about
+                    such an expression — never report it as "renders nothing"
+                    or as invalid on that basis; validate it with a run.
+                    `<array>.@index.<field>` is likewise not evaluable in the
+                    preview (the record is dropped with no error).
               operator:
                 type: string
                 description: |-
@@ -4585,6 +4660,14 @@ components:
               TWO locations: `netsuite_da.lookups` and top-level `lookups`.
               Both arrays must hold byte-for-byte identical content — the
               MappingsAgent writes both on every save.
+            - |-
+              ## One context for body and sublist lookups
+              Every lookup's `expression` renders against the whole source
+              record. A lookup referenced from a sublist row
+              (`mapping.lists[].fields[].lookupName`) is evaluated once per
+              line and addresses the current line with `<array>[*].<field>`
+              — never a bare line field. See `expression` for the failure
+              modes and the preview caveat.
           x-celigo-agent:
             - lookup
         rawOverride:

package/dist/tool.yml

@@ -15522,6 +15522,15 @@ components:
                   - DO NOT use `jsonSerialize` here — search expressions take
                     scalar literals, not serialized JSON.  Use `{{{id}}}` or
                     `{{{[Field Name]}}}` directly.
+                - |-
+                  ## Body-level only
+
+                  This lookup identifies the record being imported, so bare
+                  body fields are the right paths here. A per-field lookup
+                  attached to a sublist row (`lookups[]` referenced from
+                  `mapping.lists[].fields[].lookupName`) is different: its
+                  expression addresses the current line with
+                  `<array>[*].<field>` — see `lookups[].expression`.
         hooks:
           type: object
           description: |
@@ -15867,6 +15876,13 @@ components:
                               scalar extracts tag along.
                               If no child uses `[*]` and none set `extract` at all (every child is a `hardCodedValue`),
                               the sublist renders a single static line.
+                            - |-
+                              A row that resolves its value through `lookupName`
+                              (typically `extract: ""`) is driven by the sibling
+                              rows' `[*]` extracts, and the lookup's `expression`
+                              addresses the current line with the same
+                              `<array>[*].<field>` path — see
+                              `netsuite_da.lookups[].expression`.
                         generate:
                           type: string
                           description: NetSuite sublist field ID to write to.
@@ -16103,10 +16119,69 @@ components:
                   - internalid
               expression:
                 type: string
+                x-celigo-agent:
+                  - handlebars
                 description: |-
                   Optional advanced-search expression (NetSuite saved-search
                   DSL) for multi-criterion lookups. When present, supersedes
                   `searchField` / `operator` — those fields are ignored.
+                  Handlebars inside the expression is rendered against the
+                  whole source record before the search runs; a lookup on a
+                  sublist row reaches the current line through
+                  `<array>[*].<field>` (for example `line_items[*].sku`).
+                x-celigo-ai-guidance:
+                  - |-
+                    ## Evaluation context — the whole source record, no `record.` prefix
+
+                    The expression's Handlebars renders against the incoming
+                    source record as the context root (the record is NOT
+                    wrapped under `record`), then the rendered JSON array is
+                    sent to NetSuite as the search criteria. Body-level fields
+                    are addressed bare: `{{{id}}}`, `{{{email}}}`.
+                  - |-
+                    ## Sublist-row lookups address the line with `<array>[*].<field>`
+
+                    A lookup referenced from a sublist mapping row
+                    (`mapping.lists[].fields[].lookupName`) still receives the
+                    whole record; the current line's fields are reached with the
+                    same bracket-star path the sublist extracts use —
+                    `{{{line_items[*].sku}}}` resolves the line's item (one line
+                    per sublist row). A bare line field (`{{sku}}`,
+                    `{{#contains sku "_"}}`) is undefined at the record root: a
+                    helper that receives it fails every record with
+                    `INVALID_HANDLE_BAR_EXPRESSION` — `Could not compile handle
+                    bar "<expression>" because "Cannot call method "indexOf" of
+                    undefined"` — before anything reaches NetSuite. When an
+                    audit diff shows `<array>[*].` removed from the expression
+                    right before such errors began, that edit is the cause; do
+                    not look for a line missing the field.
+                  - |-
+                    ## Rendered unmatched
+
+                    A rendered value NetSuite does not match fails the record
+                    with `VALUE_LOOKUP_FAILED` — `Could not find a match for
+                    "<rendered criteria>" for the record type "<recordType>"`
+                    — quoting the criteria exactly as rendered, so the message
+                    shows what the expression produced for that line. With
+                    `allowFailures: true` the `default` value is used instead
+                    and no error is raised. Give every branch an output.
+                  - |-
+                    ## The mapping preview cannot evaluate `[*]` inside a block-helper argument
+
+                    `PUT /v1/netsuiteDA/previewImportMappingFields` (the mapping
+                    editor's Preview) evaluates lookups for real — resolved
+                    internal ids appear in `nlobjSublistIds`, misses and
+                    compile errors in `data.mappingErrors[]` — and handles
+                    `[*]` in plain substitutions and inside a branch's output.
+                    It does NOT apply the per-line evaluation to `[*]` used as a
+                    block-helper ARGUMENT (`{{#if line_items[*].x}}`,
+                    `{{#contains line_items[*].sku "_"}}`): the sublist comes
+                    back EMPTY with no error, whatever the expression would do
+                    in a run. An empty preview is therefore no evidence about
+                    such an expression — never report it as "renders nothing"
+                    or as invalid on that basis; validate it with a run.
+                    `<array>.@index.<field>` is likewise not evaluable in the
+                    preview (the record is dropped with no error).
               operator:
                 type: string
                 description: |-
@@ -16164,6 +16239,14 @@ components:
               TWO locations: `netsuite_da.lookups` and top-level `lookups`.
               Both arrays must hold byte-for-byte identical content — the
               MappingsAgent writes both on every save.
+            - |-
+              ## One context for body and sublist lookups
+              Every lookup's `expression` renders against the whole source
+              record. A lookup referenced from a sublist row
+              (`mapping.lists[].fields[].lookupName`) is evaluated once per
+              line and addresses the current line with `<array>[*].<field>`
+              — never a bare line field. See `expression` for the failure
+              modes and the preview caveat.
           x-celigo-agent:
             - lookup
         rawOverride:

package/package.json

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

package/schemas.json

@@ -1,8 +1,8 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "5353c280",
-		"generatedAt": "2026-10-14"
+		"iasCommit": "290f7bc1",
+		"generatedAt": "2026-10-15"
 	},
 	"roots": {
 		"aiagent": 133,