netbox/docs/reference/conditions.md

Conditions

Conditions are NetBox's mechanism for evaluating whether a set data meets a prescribed set of conditions. It allows the author to convey simple logic by declaring an arbitrary number of attribute-value-operation tuples nested within a hierarchy of logical AND and OR statements.

Conditions

A condition is expressed as a JSON object with the following keys:

Key name	Required	Default	Description
attr	Yes	-	Name of the key within the data being evaluated
value	See note	-	The reference value to which the given data will be compared. Not used by snapshot operators (changed, unchanged).
op	No	eq	The logical operation to be performed
negate	No	False	Negate (invert) the result of the condition's evaluation

Available Operations

• eq: Equals
• gt: Greater than
• gte: Greater than or equal to
• lt: Less than
• lte: Less than or equal to
• in: Is present within a list of values
• contains: Contains the specified value
• regex: Matches a regular expression
• changed: The attribute's value differs between the pre-change and post-change snapshots (no value required)
• unchanged: The attribute's value is the same in both snapshots (no value required)

Accessing Nested Keys

To access nested keys, use dots to denote the path to the desired attribute. For example, assume the following data:

{
  "a": {
    "b": {
      "c": 123
    }
  }
}

The following condition will evaluate as true:

{
  "attr": "a.b.c",
  "value": 123
}

Examples

name equals "foo":

{
  "attr": "name",
  "value": "foo"
}

name does not equal "foo"

{
  "attr": "name",
  "value": "foo",
  "negate": true
}

asn is greater than 65000:

{
  "attr": "asn",
  "value": 65000,
  "op": "gt"
}

status is not "planned" or "staging":

{
  "attr": "status.value",
  "value": ["planned", "staging"],
  "op": "in",
  "negate": true
}

!!! note "Evaluating static choice fields"

Pay close attention when evaluating static choice fields, such as the `status` field above. These fields typically render as a dictionary specifying both the field's raw value (`value`) and its human-friendly label (`label`). Be sure to specify on which of these you want to match.

Snapshot Conditions (Event Rules)

When used in an event rule, conditions can also inspect the pre-change and post-change snapshots captured at the time of the event. This allows rules to fire only when a specific field actually changes value, rather than whenever it has a particular value.

Snapshot Operators

The changed and unchanged operators compare an attribute's value across the two snapshots. They do not accept a value key.

Fire only when status changes (to any value):

{
  "attr": "status",
  "op": "changed"
}

Combining with Standard Conditions

The canonical use case — fire only when status changes to active — combines a standard value check with the changed operator:

{
  "and": [
    {
      "attr": "status.value",
      "value": "active"
    },
    {
      "attr": "status",
      "op": "changed"
    }
  ]
}

Direct Snapshot Path Access

You can also read pre- or post-change values directly using the snapshots.prechange.<attr> and snapshots.postchange.<attr> dot-path syntax with any standard operator:

{
  "attr": "snapshots.prechange.status",
  "value": "planned"
}

!!! warning "Snapshot serialization format"

Snapshot data uses the **model serializer format**, not the REST API format. Choice fields such as `status` are stored as raw strings (e.g. `"active"`) rather than nested objects (e.g. `{"value": "active", "label": "Active"}`). Use `attr: "snapshots.prechange.status"` — not `"snapshots.prechange.status.value"` — when referencing snapshot attributes. The `changed`/`unchanged` operators compare the same format on both sides, so they are not affected by this distinction.

!!! note "Snapshot availability"

Snapshots are only populated for update and delete events. For create events, `prechange` is `null` — conditions using the `changed` operator on a create event evaluate to `true` (the field transitioned from non-existent to its initial value), while conditions using `snapshots.prechange.*` paths evaluate to `false`. For delete events, `postchange` is `null` — the `changed` operator evaluates to `true` for any attribute present in the prechange snapshot, and `unchanged` evaluates to `false`.

Condition Sets

Multiple conditions can be combined into nested sets using AND or OR logic. This is done by declaring a JSON object with a single key (and or or) containing a list of condition objects and/or child condition sets.

Examples

status is "active" and primary_ip4 is defined or the "exempt" tag is applied.

{
  "or": [
    {
      "and": [
        {
          "attr": "status.value",
          "value": "active"
        },
        {
          "attr": "primary_ip4",
          "value": null,
          "negate": true
        }
      ]
    },
    {
      "attr": "tags.slug",
      "value": "exempt",
      "op": "contains"
    }
  ]
}