Skip to main content

Formulas in Filters

James Herring
Updated

Formulas in Filters

The right-hand side of a filter condition can use formula expressions, giving you access to functions, arithmetic, string operations, and more when defining filter values.

How It Works

In a standard filter condition, the structure is:

[field]   operator   value

The field name on the left is written in square brackets. The value (right-hand side) can be a formula expression instead of a static value. This means you can write:

[created_date] > datetime.now() - timedelta(days=30)

Here, [created_date] is the field, > is the operator, and datetime.now() - timedelta(days=30) is a formula expression that computes a date 30 days ago.

Important: = vs ==

This is the most common source of confusion when working with filters and formulas.

Context Equality Operator Example
Filters = [status] = "active"
Formulas == "active" if [status] == "open" else "closed"
  • In the filter builder, = means "is equal to" — it's the filter operator
  • In formula expressions, == is the Python equality comparison operator

When you write a filter condition, the = is the filter operator, and the right side is evaluated as a formula. You do not use == in the filter operator position.

Correct

[priority] = int(max_priority) - 1

The = is the filter operator. int(max_priority) - 1 is a formula evaluated at runtime.

Incorrect

[priority] == int(max_priority) - 1

== is not a valid filter operator. Use = for filter equality.

What You Can Use on the Right Side

Any valid formula expression is allowed as the filter value:

Function Calls

[created_date] > datetime(2024, 1, 1)
[updated_date] > datetime.now() - timedelta(days=7)

Arithmetic

[priority] = max_priority - 1
[score] > min_score * 1.5

String Operations

[category] = target_category.lower()
[name] = first_name + ' ' + last_name

Variable References

[status] = current_status
[assigned_to] = team_lead_id
[sys_id] in extracted_id_list

Combined Expressions

[priority] <= int(threshold_var) + 1
[created_date] > datetime.now() - timedelta(days=int(lookback_days))

Worked Examples

Records from the Last 30 Days

[created_date] > datetime.now() - timedelta(days=30)

The formula computes a date 30 days before the current time.

Dynamic Priority Threshold

[priority] <= int(max_priority_threshold)

Where max_priority_threshold is a procedure variable (e.g., "2"). The int() function ensures it's compared as a number.

Records in an Active Category List

[category] in active_categories

Where active_categories is a list variable populated by a previous step (e.g., ["hardware", "software", "network"]).

Computed String Match

[short_description] contains search_term.lower()

The right side computes a lowercase version of the search_term variable.

Dates and Datetimes in Filters

When comparing against date or datetime fields, always use the date() or datetime() constructors. PB needs proper date objects to translate them into the source system's native format (SQL date literals, ServiceNow date encoding, etc.).

Correct:

[sys_created_on] > datetime.now() - timedelta(days=30)
[sys_created_on] > datetime(2024, 1, 1)
[opened_at] > date.today() - timedelta(days=90)

Incorrect:

[sys_created_on] > '2024-01-01'

Raw date strings will not be translated correctly and may cause errors or return no results.

Notes

  • The formula expression is evaluated once before the query is sent to the source system — not per record
  • If the formula references a variable that doesn't exist, the filter will produce an error at execution time
  • All Formula Language features are available on the right side: functions, builtins, string methods, comprehensions, conditionals, etc.
  • The left side (field name) is always a source field, written in square brackets — you cannot use formulas on the left side

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk