@celigo/api-specs 0.2.111 → 0.2.113

package/dist/import.yml

@@ -3802,23 +3802,25 @@ components:
             - |-
               Two ways to specify the lookup, picked per import:
 
+              - **Expression form** — the default choice: set `expression` to a
+                NetSuite search-expression literal (the canonical patterns are on
+                the `expression` field — `["internalid","is","{{{id}}}"]` for a
+                record that carries the internal id, `externalid` and `cust*_*`
+                variants, `anyof` for multi-match, AND/OR compounds).  When
+                `expression` is set, `searchField` / `operator` / `extract` are
+                ignored.
               - **Simple form** — set `searchField` + `operator` (+ optional
-                `extract`).  Use for single-criterion lookups against a built-in
-                NetSuite field.  The platform builds the equivalent search
-                expression for you at runtime.
-              - **Expression form** — set `expression` to a NetSuite search-
-                expression literal.  Use for compound (AND/OR) lookups, custom-
-                record-field lookups (`custbody_*` / `custrecord_*` /
-                `custentity_*`), and the `anyof` operator that the simple form
-                doesn't cover.  When `expression` is set, `searchField` /
-                `operator` / `extract` are ignored.  The expression form is the
-                common pattern in practice.
+                `extract`) for a single-criterion lookup against a built-in
+                NetSuite field; the platform builds the equivalent search
+                expression at runtime.  For the internal id itself the expression
+                form above is the preferred path, and `anyof` is available only
+                through `expression`.
             - |-
               The lookup result is what identifies the target record; on `update` a source
               field mapped to `internalid` is overridden by it. When the incoming record
-              already carries the NetSuite internal ID, point the lookup at that field
-              (simple form with `extract`, or an expression on the id field) rather than
-              removing the lookup.
+              already carries the NetSuite internal ID, point the lookup at that field with
+              the expression form — `["internalid","is","{{{id}}}"]` — rather than removing
+              the lookup.
           properties:
             extract:
               type: string
@@ -3827,7 +3829,7 @@ components:
                 - |-
                   Path on the incoming source record (NOT the post-mapped record) whose value drives the lookup.
                   Used with the simple form (`searchField` + `operator`).
-                  Common values: `"internalId"`, `"externalId"`, `"id"`.
+                  Common values: `"externalId"`, `"id"`.
                   Ignored when `expression` is set.
               examples:
                 - externalId
@@ -3837,8 +3839,9 @@ components:
               x-celigo-ai-guidance:
                 - |-
                   NetSuite field the simple-form lookup queries against.
-                  Common values: `"externalId"`, `"internalId"`, `"email"`, `"tranId"`,
-                  `"name"`.
+                  Common values: `"externalId"`, `"email"`, `"tranId"`, `"name"`.
+                  Matching on the record's internal id is the expression form —
+                  `["internalid","is","{{{id}}}"]` — not a `searchField`.
                   Ignored when `expression` is set.
               examples:
                 - externalId
@@ -3848,9 +3851,9 @@ components:
               x-celigo-ai-guidance:
                 - |-
                   Comparison operator for the simple-form lookup.
-                  Common values: `"is"` (exact match),
-                  `"anyof"` (matches any of the given internal-id values), `"contains"`,
-                  `"startswith"`, `"equalto"`.
+                  Common values: `"is"` (exact match), `"contains"`, `"startswith"`,
+                  `"equalto"`.  Multi-match (`anyof`) is available only through
+                  `expression` (`["internalid","anyof","{{{id}}}"]`).
                   Ignored when `expression` is set.
             expression:
               type: string
@@ -3943,6 +3946,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 +4300,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 +4543,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 +4663,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

@@ -15381,23 +15381,25 @@ components:
             - |-
               Two ways to specify the lookup, picked per import:
 
+              - **Expression form** — the default choice: set `expression` to a
+                NetSuite search-expression literal (the canonical patterns are on
+                the `expression` field — `["internalid","is","{{{id}}}"]` for a
+                record that carries the internal id, `externalid` and `cust*_*`
+                variants, `anyof` for multi-match, AND/OR compounds).  When
+                `expression` is set, `searchField` / `operator` / `extract` are
+                ignored.
               - **Simple form** — set `searchField` + `operator` (+ optional
-                `extract`).  Use for single-criterion lookups against a built-in
-                NetSuite field.  The platform builds the equivalent search
-                expression for you at runtime.
-              - **Expression form** — set `expression` to a NetSuite search-
-                expression literal.  Use for compound (AND/OR) lookups, custom-
-                record-field lookups (`custbody_*` / `custrecord_*` /
-                `custentity_*`), and the `anyof` operator that the simple form
-                doesn't cover.  When `expression` is set, `searchField` /
-                `operator` / `extract` are ignored.  The expression form is the
-                common pattern in practice.
+                `extract`) for a single-criterion lookup against a built-in
+                NetSuite field; the platform builds the equivalent search
+                expression at runtime.  For the internal id itself the expression
+                form above is the preferred path, and `anyof` is available only
+                through `expression`.
             - |-
               The lookup result is what identifies the target record; on `update` a source
               field mapped to `internalid` is overridden by it. When the incoming record
-              already carries the NetSuite internal ID, point the lookup at that field
-              (simple form with `extract`, or an expression on the id field) rather than
-              removing the lookup.
+              already carries the NetSuite internal ID, point the lookup at that field with
+              the expression form — `["internalid","is","{{{id}}}"]` — rather than removing
+              the lookup.
           properties:
             extract:
               type: string
@@ -15406,7 +15408,7 @@ components:
                 - |-
                   Path on the incoming source record (NOT the post-mapped record) whose value drives the lookup.
                   Used with the simple form (`searchField` + `operator`).
-                  Common values: `"internalId"`, `"externalId"`, `"id"`.
+                  Common values: `"externalId"`, `"id"`.
                   Ignored when `expression` is set.
               examples:
                 - externalId
@@ -15416,8 +15418,9 @@ components:
               x-celigo-ai-guidance:
                 - |-
                   NetSuite field the simple-form lookup queries against.
-                  Common values: `"externalId"`, `"internalId"`, `"email"`, `"tranId"`,
-                  `"name"`.
+                  Common values: `"externalId"`, `"email"`, `"tranId"`, `"name"`.
+                  Matching on the record's internal id is the expression form —
+                  `["internalid","is","{{{id}}}"]` — not a `searchField`.
                   Ignored when `expression` is set.
               examples:
                 - externalId
@@ -15427,9 +15430,9 @@ components:
               x-celigo-ai-guidance:
                 - |-
                   Comparison operator for the simple-form lookup.
-                  Common values: `"is"` (exact match),
-                  `"anyof"` (matches any of the given internal-id values), `"contains"`,
-                  `"startswith"`, `"equalto"`.
+                  Common values: `"is"` (exact match), `"contains"`, `"startswith"`,
+                  `"equalto"`.  Multi-match (`anyof`) is available only through
+                  `expression` (`["internalid","anyof","{{{id}}}"]`).
                   Ignored when `expression` is set.
             expression:
               type: string
@@ -15522,6 +15525,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 +15879,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 +16122,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 +16242,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.113",
   "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": "af39c6bc",
+		"generatedAt": "2026-10-15"
 	},
 	"roots": {
 		"aiagent": 133,