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
}

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"
}

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.

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"
    }
  ]
}