Structure of a Rule

Karl Falconer · Updated May 01, 2026 19:11

Every BGL rule has the same skeleton. Once you can read this skeleton, you can read every rule in DropStream.

rule "Name of the rule"
  statement
  statement
  ...
end

The outer rule "..." ... end wraps the whole thing. Inside is a list of statements that run top-to-bottom. A statement can be:

A simple action like set X to Y that runs unconditionally.
A when ... then ... end block — actions that only run if a condition is true.
A for ... end loop over a collection.
An accumulate ... end block.

A rule needs at least one statement. There’s no requirement for a when block — if you want to set a field on every record, a top-level set is enough.

A simple example — no condition

rule "Set shipping method"
  set order.shipping_carrier_name to "UPS"
  set order.shipping_carrier_service_level to "Ground"
end

Reads as: for the rule called “Set shipping method”, set the order’s shipping carrier name to “UPS” and the service level to “Ground” — on every record this rule sees.

A conditional example — with `when`

rule "Apply free shipping for high-value orders"
  when
    order.subtotal > 100.0
  then
    set order.shipping_amount to 0.0
  end
end

Reads as: for the rule called “Apply free shipping…”, when the order’s subtotal is over $100, set the shipping amount to zero. Any record where the condition isn’t true is left alone.

The parts

Part	Purpose
`rule "Name"`	Opens the rule. The name is in double quotes and must not contain double quotes.
`when condition`	Opens a conditional block. The condition is a logical expression — see Conditions and Comparisons.
`then action`	Begins the actions that run when the condition is true.
`end`	Closes the most recently opened block — either a `when ... then`, a `for`, an `accumulate`, or the outer `rule`.

Every rule, when ... then, for, and accumulate you open must be closed with a matching end. Indenting consistently makes it easy to see which end closes which.

Multiple `when` blocks

A rule can have several when blocks, and they all run in order, top to bottom. Every block whose condition matches will execute.

rule "Tag and route premium orders"
  when
    order.subtotal > 500.0
  then
    set order.custom.tag to "premium"
  end

  when
    order.subtotal > 500.0
    and order.shipping_address.country is "US"
  then
    set order.custom.region to "us-premium"
  end
end

Both blocks check order.subtotal > 500.0, so for a US premium order both run: the tag gets set and the region field gets set too.

Rule options

You can place options between the rule line and the first when:

Option	What it does
`active`	The rule is on (default).
`inactive`	The rule is off. Useful when you want to keep a rule but not run it. The same as setting the rule’s status to Inactive in the UI.
`debug`	Enables verbose logging when the rule runs.
`timezone "..."`	Sets the timezone for date operations. Example: `timezone "Eastern Time (US & Canada)"`.

rule "Holiday hold"
  inactive
  timezone "Eastern Time (US & Canada)"

  when
    order.ordered_at is_in @december
  then
    hold order until 1D after @now
  end
end

Comments

Anything after a # on a line is a comment. There are no block comments — only single-line.

# This rule applies a 10% discount to wholesale orders.
rule "Wholesale discount"
  when
    order.custom.tier is "wholesale"  # tier is set by an earlier rule
  then
    set order.discount_amount to order.subtotal * 0.10
  end
end

Where to go next

Write the condition. Conditions and Comparisons covers the operators you can use in a when block.
Write the action. Setting Values covers the most common action — set X to Y. The full list of actions is in the Action Reference.
Combine conditions. Logical Operators covers and, or, not.