@celigo/api-specs 0.2.110 → 0.2.112

package/dist/export.yml

@@ -7891,8 +7891,8 @@ components:
               - Requires the "soql" object with query configuration
 
           2. **Real-time Event Listeners** (type="distributed")
-              - Responds to Salesforce events as they happen
-              - Uses Salesforce's streaming API and platform events
+              - Responds to Salesforce record creates, updates, and deletes as they happen
+              - Fires through an Apex trigger on the object in the connected org (see `distributed`)
               - Always appears as a "Listener" in the flow builder UI
               - Requires the "distributed" object with event configuration
 
@@ -7957,7 +7957,7 @@ components:
               - **Use Cases**: Real-time synchronization, event-driven integration
               - **Dependencies**:
                 - Only uses REST API (api field is ignored)
-                - Automatically configured with trigger logic in Salesforce
+                - Depends on an Apex trigger on the object in the connected org: Integration Apps create it at installation; for a custom flow the customer deploys it from the export page's Required trigger code (see `distributed`)
                 - Only compatible with standard export type (ignores delta/test/once)
             - |-
               ## IMPLEMENTATION CONSIDERATIONS
@@ -8421,34 +8421,21 @@ components:
                 - SELECT Id, Name, (SELECT Id, FirstName, LastName FROM Contacts) FROM Account
         distributed:
           type: object
-          description: Real-time event listener configuration; required when `type` is `distributed` and not used otherwise. The system installs triggers in the connected Salesforce org and delivers records to the flow as create, update, and delete events occur — no scheduling or manual execution is involved.
+          description: Real-time listener configuration; required when `type` is `distributed` and not used otherwise. Records reach the flow only when an Apex trigger on `sObjectType` in the connected org calls the Celigo package (`integrator_da__.RealTimeExporter.processExport()`) — no scheduling or manual execution is involved. Integration Apps create their triggers at installation; for a custom flow the customer deploys the trigger in Salesforce, starting from the code the export page shows under Required trigger.
           x-celigo-ai-guidance:
-            - Configuration for real-time Salesforce event-driven exports.
             - |-
-              ## FIELD BEHAVIOR
-
-              This object defines real-time event listener settings:
-
-              - REQUIRED when type="distributed"
-              - Not used when type="soql" or for blob exports
-              - Creates push-based integration triggered by Salesforce events
-              - Implements real-time processing of creates, updates, and deletes
-            - |-
-              ## IMPLEMENTATION CONTEXT
-
-              Distributed exports work fundamentally differently from SOQL exports:
-              - No scheduling or manual execution required
-              - Triggered automatically when records change in Salesforce
-              - Data flows in real-time as events occur
-              - Uses Salesforce's platform events and streaming API
-            - |-
-              ## TECHNICAL ARCHITECTURE
-
-              When configured, the system:
-              1. Creates custom triggers in the connected Salesforce org
-              2. Establishes event listeners for the specified objects
-              3. Processes events as they occur (create/update/delete operations)
-              4. Delivers the changed records to the integration flow
+              After creating a listener on a custom flow, relay what the Help Center's "Listen for real-time data
+              from Salesforce" states: an Apex trigger is required per sObject type and, for a custom flow, the
+              customer creates it in Salesforce — copy the export page's Required trigger code, replace `<name>`,
+              and save it under Setup → Object Manager → <object> → Triggers → New; deploying to production also
+              needs a test class with 75% coverage. Integration Apps create their triggers at installation.
+            - |-
+              When a listener on an enabled flow never creates a job for a create, update, or delete, the
+              Celigo-side causes are `distributed.disabled` true, an offline connection, and a qualifier the
+              record does not satisfy — and any qualifier drops delete events (see `qualifier`). Also verify the
+              Help Center's trigger requirement in the connected org: an active Apex trigger on the object whose
+              code calls `integrator_da__.RealTimeExporter`, and the Celigo package reachable through the
+              connection (`GET /v1/connections/{_id}/distributed`, documented in this spec set).
           properties:
             referencedFields:
               type:

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:
@@ -31996,8 +32079,8 @@ components:
               - Requires the "soql" object with query configuration
 
           2. **Real-time Event Listeners** (type="distributed")
-              - Responds to Salesforce events as they happen
-              - Uses Salesforce's streaming API and platform events
+              - Responds to Salesforce record creates, updates, and deletes as they happen
+              - Fires through an Apex trigger on the object in the connected org (see `distributed`)
               - Always appears as a "Listener" in the flow builder UI
               - Requires the "distributed" object with event configuration
 
@@ -32062,7 +32145,7 @@ components:
               - **Use Cases**: Real-time synchronization, event-driven integration
               - **Dependencies**:
                 - Only uses REST API (api field is ignored)
-                - Automatically configured with trigger logic in Salesforce
+                - Depends on an Apex trigger on the object in the connected org: Integration Apps create it at installation; for a custom flow the customer deploys it from the export page's Required trigger code (see `distributed`)
                 - Only compatible with standard export type (ignores delta/test/once)
             - |-
               ## IMPLEMENTATION CONSIDERATIONS
@@ -32526,34 +32609,21 @@ components:
                 - SELECT Id, Name, (SELECT Id, FirstName, LastName FROM Contacts) FROM Account
         distributed:
           type: object
-          description: Real-time event listener configuration; required when `type` is `distributed` and not used otherwise. The system installs triggers in the connected Salesforce org and delivers records to the flow as create, update, and delete events occur — no scheduling or manual execution is involved.
+          description: Real-time listener configuration; required when `type` is `distributed` and not used otherwise. Records reach the flow only when an Apex trigger on `sObjectType` in the connected org calls the Celigo package (`integrator_da__.RealTimeExporter.processExport()`) — no scheduling or manual execution is involved. Integration Apps create their triggers at installation; for a custom flow the customer deploys the trigger in Salesforce, starting from the code the export page shows under Required trigger.
           x-celigo-ai-guidance:
-            - Configuration for real-time Salesforce event-driven exports.
             - |-
-              ## FIELD BEHAVIOR
-
-              This object defines real-time event listener settings:
-
-              - REQUIRED when type="distributed"
-              - Not used when type="soql" or for blob exports
-              - Creates push-based integration triggered by Salesforce events
-              - Implements real-time processing of creates, updates, and deletes
+              After creating a listener on a custom flow, relay what the Help Center's "Listen for real-time data
+              from Salesforce" states: an Apex trigger is required per sObject type and, for a custom flow, the
+              customer creates it in Salesforce — copy the export page's Required trigger code, replace `<name>`,
+              and save it under Setup → Object Manager → <object> → Triggers → New; deploying to production also
+              needs a test class with 75% coverage. Integration Apps create their triggers at installation.
             - |-
-              ## IMPLEMENTATION CONTEXT
-
-              Distributed exports work fundamentally differently from SOQL exports:
-              - No scheduling or manual execution required
-              - Triggered automatically when records change in Salesforce
-              - Data flows in real-time as events occur
-              - Uses Salesforce's platform events and streaming API
-            - |-
-              ## TECHNICAL ARCHITECTURE
-
-              When configured, the system:
-              1. Creates custom triggers in the connected Salesforce org
-              2. Establishes event listeners for the specified objects
-              3. Processes events as they occur (create/update/delete operations)
-              4. Delivers the changed records to the integration flow
+              When a listener on an enabled flow never creates a job for a create, update, or delete, the
+              Celigo-side causes are `distributed.disabled` true, an offline connection, and a qualifier the
+              record does not satisfy — and any qualifier drops delete events (see `qualifier`). Also verify the
+              Help Center's trigger requirement in the connected org: an active Apex trigger on the object whose
+              code calls `integrator_da__.RealTimeExporter`, and the Celigo package reachable through the
+              connection (`GET /v1/connections/{_id}/distributed`, documented in this spec set).
           properties:
             referencedFields:
               type:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.110",
+  "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": "155f6181",
-		"generatedAt": "2026-10-14"
+		"iasCommit": "290f7bc1",
+		"generatedAt": "2026-10-15"
 	},
 	"roots": {
 		"aiagent": 133,