@celigo/api-specs 0.2.127 → 0.2.128

package/dist/import.yml

@@ -4248,6 +4248,22 @@ components:
                         existing record: on an `add`-only operation every record fails with
                         `The mapping condition:"record_updated" not supported for the
                         operation`. It works on `addupdate` and `update`.
+                      - |-
+                        The condition is one of the fixed `when` values — there is no
+                        predicate over a source field ("when `customer.id` is not empty",
+                        "when `channel.name` is Point of Sale" cannot be written here).
+                        `extract_not_empty` is the only source-driven gate: on a lookup row
+                        it reads the row's `extract`, and when that is empty the row is
+                        skipped and the field is left unset — nothing substitutes a value.
+                        Value-dependent behaviour (a fallback record when the key is
+                        missing) belongs inside the lookup's `expression` (see
+                        `lookups[].expression`).
+                      - |-
+                        Two rows with the same `generate` are not a fallback pair: the
+                        last row for a destination decides it alone — when its condition
+                        skips it the field stays empty even if an earlier row produced a
+                        value, and when it applies it overwrites the earlier row's value
+                        (`ignore_if_set` reads the target record, not an earlier row).
                     properties:
                       lookupName:
                         type: string
@@ -4503,6 +4519,18 @@ components:
                               rows in live verification. Do not rely on that tolerance — use
                               `when: record_updated` only on operations that can update
                               records (`addupdate` / `update`).
+                            - |-
+                              The condition is one of the fixed `when` values — the same
+                              closed set as body rows, with no predicate over a source
+                              field; `extract_not_empty` skips the row on the lines whose
+                              extract is empty and leaves that line's field unset. Two
+                              sublist rows with the same `generate` are not a fallback
+                              pair either, and the order rule is not the body rows': among
+                              extract rows the last row decides each line alone (a skipped
+                              last row leaves the line's field unset even when an earlier
+                              row produced a value), while a hard-coded row's value lands
+                              on every line whatever its position — a later conditional
+                              extract row does not override it.
                           properties:
                             lookupName:
                               type: string
@@ -4629,6 +4657,32 @@ components:
                     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.
+                  - |-
+                    ## An empty substitution searches `isempty`
+
+                    When the source path a criterion reads is null or absent
+                    (`["custentity_celigo_etail_cust_id","is","{{{customer.id}}}"]`
+                    on an order with no customer), the engine does not fail on
+                    the missing input: it searches the field with an `isempty`
+                    criterion, so the lookup now matches every target record
+                    whose field is BLANK. Two or more such records fail the
+                    record with `VALUE_LOOKUP_FAILED` — `More than one match
+                    for "[<field>,"isempty"]" for the record type "<recordType>"`
+                    (the message quotes the search field, never the empty
+                    source path); none fail it as `Could not find a match`;
+                    exactly one silently resolves to that record. Keep an empty
+                    key out of the search inside the expression — branch on
+                    the key: `{{#if customer.id}}[["custentity_celigo_etail_cust_id",
+                    "is","{{{customer.id}}}"]]{{else}}[["internalid","anyof",
+                    "<fallback internal id>"]]{{/if}}` routes records without a
+                    key to a fallback record while records with a key keep
+                    fail-on-miss; or render a value that can never match in the
+                    else branch and set `allowFailures: true` with `default`.
+                    A `searchField` / `operator` lookup (no `expression`) never
+                    reaches this state: an empty extract fails the record with
+                    `STATIC_MAPPING_ERROR` — `Exported value is empty/undefined
+                    for the field: $.<path>` — and resolves to `default` when
+                    `allowFailures` is true.
                   - |-
                     ## The mapping preview cannot evaluate `[*]` inside a block-helper argument
 
@@ -4662,19 +4716,34 @@ components:
               useDefaultOnMultipleMatches:
                 type: boolean
                 description: |-
-                  Controls behaviour when the search matches more than one
-                  record. When true, the `default` value is returned instead
-                  of raising an ambiguous-match error. When false (default),
-                  multiple matches are treated as a failure.
+                  When true and `allowFailures` is also true, a search that
+                  matches more than one record resolves to `default` instead
+                  of failing the record. Has no effect while `allowFailures`
+                  is false — an ambiguous match then fails the record whatever
+                  this flag says.
+                x-celigo-ai-guidance:
+                  - |-
+                    Set it together with `allowFailures: true` whenever the
+                    search value can be empty or duplicated: with
+                    `allowFailures: true` alone an ambiguous match resolves to
+                    ONE of the matching records with no error, and with this
+                    flag alone the record still fails `More than one match`.
+                    Every ambiguous match then becomes `default`, a genuinely
+                    duplicated key included — when that must still fail, keep
+                    `allowFailures` false and handle the empty key in the
+                    `expression` instead (see `expression`).
               allowFailures:
                 type:
                   - boolean
                   - 'null'
                 description: |-
                   When true, a lookup miss (no matching record and no
-                  `default`) resolves to `null` and the import continues.
-                  When false (default), a miss halts the record. May be
-                  stored as null (treated as unset).
+                  `default`) resolves to `null` and the import continues, and
+                  a search matching more than one record resolves to one of
+                  them unless `useDefaultOnMultipleMatches` routes it to
+                  `default`. When false (default), a miss and an ambiguous
+                  match both halt the record. May be stored as null (treated
+                  as unset).
               map:
                 type:
                   - object

package/dist/tool.yml

@@ -15829,6 +15829,22 @@ components:
                         existing record: on an `add`-only operation every record fails with
                         `The mapping condition:"record_updated" not supported for the
                         operation`. It works on `addupdate` and `update`.
+                      - |-
+                        The condition is one of the fixed `when` values — there is no
+                        predicate over a source field ("when `customer.id` is not empty",
+                        "when `channel.name` is Point of Sale" cannot be written here).
+                        `extract_not_empty` is the only source-driven gate: on a lookup row
+                        it reads the row's `extract`, and when that is empty the row is
+                        skipped and the field is left unset — nothing substitutes a value.
+                        Value-dependent behaviour (a fallback record when the key is
+                        missing) belongs inside the lookup's `expression` (see
+                        `lookups[].expression`).
+                      - |-
+                        Two rows with the same `generate` are not a fallback pair: the
+                        last row for a destination decides it alone — when its condition
+                        skips it the field stays empty even if an earlier row produced a
+                        value, and when it applies it overwrites the earlier row's value
+                        (`ignore_if_set` reads the target record, not an earlier row).
                     properties:
                       lookupName:
                         type: string
@@ -16084,6 +16100,18 @@ components:
                               rows in live verification. Do not rely on that tolerance — use
                               `when: record_updated` only on operations that can update
                               records (`addupdate` / `update`).
+                            - |-
+                              The condition is one of the fixed `when` values — the same
+                              closed set as body rows, with no predicate over a source
+                              field; `extract_not_empty` skips the row on the lines whose
+                              extract is empty and leaves that line's field unset. Two
+                              sublist rows with the same `generate` are not a fallback
+                              pair either, and the order rule is not the body rows': among
+                              extract rows the last row decides each line alone (a skipped
+                              last row leaves the line's field unset even when an earlier
+                              row produced a value), while a hard-coded row's value lands
+                              on every line whatever its position — a later conditional
+                              extract row does not override it.
                           properties:
                             lookupName:
                               type: string
@@ -16210,6 +16238,32 @@ components:
                     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.
+                  - |-
+                    ## An empty substitution searches `isempty`
+
+                    When the source path a criterion reads is null or absent
+                    (`["custentity_celigo_etail_cust_id","is","{{{customer.id}}}"]`
+                    on an order with no customer), the engine does not fail on
+                    the missing input: it searches the field with an `isempty`
+                    criterion, so the lookup now matches every target record
+                    whose field is BLANK. Two or more such records fail the
+                    record with `VALUE_LOOKUP_FAILED` — `More than one match
+                    for "[<field>,"isempty"]" for the record type "<recordType>"`
+                    (the message quotes the search field, never the empty
+                    source path); none fail it as `Could not find a match`;
+                    exactly one silently resolves to that record. Keep an empty
+                    key out of the search inside the expression — branch on
+                    the key: `{{#if customer.id}}[["custentity_celigo_etail_cust_id",
+                    "is","{{{customer.id}}}"]]{{else}}[["internalid","anyof",
+                    "<fallback internal id>"]]{{/if}}` routes records without a
+                    key to a fallback record while records with a key keep
+                    fail-on-miss; or render a value that can never match in the
+                    else branch and set `allowFailures: true` with `default`.
+                    A `searchField` / `operator` lookup (no `expression`) never
+                    reaches this state: an empty extract fails the record with
+                    `STATIC_MAPPING_ERROR` — `Exported value is empty/undefined
+                    for the field: $.<path>` — and resolves to `default` when
+                    `allowFailures` is true.
                   - |-
                     ## The mapping preview cannot evaluate `[*]` inside a block-helper argument
 
@@ -16243,19 +16297,34 @@ components:
               useDefaultOnMultipleMatches:
                 type: boolean
                 description: |-
-                  Controls behaviour when the search matches more than one
-                  record. When true, the `default` value is returned instead
-                  of raising an ambiguous-match error. When false (default),
-                  multiple matches are treated as a failure.
+                  When true and `allowFailures` is also true, a search that
+                  matches more than one record resolves to `default` instead
+                  of failing the record. Has no effect while `allowFailures`
+                  is false — an ambiguous match then fails the record whatever
+                  this flag says.
+                x-celigo-ai-guidance:
+                  - |-
+                    Set it together with `allowFailures: true` whenever the
+                    search value can be empty or duplicated: with
+                    `allowFailures: true` alone an ambiguous match resolves to
+                    ONE of the matching records with no error, and with this
+                    flag alone the record still fails `More than one match`.
+                    Every ambiguous match then becomes `default`, a genuinely
+                    duplicated key included — when that must still fail, keep
+                    `allowFailures` false and handle the empty key in the
+                    `expression` instead (see `expression`).
               allowFailures:
                 type:
                   - boolean
                   - 'null'
                 description: |-
                   When true, a lookup miss (no matching record and no
-                  `default`) resolves to `null` and the import continues.
-                  When false (default), a miss halts the record. May be
-                  stored as null (treated as unset).
+                  `default`) resolves to `null` and the import continues, and
+                  a search matching more than one record resolves to one of
+                  them unless `useDefaultOnMultipleMatches` routes it to
+                  `default`. When false (default), a miss and an ambiguous
+                  match both halt the record. May be stored as null (treated
+                  as unset).
               map:
                 type:
                   - object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.127",
+  "version": "0.2.128",
   "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": "2882b3ab",
+		"iasCommit": "4974f60c",
 		"generatedAt": "2026-10-20"
 	},
 	"roots": {