Conditions and Comparisons

A condition decides whether a rule fires. Conditions go in the when block, between when and then. Most conditions are comparisons — checking a field against a value, or against another field.

when
  order.subtotal > 100.0
then
  set order.custom.is_high_value to true
end

Reads as: when the order’s subtotal is greater than 100.0, set the custom is_high_value field to true.

The operator you use depends on the type of the field — text fields compare differently than numbers, which compare differently than dates.

Numbers

order.subtotal > 100.0
order_line.qty_ordered = 1
order_line.qty_ordered <= 5

Heads up: BGL uses <> for “not equal”, not !=. And it uses = for equality, not ==.

Text

order.status is "pending"
order.shipping_address.country is_not "MX"
order.id starts_with "EXT-"
order.notes contains "fragile"

For pattern matching with matches, see Strings and Regex.

Dates

order.ordered_at > @2024-01-01
order.shipped_at = @today
order.ordered_at is_on @monday
order.ordered_at is_in @december

For date literals (@now, @today, @2024-01-15, etc.) and date arithmetic, see Dates and Times.

Booleans

order_line.gift_wrap
not order_line.gift_wrap
order_line.gift_wrap = true

A boolean field on its own (order_line.gift_wrap) is true if the field is true. Negate with not.

Comparing two fields

The right-hand side doesn’t have to be a literal — you can compare against another field, or any expression.

order.shipping_address.country is order.billing_address.country
order.subtotal > order.discount_amount * 2
order_line.qty_fulfilled < order_line.qty_ordered

Always-true and always-false

when true then ... end       # always runs
when false then ... end      # never runs (but valid syntax)

If you just want actions to run on every record, you don’t need a when at all — a top-level set (or any other statement) outside any when block runs unconditionally. See Structure of a Rule. Use when true only when you want to nest other statements inside the THEN block.

Type mismatches

If you compare a text field to a number, the rule won’t run — BGL checks types when the rule is saved and surfaces an error. To compare across types, cast first:

when order.custom.qty as number > 10 then ... end

See Data Types for casting.

Combining conditions

Most rules check more than one thing. Use and, or, and not — see Logical Operators.

when
  order.subtotal > 100.0
  and order.shipping_address.country is "US"
  and order has none order_lines with (order_line.gift_wrap)
then
  ...
end

What about checking a list?

To ask “do any line items have SKU starting with PREMIUM?” — you don’t compare against a list directly. You use a quantifier:

when
  order has any order_lines with (order_line.sku starts_with "PREMIUM-")
then
  ...
end

See Quantifiers for any, all, and none.