@celigo/api-specs 0.2.137 → 0.2.139

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/template.yml CHANGED
@@ -329,6 +329,11 @@ paths:
329
329
  whose `type` is `mcpserver` is rejected before anything is created —
330
330
  install it with `POST /v1/mcpservers/template/{_templateId}` instead.
331
331
  Check `type` on the `GET /v1/templates/{_id}/preview` response first.
332
+
333
+ This one-shot install doesn't run a template's own install steps. A
334
+ template whose preview `Integration` object lists `installSteps` is
335
+ refused with nothing created; install it from the integrator.io
336
+ marketplace, whose installer runs those steps.
332
337
  parameters:
333
338
  - name: _id
334
339
  in: path
@@ -371,19 +376,36 @@ paths:
371
376
  61f92026dd053843b5d72350: 64a1234567890abcdef12345
372
377
  61f92026dd053843b5d72351: 64a1234567890abcdef12346
373
378
  responses:
374
- '200':
375
- description: Template installed successfully.
379
+ '201':
380
+ description: Template installed. Returns one entry per resource the install created.
376
381
  content:
377
382
  application/json:
378
383
  schema:
379
- type: object
380
- description: The created integration and related resources.
381
- additionalProperties: true
384
+ type: array
385
+ description: The resources the install created, the new integration among them.
386
+ items:
387
+ type: object
388
+ properties:
389
+ model:
390
+ type: string
391
+ description: Resource type of the created document (`Integration`, `Flow`, `Export`, `Import`, ...).
392
+ _id:
393
+ type: string
394
+ format: objectId
395
+ description: Id of the created document.
396
+ additionalProperties: true
382
397
  examples:
383
398
  installed:
384
- summary: Integration created from the template
399
+ summary: Integration, flow, export and import created from the template
385
400
  value:
386
- _integrationId: 6405b9d73496e05ff253d587
401
+ - model: Integration
402
+ _id: 6405b9d73496e05ff253d587
403
+ - model: Flow
404
+ _id: 6405b9d83496e05ff253d58c
405
+ - model: Export
406
+ _id: 6405b9d83496e05ff253d590
407
+ - model: Import
408
+ _id: 6405b9d83496e05ff253d594
387
409
  '400':
388
410
  description: |-
389
411
  Missing or empty `connectionMap`, or the template is an MCP server
@@ -424,7 +446,8 @@ paths:
424
446
  '422':
425
447
  description: |-
426
448
  Connection IDs in `connectionMap` do not match the template's
427
- expected connection IDs.
449
+ expected connection IDs, or the template has its own install steps
450
+ (a `template_zip` step this install doesn't run). Nothing is created.
428
451
  content:
429
452
  application/json:
430
453
  schema:
@@ -435,6 +458,11 @@ paths:
435
458
  errors:
436
459
  - code: invalid_connectionId
437
460
  message: Invalid connection ID in connectionMap.
461
+ templateInstallSteps:
462
+ summary: Template with its own install steps
463
+ value:
464
+ errors:
465
+ - message: 'Failed to create Integration due to: Install step is invalid: invalid templateZip.'
438
466
  /v1/integrations/template/preview:
439
467
  get:
440
468
  x-internal: false
package/dist/tool.yml CHANGED
@@ -3546,14 +3546,15 @@ components:
3546
3546
  - `objectarray`: Array of objects (most common array type)
3547
3547
  - `arrayarray`: Array of arrays (for matrix/table structures)
3548
3548
 
3549
- Array dataTypes can be populated two ways: pass a source array through
3550
- unchanged via `extract` alone (when the source is already an array of
3551
- the right shape), or construct/iterate via `buildArrayHelper`.
3549
+ Array dataTypes can be populated three ways: pass a source array
3550
+ through unchanged via a JSONPath `extract` alone (when the source is
3551
+ already an array of the right shape), construct/iterate via
3552
+ `buildArrayHelper`, or set a constant with `hardCodedValue`.
3552
3553
 
3553
3554
  IMPORTANT: The dataType controls which additional fields are relevant:
3554
3555
  - For date-like string fields: extractDateFormat, generateDateFormat, etc. become relevant
3555
3556
  - For object types: 'mappings' array becomes relevant
3556
- - For array types: `buildArrayHelper` is one option (see above)
3557
+ - For array types: a JSONPath `extract` alone, `buildArrayHelper`, or `hardCodedValue` (see above)
3557
3558
 
3558
3559
  When analyzing existing mappings or generating new ones, always check dataType first
3559
3560
  to understand what additional fields should be present.
@@ -3616,9 +3617,12 @@ components:
3616
3617
  - Access input record fields with {{record.fieldName}} notation; a grouped
3617
3618
  (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
3618
3619
  - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
3619
- - Valid on `object`, `objectarray`, and primitive-array dataTypes as
3620
- well as scalars — the rendered template output must parse into the
3621
- declared shape
3620
+ - Valid on scalars and on `object` rows, where the rendered output must
3621
+ parse into an object. On an array row the template goes in a
3622
+ `buildArrayHelper` entry instead: on an `objectarray` row's own
3623
+ `extract` it is refused with 422 ("buildArrayHelper" must be present
3624
+ for object array datatype), and on a primitive-array row's own
3625
+ `extract` it renders null without an error
3622
3626
 
3623
3627
  ```json
3624
3628
  "extract": "{{record.price}} {{record.currency}}" // Combines two fields
@@ -3817,6 +3821,19 @@ components:
3817
3821
  - countryCodeToName
3818
3822
  - statusMapping
3819
3823
  - departmentCodes
3824
+ hardCodedValue:
3825
+ type: string
3826
+ description: |
3827
+ Constant written to the destination instead of an extracted value. On a primitive
3828
+ array (`stringarray`, `numberarray`, `booleanarray`) the string is split on commas,
3829
+ verbatim and untrimmed, into elements of the array's type (`"A,B"` gives `["A", "B"]`).
3830
+ On an `object` it must be a JSON object string and on an `objectarray` a JSON array
3831
+ string (an object string becomes one element); the save parses it and refuses non-JSON
3832
+ or the wrong shape with 422, and an array row with a constant needs no `buildArrayHelper`.
3833
+ examples:
3834
+ - USD
3835
+ - A,B
3836
+ - '[{"code": "A"}, {"code": "B"}]'
3820
3837
  description:
3821
3838
  type: string
3822
3839
  description: |
@@ -3952,15 +3969,25 @@ components:
3952
3969
  processor renders the entire destination array as null with no
3953
3970
  validation error. To emit a fixed number of static elements, add
3954
3971
  that many sibling constructed entries — never index the extract.
3972
+ - |-
3973
+ An entry's `extract` can be a Handlebars template. On an
3974
+ `objectarray` it must render a JSON object (one element) or a JSON
3975
+ array (one element per item). On a primitive array each entry
3976
+ renders one element, so a serialized array becomes one string
3977
+ element. A bare literal entry extract is refused with 422 ("extract
3978
+ only supports json path or handlebars expression"); set a constant
3979
+ with the row's `hardCodedValue` instead.
3955
3980
  description: |
3956
3981
  **Purpose**
3957
3982
  Configures how to construct arrays in the output record, handling various array types and inputs.
3958
3983
 
3959
3984
  **Guidance**
3960
- This is the REQUIRED mechanism for ALL array data types:
3985
+ This is the mechanism for building array data types:
3961
3986
 
3962
3987
  **When to Use**
3963
- - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.)
3988
+ - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
3989
+ row passes a source array through with a JSONPath `extract` alone or sets
3990
+ `hardCodedValue`
3964
3991
  - Each entry in this array contributes elements to the output array
3965
3992
  - Multiple entries allow combining data from different input arrays
3966
3993
 
@@ -4585,14 +4612,15 @@ components:
4585
4612
  - `objectarray`: Array of objects (most common array type)
4586
4613
  - `arrayarray`: Array of arrays (for matrix/table structures)
4587
4614
 
4588
- Array dataTypes can be populated two ways: pass a source array through
4589
- unchanged via `extract` alone (when the source is already an array of
4590
- the right shape), or construct/iterate via `buildArrayHelper`.
4615
+ Array dataTypes can be populated three ways: pass a source array
4616
+ through unchanged via a JSONPath `extract` alone (when the source is
4617
+ already an array of the right shape), construct/iterate via
4618
+ `buildArrayHelper`, or set a constant with `hardCodedValue`.
4591
4619
 
4592
4620
  IMPORTANT: The dataType controls which additional fields are relevant:
4593
4621
  - For date-like string fields: extractDateFormat, generateDateFormat, etc. become relevant
4594
4622
  - For object types: 'mappings' array becomes relevant
4595
- - For array types: `buildArrayHelper` is one option (see above)
4623
+ - For array types: a JSONPath `extract` alone, `buildArrayHelper`, or `hardCodedValue` (see above)
4596
4624
 
4597
4625
  When analyzing existing mappings or generating new ones, always check dataType first
4598
4626
  to understand what additional fields should be present.
@@ -4655,9 +4683,12 @@ components:
4655
4683
  - Access input record fields with {{record.fieldName}} notation; a grouped
4656
4684
  (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
4657
4685
  - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
4658
- - Valid on `object`, `objectarray`, and primitive-array dataTypes as
4659
- well as scalars — the rendered template output must parse into the
4660
- declared shape
4686
+ - Valid on scalars and on `object` rows, where the rendered output must
4687
+ parse into an object. On an array row the template goes in a
4688
+ `buildArrayHelper` entry instead: on an `objectarray` row's own
4689
+ `extract` it is refused with 422 ("buildArrayHelper" must be present
4690
+ for object array datatype), and on a primitive-array row's own
4691
+ `extract` it renders null without an error
4661
4692
 
4662
4693
  ```json
4663
4694
  "extract": "{{record.price}} {{record.currency}}" // Combines two fields
@@ -4856,6 +4887,19 @@ components:
4856
4887
  - countryCodeToName
4857
4888
  - statusMapping
4858
4889
  - departmentCodes
4890
+ hardCodedValue:
4891
+ type: string
4892
+ description: |
4893
+ Constant written to the destination instead of an extracted value. On a primitive
4894
+ array (`stringarray`, `numberarray`, `booleanarray`) the string is split on commas,
4895
+ verbatim and untrimmed, into elements of the array's type (`"A,B"` gives `["A", "B"]`).
4896
+ On an `object` it must be a JSON object string and on an `objectarray` a JSON array
4897
+ string (an object string becomes one element); the save parses it and refuses non-JSON
4898
+ or the wrong shape with 422, and an array row with a constant needs no `buildArrayHelper`.
4899
+ examples:
4900
+ - USD
4901
+ - A,B
4902
+ - '[{"code": "A"}, {"code": "B"}]'
4859
4903
  description:
4860
4904
  type: string
4861
4905
  description: |
@@ -4991,15 +5035,25 @@ components:
4991
5035
  processor renders the entire destination array as null with no
4992
5036
  validation error. To emit a fixed number of static elements, add
4993
5037
  that many sibling constructed entries — never index the extract.
5038
+ - |-
5039
+ An entry's `extract` can be a Handlebars template. On an
5040
+ `objectarray` it must render a JSON object (one element) or a JSON
5041
+ array (one element per item). On a primitive array each entry
5042
+ renders one element, so a serialized array becomes one string
5043
+ element. A bare literal entry extract is refused with 422 ("extract
5044
+ only supports json path or handlebars expression"); set a constant
5045
+ with the row's `hardCodedValue` instead.
4994
5046
  description: |
4995
5047
  **Purpose**
4996
5048
  Configures how to construct arrays in the output record, handling various array types and inputs.
4997
5049
 
4998
5050
  **Guidance**
4999
- This is the REQUIRED mechanism for ALL array data types:
5051
+ This is the mechanism for building array data types:
5000
5052
 
5001
5053
  **When to Use**
5002
- - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.)
5054
+ - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
5055
+ row passes a source array through with a JSONPath `extract` alone or sets
5056
+ `hardCodedValue`
5003
5057
  - Each entry in this array contributes elements to the output array
5004
5058
  - Multiple entries allow combining data from different input arrays
5005
5059
 
@@ -6030,7 +6084,7 @@ components:
6030
6084
  - envelope
6031
6085
  x-enumDescriptions:
6032
6086
  record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
6033
- 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`).
6087
+ 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`).
6034
6088
  description: |
6035
6089
  Controls the JSON shape the transformTwoDotZero processor
6036
6090
  evaluates `mappings[].extract` JSONPath values against at
@@ -6050,10 +6104,12 @@ components:
6050
6104
  `"$.PLACEHOLDER_<field>"`.
6051
6105
  This is the dominant Celigo idiom and the right choice for new transforms.
6052
6106
  - `envelope`: the processor sees a wrapped object
6053
- `{record: {...}, settings: ..., job: ...}` (plus
6054
- `fileMeta` on file-provider steps).
6107
+ `{record: {...}, job, testMode, settings, headers,
6108
+ queryParams}` (plus `fileMeta` on file-provider steps).
6055
6109
  `mappings[].extract` JSONPath MUST include the
6056
- `record.` segment — e.g. `"$.record.orderId"`;
6110
+ `record.` segment for record fields — e.g.
6111
+ `"$.record.orderId"` — and reads `headers` and
6112
+ `queryParams` beside it (`$.headers['X-Id']`);
6057
6113
  PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
6058
6114
  Pick this only when the transform was authored against
6059
6115
  the envelope shape on purpose.
@@ -6062,6 +6118,11 @@ components:
6062
6118
  (`{{record.field}}`, `{{dateFormat ... record.field}}`)
6063
6119
  ALWAYS reference the `record` root regardless of
6064
6120
  `inputContext` — only JSONPath anchoring flips.
6121
+ - |-
6122
+ In `envelope` mode a `modify` transform merges its mapped
6123
+ fields into `record` and keeps the rest of the envelope
6124
+ around it; a `create` transform returns only the mapped
6125
+ fields, as a bare record.
6065
6126
  - |-
6066
6127
  Emit `inputContext` explicitly on new v2 transforms:
6067
6128
  unset is read as `record`, but stating it makes the
@@ -6082,13 +6143,17 @@ components:
6082
6143
 
6083
6144
  - ``envelope``: the transform processor sees a wrapped
6084
6145
  object of the shape
6085
- ``{record: {...}, settings: ..., job: ...}`` (plus
6086
- ``fileMeta`` on file-provider steps) — the
6146
+ ``{record: {...}, job, testMode, settings, headers,
6147
+ queryParams}`` (plus ``fileMeta`` on file-provider
6148
+ steps; ``headers`` and ``queryParams`` sit beside
6149
+ ``record``) — the
6087
6150
  same runtime-context envelope Handlebars / SQL /
6088
6151
  GraphQL templates render against. ``mappings[].extract``
6089
- JSONPath values MUST include the ``record.`` segment
6090
- — for example ``"$.record.orderId"`` or
6091
- ``"$.record.customer.email"``. PLACEHOLDER extracts
6152
+ JSONPath values for record fields MUST include the
6153
+ ``record.`` segment — for example ``"$.record.orderId"``
6154
+ or ``"$.record.customer.email"`` — while ``headers`` and
6155
+ ``queryParams`` are read beside it
6156
+ (``"$.headers['X-Id']"``). PLACEHOLDER extracts
6092
6157
  use ``"$.record.PLACEHOLDER_<field>"``. Pick this
6093
6158
  mode only when the export was authored against the
6094
6159
  envelope shape on purpose (typically because an
@@ -7146,21 +7211,11 @@ components:
7146
7211
  format: objectId
7147
7212
  x-celigo-refModel: connectors
7148
7213
  readOnly: true
7149
- description: |
7150
- Reference to the integration app that defines this resource.
7151
-
7152
- This field is only populated for resources that are part of an integration app.
7153
- It contains the unique identifier (_id) of the integration app (connector)
7154
- that defines the structure, behavior, and templates for this resource.
7155
-
7156
- The integration app is the published template that can be installed
7157
- multiple times across different accounts, with each installation creating
7158
- a separate integration instance (referenced by _integrationId).
7159
-
7160
- This reference enables:
7161
- - Identifying the source integration app for this resource
7162
- - Determining which template version is being used
7163
- - Linking to documentation, support, and marketplace information
7214
+ description: |-
7215
+ Integration App (connector) that defines this resource. Present only on resources an
7216
+ Integration App owns. The app locks parts of these documents, and a PUT that changes a
7217
+ locked field answers 200 but keeps the stored value, so read the document back to confirm
7218
+ a change.
7164
7219
  examples:
7165
7220
  - 5e8d43a1b9e5a80011a35f1b
7166
7221
  x-celigo-ai-guidance:
@@ -23442,7 +23497,7 @@ components:
23442
23497
 
23443
23498
  **Common filter patterns**
23444
23499
 
23445
- 1. **Pattern matching**: Using wildcards like `*` and `?`
23500
+ 1. **Pattern matching**: Regular expressions with `matches`
23446
23501
  2. **Value range filtering**: Numbers between min and max values
23447
23502
  3. **Date range filtering**: Items created/modified within specific time ranges
23448
23503
  4. **Status checking**: Items with specific status values or properties
@@ -23492,9 +23547,12 @@ components:
23492
23547
  - `"endswith"`: String ends with specified suffix (ends with)
23493
23548
  - `"contains"`: String contains specified substring (contains)
23494
23549
  - `"doesnotcontain"`: String does not contain specified substring (does not contain)
23495
- - `"isempty"`: Field is empty or null (is empty)
23496
- - `"isnotempty"`: Field contains a value (is not empty)
23497
- - `"matches"`: Matches specified pattern (matches)
23550
+ - `"empty"`: Field is missing or empty (is empty)
23551
+ - `"notempty"`: Field contains a value (is not empty)
23552
+ - `"matches"`: Matches a regular expression (matches)
23553
+
23554
+ `isempty`, `isnotempty` and `anyof` are not operators: they are refused with 422
23555
+ "Invalid operation: <name>".
23498
23556
 
23499
23557
  **Logical Operators**
23500
23558
  - `"and"`: All conditions must be true
@@ -23514,7 +23572,11 @@ components:
23514
23572
  **Using `extract` to access record fields:**
23515
23573
  - Retrieves values from the current record being processed
23516
23574
  - Can access nested properties using dot notation (e.g., `"customer.email"`)
23517
- - Returns the raw field value which may need type conversion
23575
+ - In a record filter, must be wrapped in a type conversion (`string`, `number`,
23576
+ `boolean` or `epochtime`): a bare `["extract", ...]` operand is refused with 422
23577
+ "Field operation extract must be called by a Type Conversion Operation but was called
23578
+ by <operator>", both when an import's filter is saved and by
23579
+ `POST /v1/processors/filter`
23518
23580
 
23519
23581
  **Using `settings` to access configuration values:**
23520
23582
  - Retrieves values from the integration's configuration settings
@@ -23532,7 +23594,20 @@ components:
23532
23594
  - `"floor"`: Round number down to the nearest integer
23533
23595
  - `"abs"`: Get absolute value of a number
23534
23596
 
23535
- 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:
23597
+ **Handlebars operands**
23598
+ - An operand can also be a string holding exactly one Handlebars expression, such as
23599
+ `"{{record.status}}"` or `"{{lowercase record.code}}"`, on either side of the
23600
+ operator. It renders against the record (`record.<field>`; an unprefixed
23601
+ `{{status}}` renders empty) before the comparison.
23602
+ - The rendered value is a string: wrap it in `["number", ...]` to compare it with a
23603
+ number, or the rule is refused with 422.
23604
+ - `epochtime` does not render Handlebars: `["epochtime", "{{timestamp}}"]` is refused
23605
+ with 422 "invalid datetime format".
23606
+ - A string with text around the expression, or with more than one expression, is
23607
+ compared as a literal.
23608
+
23609
+ Choose the type conversion that matches the comparison — `number` for numeric
23610
+ comparisons, `epochtime` for dates, `string` for text. For example:
23536
23611
 
23537
23612
  ```json
23538
23613
  [
@@ -23623,8 +23698,11 @@ components:
23623
23698
  [
23624
23699
  "notequals",
23625
23700
  [
23626
- "extract",
23627
- "status"
23701
+ "string",
23702
+ [
23703
+ "extract",
23704
+ "status"
23705
+ ]
23628
23706
  ],
23629
23707
  "cancelled"
23630
23708
  ]
@@ -23635,8 +23713,11 @@ components:
23635
23713
  [
23636
23714
  "startswith",
23637
23715
  [
23638
- "extract",
23639
- "filename"
23716
+ "string",
23717
+ [
23718
+ "extract",
23719
+ "filename"
23720
+ ]
23640
23721
  ],
23641
23722
  "HC"
23642
23723
  ]
@@ -23657,29 +23738,26 @@ components:
23657
23738
  ]
23658
23739
  ```
23659
23740
 
23660
- Example 4: Order date is after January 1, 2023
23741
+ Example 4: Order date is after January 1, 2023 (UTC). Compare dates as `epochtime`
23742
+ against epoch milliseconds: a `string` comparison of ISO timestamps orders values with
23743
+ different UTC offsets wrongly.
23661
23744
  ```json
23662
23745
  [
23663
23746
  "greaterthan",
23664
23747
  [
23665
- "extract",
23666
- "orderDate"
23667
- ],
23668
- "2023-01-01T00:00:00Z"
23669
- ]
23670
- ```
23671
-
23672
- Example 5: Category contains any of ["Urgent", "High Priority"]
23673
- ```json
23674
- [
23675
- "anyof",
23676
- [
23677
- "extract",
23678
- "category"
23748
+ "epochtime",
23749
+ [
23750
+ "extract",
23751
+ "orderDate"
23752
+ ]
23679
23753
  ],
23680
- ["Urgent", "High Priority"]
23754
+ 1672531200000
23681
23755
  ]
23682
23756
  ```
23757
+ x-celigo-ai-guidance:
23758
+ - |-
23759
+ To test whether a field has a value, use `notempty` on the wrapped extract, not a
23760
+ `matches` pattern: a record without the field matches `.*\S.*`.
23683
23761
  items:
23684
23762
  oneOf:
23685
23763
  - title: String
@@ -563,7 +563,7 @@ components:
563
563
 
564
564
  **Common filter patterns**
565
565
 
566
- 1. **Pattern matching**: Using wildcards like `*` and `?`
566
+ 1. **Pattern matching**: Regular expressions with `matches`
567
567
  2. **Value range filtering**: Numbers between min and max values
568
568
  3. **Date range filtering**: Items created/modified within specific time ranges
569
569
  4. **Status checking**: Items with specific status values or properties
@@ -613,9 +613,12 @@ components:
613
613
  - `"endswith"`: String ends with specified suffix (ends with)
614
614
  - `"contains"`: String contains specified substring (contains)
615
615
  - `"doesnotcontain"`: String does not contain specified substring (does not contain)
616
- - `"isempty"`: Field is empty or null (is empty)
617
- - `"isnotempty"`: Field contains a value (is not empty)
618
- - `"matches"`: Matches specified pattern (matches)
616
+ - `"empty"`: Field is missing or empty (is empty)
617
+ - `"notempty"`: Field contains a value (is not empty)
618
+ - `"matches"`: Matches a regular expression (matches)
619
+
620
+ `isempty`, `isnotempty` and `anyof` are not operators: they are refused with 422
621
+ "Invalid operation: <name>".
619
622
 
620
623
  **Logical Operators**
621
624
  - `"and"`: All conditions must be true
@@ -635,7 +638,11 @@ components:
635
638
  **Using `extract` to access record fields:**
636
639
  - Retrieves values from the current record being processed
637
640
  - Can access nested properties using dot notation (e.g., `"customer.email"`)
638
- - Returns the raw field value which may need type conversion
641
+ - In a record filter, must be wrapped in a type conversion (`string`, `number`,
642
+ `boolean` or `epochtime`): a bare `["extract", ...]` operand is refused with 422
643
+ "Field operation extract must be called by a Type Conversion Operation but was called
644
+ by <operator>", both when an import's filter is saved and by
645
+ `POST /v1/processors/filter`
639
646
 
640
647
  **Using `settings` to access configuration values:**
641
648
  - Retrieves values from the integration's configuration settings
@@ -653,7 +660,20 @@ components:
653
660
  - `"floor"`: Round number down to the nearest integer
654
661
  - `"abs"`: Get absolute value of a number
655
662
 
656
- 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:
663
+ **Handlebars operands**
664
+ - An operand can also be a string holding exactly one Handlebars expression, such as
665
+ `"{{record.status}}"` or `"{{lowercase record.code}}"`, on either side of the
666
+ operator. It renders against the record (`record.<field>`; an unprefixed
667
+ `{{status}}` renders empty) before the comparison.
668
+ - The rendered value is a string: wrap it in `["number", ...]` to compare it with a
669
+ number, or the rule is refused with 422.
670
+ - `epochtime` does not render Handlebars: `["epochtime", "{{timestamp}}"]` is refused
671
+ with 422 "invalid datetime format".
672
+ - A string with text around the expression, or with more than one expression, is
673
+ compared as a literal.
674
+
675
+ Choose the type conversion that matches the comparison — `number` for numeric
676
+ comparisons, `epochtime` for dates, `string` for text. For example:
657
677
 
658
678
  ```json
659
679
  [
@@ -744,8 +764,11 @@ components:
744
764
  [
745
765
  "notequals",
746
766
  [
747
- "extract",
748
- "status"
767
+ "string",
768
+ [
769
+ "extract",
770
+ "status"
771
+ ]
749
772
  ],
750
773
  "cancelled"
751
774
  ]
@@ -756,8 +779,11 @@ components:
756
779
  [
757
780
  "startswith",
758
781
  [
759
- "extract",
760
- "filename"
782
+ "string",
783
+ [
784
+ "extract",
785
+ "filename"
786
+ ]
761
787
  ],
762
788
  "HC"
763
789
  ]
@@ -778,29 +804,26 @@ components:
778
804
  ]
779
805
  ```
780
806
 
781
- Example 4: Order date is after January 1, 2023
807
+ Example 4: Order date is after January 1, 2023 (UTC). Compare dates as `epochtime`
808
+ against epoch milliseconds: a `string` comparison of ISO timestamps orders values with
809
+ different UTC offsets wrongly.
782
810
  ```json
783
811
  [
784
812
  "greaterthan",
785
813
  [
786
- "extract",
787
- "orderDate"
788
- ],
789
- "2023-01-01T00:00:00Z"
790
- ]
791
- ```
792
-
793
- Example 5: Category contains any of ["Urgent", "High Priority"]
794
- ```json
795
- [
796
- "anyof",
797
- [
798
- "extract",
799
- "category"
814
+ "epochtime",
815
+ [
816
+ "extract",
817
+ "orderDate"
818
+ ]
800
819
  ],
801
- ["Urgent", "High Priority"]
820
+ 1672531200000
802
821
  ]
803
822
  ```
823
+ x-celigo-ai-guidance:
824
+ - |-
825
+ To test whether a field has a value, use `notempty` on the wrapped extract, not a
826
+ `matches` pattern: a record without the field matches `.*\S.*`.
804
827
  items:
805
828
  oneOf:
806
829
  - title: String
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@celigo/api-specs",
3
- "version": "0.2.137",
3
+ "version": "0.2.139",
4
4
  "private": false,
5
5
  "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
6
6
  "keywords": [
package/schemas.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "provenance": {
3
3
  "repo": "celigo/integrator-api-specs",
4
- "iasCommit": "37458f51",
4
+ "iasCommit": "01fd1fe4",
5
5
  "generatedAt": "2026-10-21"
6
6
  },
7
7
  "roots": {
@@ -923,6 +923,7 @@
923
923
  "generate": 1,
924
924
  "generateDateFormat": 1,
925
925
  "generateDateTimezone": 1,
926
+ "hardCodedValue": 1,
926
927
  "lookupName": 1,
927
928
  "mappings": 86,
928
929
  "sourceDataType": 87,
@@ -2130,6 +2131,7 @@
2130
2131
  "generate": 1,
2131
2132
  "generateDateFormat": 1,
2132
2133
  "generateDateTimezone": 1,
2134
+ "hardCodedValue": 1,
2133
2135
  "lookupName": 1,
2134
2136
  "mappings": 206,
2135
2137
  "sourceDataType": 87,
@@ -5160,6 +5162,7 @@
5160
5162
  "generate": 1,
5161
5163
  "generateDateFormat": 1,
5162
5164
  "generateDateTimezone": 1,
5165
+ "hardCodedValue": 1,
5163
5166
  "lookupName": 1,
5164
5167
  "mappings": 438,
5165
5168
  "sourceDataType": 87,
@@ -7526,6 +7529,7 @@
7526
7529
  "generate": 1,
7527
7530
  "generateDateFormat": 1,
7528
7531
  "generateDateTimezone": 1,
7532
+ "hardCodedValue": 1,
7529
7533
  "lookupName": 1,
7530
7534
  "mappings": 627,
7531
7535
  "sourceDataType": 87,
@@ -8761,6 +8765,7 @@
8761
8765
  "generate": 1,
8762
8766
  "generateDateFormat": 1,
8763
8767
  "generateDateTimezone": 1,
8768
+ "hardCodedValue": 1,
8764
8769
  "lookupName": 1,
8765
8770
  "mappings": 726,
8766
8771
  "sourceDataType": 87,