@celigo/api-specs 0.2.138 → 0.2.140

package/dist/ai-agent.yml

@@ -2351,14 +2351,15 @@ components:
             - `objectarray`: Array of objects (most common array type)
             - `arrayarray`: Array of arrays (for matrix/table structures)
 
-            Array dataTypes can be populated two ways: pass a source array through
-            unchanged via `extract` alone (when the source is already an array of
-            the right shape), or construct/iterate via `buildArrayHelper`.
+            Array dataTypes can be populated three ways: pass a source array
+            through unchanged via a JSONPath `extract` alone (when the source is
+            already an array of the right shape), construct/iterate via
+            `buildArrayHelper`, or set a constant with `hardCodedValue`.
 
             IMPORTANT: The dataType controls which additional fields are relevant:
             - For date-like string fields: extractDateFormat, generateDateFormat, etc. become relevant
             - For object types: 'mappings' array becomes relevant
-            - For array types: `buildArrayHelper` is one option (see above)
+            - For array types: a JSONPath `extract` alone, `buildArrayHelper`, or `hardCodedValue` (see above)
 
             When analyzing existing mappings or generating new ones, always check dataType first
             to understand what additional fields should be present.
@@ -2421,9 +2422,12 @@ components:
             - Access input record fields with {{record.fieldName}} notation; a grouped
               (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
             - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
-            - Valid on `object`, `objectarray`, and primitive-array dataTypes as
-              well as scalars — the rendered template output must parse into the
-              declared shape
+            - Valid on scalars and on `object` rows, where the rendered output must
+              parse into an object. On an array row the template goes in a
+              `buildArrayHelper` entry instead: on an `objectarray` row's own
+              `extract` it is refused with 422 ("buildArrayHelper" must be present
+              for object array datatype), and on a primitive-array row's own
+              `extract` it renders null without an error
 
             ```json
             "extract": "{{record.price}} {{record.currency}}"  // Combines two fields
@@ -2622,6 +2626,19 @@ components:
             - countryCodeToName
             - statusMapping
             - departmentCodes
+        hardCodedValue:
+          type: string
+          description: |
+            Constant written to the destination instead of an extracted value. On a primitive
+            array (`stringarray`, `numberarray`, `booleanarray`) the string is split on commas,
+            verbatim and untrimmed, into elements of the array's type (`"A,B"` gives `["A", "B"]`).
+            On an `object` it must be a JSON object string and on an `objectarray` a JSON array
+            string (an object string becomes one element); the save parses it and refuses non-JSON
+            or the wrong shape with 422, and an array row with a constant needs no `buildArrayHelper`.
+          examples:
+            - USD
+            - A,B
+            - '[{"code": "A"}, {"code": "B"}]'
         description:
           type: string
           description: |
@@ -2757,15 +2774,25 @@ components:
               processor renders the entire destination array as null with no
               validation error. To emit a fixed number of static elements, add
               that many sibling constructed entries — never index the extract.
+            - |-
+              An entry's `extract` can be a Handlebars template. On an
+              `objectarray` it must render a JSON object (one element) or a JSON
+              array (one element per item). On a primitive array each entry
+              renders one element, so a serialized array becomes one string
+              element. A bare literal entry extract is refused with 422 ("extract
+              only supports json path or handlebars expression"); set a constant
+              with the row's `hardCodedValue` instead.
           description: |
             **Purpose**
             Configures how to construct arrays in the output record, handling various array types and inputs.
 
             **Guidance**
-            This is the REQUIRED mechanism for ALL array data types:
+            This is the mechanism for building array data types:
 
             **When to Use**
-            - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.)
+            - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
+              row passes a source array through with a JSONPath `extract` alone or sets
+              `hardCodedValue`
             - Each entry in this array contributes elements to the output array
             - Multiple entries allow combining data from different input arrays
 
@@ -3390,14 +3417,15 @@ components:
               - `objectarray`: Array of objects (most common array type)
               - `arrayarray`: Array of arrays (for matrix/table structures)
 
-              Array dataTypes can be populated two ways: pass a source array through
-              unchanged via `extract` alone (when the source is already an array of
-              the right shape), or construct/iterate via `buildArrayHelper`.
+              Array dataTypes can be populated three ways: pass a source array
+              through unchanged via a JSONPath `extract` alone (when the source is
+              already an array of the right shape), construct/iterate via
+              `buildArrayHelper`, or set a constant with `hardCodedValue`.
 
               IMPORTANT: The dataType controls which additional fields are relevant:
               - For date-like string fields: extractDateFormat, generateDateFormat, etc. become relevant
               - For object types: 'mappings' array becomes relevant
-              - For array types: `buildArrayHelper` is one option (see above)
+              - For array types: a JSONPath `extract` alone, `buildArrayHelper`, or `hardCodedValue` (see above)
 
               When analyzing existing mappings or generating new ones, always check dataType first
               to understand what additional fields should be present.
@@ -3460,9 +3488,12 @@ components:
               - Access input record fields with {{record.fieldName}} notation; a grouped
                 (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
               - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
-              - Valid on `object`, `objectarray`, and primitive-array dataTypes as
-                well as scalars — the rendered template output must parse into the
-                declared shape
+              - Valid on scalars and on `object` rows, where the rendered output must
+                parse into an object. On an array row the template goes in a
+                `buildArrayHelper` entry instead: on an `objectarray` row's own
+                `extract` it is refused with 422 ("buildArrayHelper" must be present
+                for object array datatype), and on a primitive-array row's own
+                `extract` it renders null without an error
 
               ```json
               "extract": "{{record.price}} {{record.currency}}"  // Combines two fields
@@ -3661,6 +3692,19 @@ components:
               - countryCodeToName
               - statusMapping
               - departmentCodes
+          hardCodedValue:
+            type: string
+            description: |
+              Constant written to the destination instead of an extracted value. On a primitive
+              array (`stringarray`, `numberarray`, `booleanarray`) the string is split on commas,
+              verbatim and untrimmed, into elements of the array's type (`"A,B"` gives `["A", "B"]`).
+              On an `object` it must be a JSON object string and on an `objectarray` a JSON array
+              string (an object string becomes one element); the save parses it and refuses non-JSON
+              or the wrong shape with 422, and an array row with a constant needs no `buildArrayHelper`.
+            examples:
+              - USD
+              - A,B
+              - '[{"code": "A"}, {"code": "B"}]'
           description:
             type: string
             description: |
@@ -3796,15 +3840,25 @@ components:
                 processor renders the entire destination array as null with no
                 validation error. To emit a fixed number of static elements, add
                 that many sibling constructed entries — never index the extract.
+              - |-
+                An entry's `extract` can be a Handlebars template. On an
+                `objectarray` it must render a JSON object (one element) or a JSON
+                array (one element per item). On a primitive array each entry
+                renders one element, so a serialized array becomes one string
+                element. A bare literal entry extract is refused with 422 ("extract
+                only supports json path or handlebars expression"); set a constant
+                with the row's `hardCodedValue` instead.
             description: |
               **Purpose**
               Configures how to construct arrays in the output record, handling various array types and inputs.
 
               **Guidance**
-              This is the REQUIRED mechanism for ALL array data types:
+              This is the mechanism for building array data types:
 
               **When to Use**
-              - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.)
+              - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
+                row passes a source array through with a JSONPath `extract` alone or sets
+                `hardCodedValue`
               - Each entry in this array contributes elements to the output array
               - Multiple entries allow combining data from different input arrays
 
@@ -4579,7 +4633,7 @@ components:
 
             **Common filter patterns**
 
-            1. **Pattern matching**: Using wildcards like `*` and `?`
+            1. **Pattern matching**: Regular expressions with `matches`
             2. **Value range filtering**: Numbers between min and max values
             3. **Date range filtering**: Items created/modified within specific time ranges
             4. **Status checking**: Items with specific status values or properties
@@ -4629,9 +4683,12 @@ components:
                 - `"endswith"`: String ends with specified suffix (ends with)
                 - `"contains"`: String contains specified substring (contains)
                 - `"doesnotcontain"`: String does not contain specified substring (does not contain)
-                - `"isempty"`: Field is empty or null (is empty)
-                - `"isnotempty"`: Field contains a value (is not empty)
-                - `"matches"`: Matches specified pattern (matches)
+                - `"empty"`: Field is missing or empty (is empty)
+                - `"notempty"`: Field contains a value (is not empty)
+                - `"matches"`: Matches a regular expression (matches)
+
+                `isempty`, `isnotempty` and `anyof` are not operators: they are refused with 422
+                "Invalid operation: <name>".
 
                 **Logical Operators**
                 - `"and"`: All conditions must be true
@@ -4651,7 +4708,11 @@ components:
                 **Using `extract` to access record fields:**
                 - Retrieves values from the current record being processed
                 - Can access nested properties using dot notation (e.g., `"customer.email"`)
-                - Returns the raw field value which may need type conversion
+                - In a record filter, must be wrapped in a type conversion (`string`, `number`,
+                  `boolean` or `epochtime`): a bare `["extract", ...]` operand is refused with 422
+                  "Field operation extract must be called by a Type Conversion Operation but was called
+                  by <operator>", both when an import's filter is saved and by
+                  `POST /v1/processors/filter`
 
                 **Using `settings` to access configuration values:**
                 - Retrieves values from the integration's configuration settings
@@ -4669,7 +4730,20 @@ components:
                 - `"floor"`: Round number down to the nearest integer
                 - `"abs"`: Get absolute value of a number
 
-                Type conversion operators are often necessary when comparing extracted field values against literals or when the field type doesn't match the comparison operator's expected type. For example:
+                **Handlebars operands**
+                - An operand can also be a string holding exactly one Handlebars expression, such as
+                  `"{{record.status}}"` or `"{{lowercase record.code}}"`, on either side of the
+                  operator. It renders against the record (`record.<field>`; an unprefixed
+                  `{{status}}` renders empty) before the comparison.
+                - The rendered value is a string: wrap it in `["number", ...]` to compare it with a
+                  number, or the rule is refused with 422.
+                - `epochtime` does not render Handlebars: `["epochtime", "{{timestamp}}"]` is refused
+                  with 422 "invalid datetime format".
+                - A string with text around the expression, or with more than one expression, is
+                  compared as a literal.
+
+                Choose the type conversion that matches the comparison — `number` for numeric
+                comparisons, `epochtime` for dates, `string` for text. For example:
 
                 ```json
                 [
@@ -4760,8 +4834,11 @@ components:
                 [
                   "notequals",
                   [
-                    "extract",
-                    "status"
+                    "string",
+                    [
+                      "extract",
+                      "status"
+                    ]
                   ],
                   "cancelled"
                 ]
@@ -4772,8 +4849,11 @@ components:
                 [
                   "startswith",
                   [
-                    "extract",
-                    "filename"
+                    "string",
+                    [
+                      "extract",
+                      "filename"
+                    ]
                   ],
                   "HC"
                 ]
@@ -4794,29 +4874,26 @@ components:
                 ]
                 ```
 
-                Example 4: Order date is after January 1, 2023
+                Example 4: Order date is after January 1, 2023 (UTC). Compare dates as `epochtime`
+                against epoch milliseconds: a `string` comparison of ISO timestamps orders values with
+                different UTC offsets wrongly.
                 ```json
                 [
                   "greaterthan",
                   [
-                    "extract",
-                    "orderDate"
-                  ],
-                  "2023-01-01T00:00:00Z"
-                ]
-                ```
-
-                Example 5: Category contains any of ["Urgent", "High Priority"]
-                ```json
-                [
-                  "anyof",
-                  [
-                    "extract",
-                    "category"
+                    "epochtime",
+                    [
+                      "extract",
+                      "orderDate"
+                    ]
                   ],
-                  ["Urgent", "High Priority"]
+                  1672531200000
                 ]
                 ```
+              x-celigo-ai-guidance:
+                - |-
+                  To test whether a field has a value, use `notempty` on the wrapped extract, not a
+                  `matches` pattern: a record without the field matches `.*\S.*`.
               items:
                 oneOf:
                   - title: String
@@ -5435,7 +5512,7 @@ components:
                     - envelope
                   x-enumDescriptions:
                     record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
-                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, settings, job, …}` (file-provider steps also carry `fileMeta`) — extracts must include the `record.` segment (`$.record.field`).
+                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
                   description: |
                     Controls the JSON shape the transformTwoDotZero processor
                     evaluates `mappings[].extract` JSONPath values against at
@@ -5455,10 +5532,12 @@ components:
                         `"$.PLACEHOLDER_<field>"`.
                         This is the dominant Celigo idiom and the right choice for new transforms.
                       - `envelope`: the processor sees a wrapped object
-                        `{record: {...}, settings: ..., job: ...}` (plus
-                        `fileMeta` on file-provider steps).
+                        `{record: {...}, job, testMode, settings, headers,
+                        queryParams}` (plus `fileMeta` on file-provider steps).
                         `mappings[].extract` JSONPath MUST include the
-                        `record.` segment — e.g. `"$.record.orderId"`;
+                        `record.` segment for record fields — e.g.
+                        `"$.record.orderId"` — and reads `headers` and
+                        `queryParams` beside it (`$.headers['X-Id']`);
                         PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
                         Pick this only when the transform was authored against
                         the envelope shape on purpose.
@@ -5467,6 +5546,11 @@ components:
                       (`{{record.field}}`, `{{dateFormat ... record.field}}`)
                       ALWAYS reference the `record` root regardless of
                       `inputContext` — only JSONPath anchoring flips.
+                    - |-
+                      In `envelope` mode a `modify` transform merges its mapped
+                      fields into `record` and keeps the rest of the envelope
+                      around it; a `create` transform returns only the mapped
+                      fields, as a bare record.
                     - |-
                       Emit `inputContext` explicitly on new v2 transforms:
                       unset is read as `record`, but stating it makes the
@@ -5487,13 +5571,17 @@ components:
 
                       - ``envelope``: the transform processor sees a wrapped
                         object of the shape
-                        ``{record: {...}, settings: ..., job: ...}`` (plus
-                        ``fileMeta`` on file-provider steps) — the
+                        ``{record: {...}, job, testMode, settings, headers,
+                        queryParams}`` (plus ``fileMeta`` on file-provider
+                        steps; ``headers`` and ``queryParams`` sit beside
+                        ``record``) — the
                         same runtime-context envelope Handlebars / SQL /
                         GraphQL templates render against.  ``mappings[].extract``
-                        JSONPath values MUST include the ``record.`` segment
-                        — for example ``"$.record.orderId"`` or
-                        ``"$.record.customer.email"``.  PLACEHOLDER extracts
+                        JSONPath values for record fields MUST include the
+                        ``record.`` segment — for example ``"$.record.orderId"``
+                        or ``"$.record.customer.email"`` — while ``headers`` and
+                        ``queryParams`` are read beside it
+                        (``"$.headers['X-Id']"``).  PLACEHOLDER extracts
                         use ``"$.record.PLACEHOLDER_<field>"``.  Pick this
                         mode only when the export was authored against the
                         envelope shape on purpose (typically because an