Filters

Filters allow you to control which data is retrieved from IP Fabric during synchronization. By associating filters with Endpoints and Syncs, you can limit the scope of data collection to specific devices, networks, or other criteria. The plugin uses a two-tier filtering system consisting of Filters and Filter Expressions to provide flexibility in defining complex query conditions.

Understanding the Filtering System

The filtering system is designed to mirror IP Fabric’s native filtering capabilities, allowing you to apply the same filters you use in the IP Fabric UI to your NetBox synchronization process. Since some filters can be used on multiple endpoints, the filters is designed with reusability of filter expressions in mind.

How Filters Work

During a sync, the plugin:

Identifies which Endpoints need to be queried based on enabled Sync parameters.
For each endpoint, retrieves all associated Filters that are linked to this Sync.
Merges all Filter Expressions from those Filters according to their Filter Type (AND/OR).
Combines the merged filters with any site filters from the Sync configuration.
Uses the final combined filter when querying the IP Fabric API.

This hierarchical approach allows you to create reusable filter components and combine them in different ways for different synchronization scenarios.

Filters

A Filter is a container that groups one or more Filter Expressions together and defines how they should be combined (using AND/OR logic). Filters can be associated with multiple endpoints and syncs, making them reusable across your synchronization configuration.

Parameters

Field	Description	Type
Name	Unique name for the filter (e.g., “Production Sites Only”)	`CharField`
Description	Optional description explaining the filter’s purpose	`TextField`
Endpoints	IP Fabric endpoints this filter applies to	`ManyToMany`
Filter Type	How to combine expressions: AND/OR	`ChoiceField`
Syncs	Sync jobs that should use this filter	`ManyToMany`
Expressions	Filter Expression objects that define the actual filter conditions	`ManyToMany`

Filter Types

AND: All filter expressions must match. Use this for restrictive filtering where all conditions must be met.
OR: At least one filter expression must match. Use this for inclusive filtering where any condition can satisfy the filter.

Creating a Filter

To create a filter, navigate to Plugins → IP Fabric → Filters → + Add.

Provide a descriptive Name and optional Description.
Select the Endpoints this filter should apply to.
Choose the Filter Type (AND or OR).
Optionally associate the filter with specific Syncs.
Add Filter Expressions that define the actual filtering logic.

Best Practice

Create focused filters that target specific endpoints or use cases. For example, create separate filters for “Core Routers” and “Cisco Devices” rather than combining all filtering logic into a single filter. This makes filters more reusable and easier to maintain.

Filter Combination

When multiple filters are associated with the same endpoint and sync, they are combined on the endpoint model. The combination process:

Groups all filter expressions by their filter type (AND/OR).
Recursively merges expressions with matching nested structures.
Adds any site-specific filters from the sync parameters.
Returns a final filter object that is sent to the IP Fabric API.

When filters have the same nested structure (matching and/or keys at the same level), they are intelligently merged. For example, if you have:

Filter A (AND type) with expression {"or": [{"hostname": ["like", "router1"]}]}
Filter B (AND type) with expression {"or": [{"hostname": ["like", "router2"]}]}
Filter C (OR type) with expression {"vendor": ["eq", "cisco"]}

The final combined filter sent to IP Fabric would be:

{
  "or": [
    {"vendor": ["eq", "cisco"]}
  ],
  "and": [
    {
      "or": [
        {"hostname": ["like", "router1"]},
        {"hostname": ["like", "router2"]}
      ]
    }
  ]
}

Note how filters A and B were merged into a single or array because they had the same nested structure, while filter C remained separate as it has a different filter type.

Filter Expressions

Filter Expressions contain the actual JSON filter criteria that will be sent to the IP Fabric API. These expressions use the same format as IP Fabric’s native filtering system, specifically the Advanced Filtering format, which can be captured directly from the IP Fabric UI.

IP Fabric Advanced Filtering

Filter expressions in NetBox use the exact same format as IP Fabric’s Advanced Filter feature. In IP Fabric, filters are defined by groups and rules, where each group can contain one or more rules or nested groups with logical operators (AND/OR).

For detailed information about how filtering rules work in IP Fabric, see the Advanced Filtering documentation.

For complete filter specifications and available filter fields for each endpoint, refer to IP Fabric’s API documentation in RapiDoc. You can access RapiDoc by following the instructions in the Accessing RapiDoc section of the IP Fabric documentation. Each endpoint has its own set of available filters documented in the API specification.

Parameters

Field	Description	Type
Name	Unique name for the expression (e.g., “Site1 Devices”)	`CharField`
Description	Optional description of what the expression filters	`TextField`
Expression	JSON filter expression in IP Fabric format	`JSONField`
Filters	Filter objects that use this expression	`ManyToMany`

Creating a Filter Expression

To create a filter expression, navigate to Plugins → IP Fabric → Filter Expressions → + Add.

Obtaining Filter JSON from IP Fabric

The easiest and most accurate way to create filter expressions is to capture them directly from IP Fabric:

Open IP Fabric in your browser and navigate to any table view.
In IP Fabric, click Advanced Filter to open the filtering interface.
Define your filter using groups and rules with the desired logical operators (AND/OR).
Apply the filter to the table.
Open the Table Description item under the 3-dots menu in the top right corner of the table.
Find and copy the filters object value from the request body.
Paste the value (example below) into the Expression field in NetBox.

[
  {
    "hostname": [
      "eq",
      "s4xsw01"
    ]
  },
  {
    "vendor": [
      "eq",
      "arista"
    ]
  }
]

Table Description

The Table Description dialog shows the exact API request that IP Fabric uses to fetch the filtered data. The filters object contains the filter structure that IP Fabric uses internally, ensuring compatibility and correctness when used in NetBox.

Expression Format

Filter expressions must be a JSON array of filter conditions. Each condition is a dictionary with field names as keys and arrays as values. Number of items in the array can be up to 4 but the most common is [operator, value].

Common Operators:

eq - Equals
neq - Not equals
ieq - Equals (case-insensitive)
nieq - Not equals (case-insensitive)
like - Contains
notlike - Not contains
reg - Regex
nreg - Negative regex
ireg - Regex (case-insensitive)
nireg - Negative regex (case-insensitive)
empty - Is empty (uses True as value or False if not empty)

Available Filter Fields:

The available filter fields depend on the specific endpoint being queried. Each IP Fabric endpoint has its own set of filterable fields. To find the complete list of available filters for a specific endpoint:

Access IP Fabric’s RapiDoc API documentation (see Accessing RapiDoc).
Navigate to the endpoint you want to filter (e.g., /tables/inventory/devices).
Review the filter schema documentation for that endpoint.
Use the field names from the API specification in your filter expressions.

Common filterable fields across endpoints include: siteName, hostname, vendor, family, model, sn (serial number), intName (interface name), but each endpoint has its own specific set of available filters.

Example Expressions:

Simple hostname filter:

[{"hostname": ["eq", "ROUTER-01"]}]

Hostname pattern matching:

[{"hostname": ["regex", "router.*"]}]

Multiple conditions:

[
  {"hostname": ["empty", false]},
  {"vendor": ["eq", "cisco"]}
]

Complex nested filter:

[
  {
    "or": [
      {"vendor": ["eq", "cisco"]},
      {"vendor": ["eq", "juniper"]}
    ]
  }
]

Testing Filter Expressions

The Filter Expression form includes built-in testing capabilities to verify your expressions work correctly before using them in a sync.

When editing a filter expression:

The Test Source field automatically populates if the expression is associated with filters that have a common source.
The Test Endpoint field automatically populates if the expression is associated with filters that target a single endpoint.
Click the Test button to query IP Fabric using your expression.
Review the results to confirm the filter returns the expected data.

Note

Testing sends real request to your IP Fabric instance. It must be reachable from NetBox for this feature to work.

Viewing Filter Details

To view filter details, navigate to Plugins → IP Fabric → Filters and select a filter. The detail page displays:

Filter name, description, and type
Linked endpoints, expressions and syncs

Relationships with Other Models

Endpoints

Filters have a many-to-many relationship with Endpoints. You can associate a filter with multiple endpoints if the same filtering logic applies across different data sources. When an endpoint is queried during a sync, all filters associated with that endpoint are combined into the final query.

Syncs

Filters can be associated with specific Syncs through a many-to-many relationship. This allows you to apply different filtering rules to different synchronization jobs. For example, you might have one sync that filters for production sites only, and another that includes all sites.

When a sync runs, it only uses filters that are explicitly associated with that sync job.

Filter Expressions

Filters contain one or more Filter Expressions through a many-to-many relationship. This allows you to:

Reuse common filter expressions across multiple filters.
Build complex filtering logic by combining simple expressions.
Maintain a library of reusable filter components.

Use Cases and Examples

Filtering by Hostname Pattern

Create a filter to synchronize only devices matching a naming convention:

Filter Expression:

[
  {
    "or": [
      {"hostname": ["like", "core-"]},
      {"hostname": ["like", "dist-"]},
      {"hostname": ["like", "access-"]}
    ]
  }
]

Associate this with the device endpoint and create similar expression replacing hostname with device.hostname for interface and IP address endpoints to limit all synchronized data to devices matching these patterns.

Filtering by Device Type

Create a filter to synchronize only routers and switches:

Filter Expression:

[
  {
    "or": [
      {"family": ["eq", "switch"]},
      {"family": ["eq", "router"]}
    ]
  }
]

Filtering by Vendor

Create a filter for specific vendors:

Filter Expression:

[
  {
    "or": [
      {"vendor": ["eq", "cisco"]},
      {"vendor": ["eq", "juniper"]}
    ]
  }
]

Filtering by VLAN ID

Create a filter to synchronize specific VLANs:

Filter Expression:

[
  {
    "or": [
      {"vlanId": ["eq", "100"]},
      {"vlanId": ["eq", "200"]}
    ]
  }
]

Filtering by VRF

Create a filter to synchronize specific VRFs:

Filter Expression:

[{"vrf": ["like", "PROD-"]}]

Combining Multiple Conditions

Create a filter for Cisco routers in production VRFs using AND logic:

Filter Expression 1 - Vendor:

[{"vendor": ["eq", "cisco"]}]

Filter Expression 2 - VRF:

[{"vrf": ["reg", "PROD-.*"]}]

Filter Expression 3 - Device Type:

[{"family": ["eq", "router"]}]

Create a Filter with type “AND” and add all three expressions. This ensures only Cisco routers in production VRFs are synchronized.

Best Practices

Use Descriptive Names: Name your filters and expressions clearly to indicate their purpose (e.g., “Core Routers Only”, “Production VLANs”).
Test Before Use: Always test filter expressions using the built-in test functionality before associating them with a sync.
Keep Expressions Simple: Create focused filter expressions that do one thing well, then combine them using filters for complex logic.
Reuse Components: Build a library of reusable filter expressions that can be mixed and matched across different filters.
Document Complex Filters: Use the description field to explain complex filtering logic, especially when combining multiple expressions.
Capture from IP Fabric: Rather than manually writing filter JSON, capture it from IP Fabric’s UI to ensure correct syntax.
Consider Performance: Overly broad filters may retrieve large amounts of data. Use specific filtering criteria to improve sync performance.