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:

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
}

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

An attribute which resolves in neither snapshot — a misspelling, an attribute the object type does not have, or an event which recorded no snapshots at all — leaves nothing to compare. The condition fails closed (the rule does not fire) and an error is logged to netbox.event_rules. This holds regardless of negate: negating a condition whose attribute cannot be resolved does not turn it into a match.

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

Because an absent snapshot resolves to null rather than raising an error — matching a condition testing for null and failing any other comparison, whichever operator is used — a snapshot path can be combined safely with other conditions in a rule that also fires on create or delete. For example, this rule fires when a site is created, or when a site whose status was previously planned is updated:

{
  "or": [
    {
      "attr": "snapshots.prechange.status",
      "value": null
    },
    {
      "attr": "snapshots.prechange.status",
      "value": "planned"
    }
  ]
}

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