Filters
Use a filter to decide whether an automation runs.
A filter is a recursive and/or tree of conditions that the triggering record must match.
The tree: groups and conditions
{
"operator": "and",
"rows": [
{
"subject": { "kind": "variable", "source": "field", "field_id": 512, "field_type": "single_category", "previous": false, "collection": false, "triggering": false },
"operator": "is_any_of",
"value": { "type": "ids", "ids": [9001] }
},
{
"subject": { "kind": "variable", "source": "field", "field_id": 513, "field_type": "number", "previous": false, "collection": false, "triggering": false },
"operator": "greater_or_equal_than",
"value": { "type": "number", "number": ["1000"] }
}
]
}
A group combines its rows, nested groups or conditions, with and (match all) or or (match any). The root group has no id.
| Property | Type | On | Description |
|---|---|---|---|
id | string | Nested nodes | Opaque node ID. Optional on input, Tape creates one when you leave it out. Present on every read. |
operator | string | Group | and or or. |
rows | array | Group | Nested groups and conditions. |
subject | object | Condition | A reference to the value being tested: a field, record metadata, a trigger output or an action's file collection. See v1 limitations. |
operator | string | Condition | One of the operators below. |
value | object | Condition | The tagged comparison value, see The value union. Absent for operators without a value. |
code | array | Condition | A raw code condition, a code dynamic value. A script condition has code instead of subject, operator and value. |
General behavior
- An automation without a filter has
filter: nulland runs every time. - To run without a filter, send
filter: nullexplicitly. An explicitly empty top-level group (rows: []) returns400. It narrows nothing and would fire on every record. - An empty group is still allowed inside an action, for example a
conditionalconditionthat is true every time, or amatch_conditionthat keeps everything. The trigger filter already limits which records the automation runs on.
The same public tree (operator: "and" | "or", rows) appears everywhere conditions do:
- an automation's
filter, - a control-flow action's
condition,break_conditionandcontinue_condition, - a condition inside an action's
config, for example thematch_conditionofcollect_app_recordsorfilter_record_collection.
All of them use the same lower-case operator and rows. See Actions.
Operators
Each operator has a value_arity: none (no value, for example is_empty), single or multiple. The valid operators differ per field type. GET /v1/automation/meta/filter?field_type=… returns the exact set.
| Operator | Arity | Operator | Arity | |
|---|---|---|---|---|
is | single | has_any_of | multiple | |
is_not | single | has_all_of | multiple | |
contains | single | has_none_of | multiple | |
does_not_contain | single | is_exactly | multiple | |
starts_with | single | is_any_of | multiple | |
ends_with | single | is_none_of | multiple | |
greater_than | single | has_changed_to_any_of | multiple | |
greater_or_equal_than | single | is_empty | none | |
less_than | single | is_not_empty | none | |
less_or_equal_than | single | is_completed | none | |
is_before | single | is_incomplete | none | |
is_after | single | has_changed | none | |
glob_pattern | single | |||
has_changed_to | single |
File name patterns
glob_pattern (label Matches pattern) checks whether file names match a glob pattern, for example "*.pdf".
- It works only on subjects that carry files:
single_attachment,multi_attachment,multi_image, an action's file collection, webhook payload files and comment attachments. - Tape rejects it in
collect_app_records,collect_referenced_records,collected_records_collect_referenced_recordsand in thesearch_conditionof a relation field assignment.
Change tracking
has_changed, has_changed_to and has_changed_to_any_of compare a field with the previous revision of the record.
- They're valid only under a
record_updatedtrigger, or after acurrent_record_get_previous_revisionaction on the same app. Otherwisevalidatereports the automation as invalid. has_changed(label Has changed) takes no value.has_changed_to(label Has changed to) works on subjects with a single choice: status, single category, single user, single relation, last modified by, and on a checklist.has_changed_to_any_of(label Has changed to any of) works on subjects with multiple choices: multi category, multi user, multi relation.
The value union
The condition value is tagged by type, so you can read it without knowing the rules for each field:
type | Payload | Meaning |
|---|---|---|
text | text: a template dynamic value | Text or template comparison. |
number | number: a code dynamic value | Number comparison as a code expression. |
ids | ids: array of number or reference | A set of option, status, relation or user IDs. |
date | date: { base?, operator, unit, amount } | Relative date. operator is "plus" or "minus", unit is "hour", "day", "week" or "month". See Relative dates. |
boolean | boolean | Boolean comparison. Comes from a webhook payload property subject. Sends back without change. |
entity_type | entity_type: string | Comparison of the comment or reply entity type. Sends back without change. |
Retrieve a single app returns the option IDs for ids in config.settings.options of each field.
Relative dates
baseis optional. Without it, Tape uses thecurrent_dateglobal. Tape stores it on write, so it reads back and sends back unchanged. Set abasereference to count from something other than today.operatorandunitonly accept the listed values. Anything else returns400. Leave them out to keep the defaultsplusandday.amountis a code dynamic value: an array of strings (for example["1"]) or a plain string ("1", returned as["1"]). A plain number (1) returns400. A read returns the array form, so a retrieved definition sends back unchanged.
Match the value type to the field
Tape reads a value by its tag, but writes it by field. On create and update, Tape picks the value channel from the type of the subject field:
- number and unique ID →
number - date fields →
date - category, status, relation and user →
ids - text →
text
On create and update:
- A value whose
typedoesn't match the field's channel returns400. The check goes through all levels of nested groups. The response names the condition (by itsid, or by its JSON path, for examplefilter.rows[1].rows[0]) and the tag it expected. - An empty comparison value returns
400the same way. So does an arity mismatch: a value on an operator with aritynonesuch asis_empty, or a missing value on an operator that needs one. - Existing rows aren't checked again. Definitions saved before this check, or in the automation editor in Tape, can still hold an empty comparison.
- An operator outside the field type's channel is not rejected if it's otherwise well-formed, for example a text operator on a number field with a number value. It passes
validateand never matches when the automation runs.
meta/filter returns only operators, not the accepted tag. Match the tag to the field yourself, and use only the operators it returns for the field's type.
A value built from a reference (a field, a variable or the output of an earlier action) passes the write check, but it can resolve to empty for a record. An empty value matches everything, so under the default and group the filter matches every record. Guard such references. A simulation skips the filter, a manual run applies it.
v1 limitations
- A subject needs a condition it can be tested with. On create and update, a condition's
subjectcan be a field reference, most record metadata references (app_record_id,created_at,last_modified_at,created_by,last_modified_by), a trigger output reference (for examplewebhook_payload_property) or the file collection of an earlier action. All of these are writable and send back unchanged. Tokens that only carry a value and can't be tested (meta_typerecord_id,record_url,revision,all_comments, the rawwebhook_payload) andglobalorcustomreferences return400on write. - Collection-change conditions are read-only. Has been added and Has been deleted on an attachment, image or checklist field, and Changed item contains on a checklist field, have no public operator. They read as an
{ id, subject }without an operator and can't be sent back unchanged. Other change-tracking conditions use the public operatorshas_changed,has_changed_toandhas_changed_to_any_ofand send back without problems.
A GET followed by an unchanged PUT fails only for an automation with such a collection-change condition, so remove these conditions first. All other subjects send back unchanged, including the boolean and entity_type value kinds.