Skip to content

Table Rules

A Rule is a set of conditions and actions that define how to create or update dynamic attributes. Each rule can have its own filters, attribute mappings, and value transformations. Rules are processed in order, and the first matching rule will be applied to the device.

There must be at least one rule defined for the integration to run.

A Table Rule is a rule that queries an IP Fabric table using the API to set the value of a dynamic attribute. These are defined in the rules section of the configuration file. Each rule must have a unique name and have an attribute and value set unless configured in the default section.

Table Rule Example
rules:
  - name: Loopback0  # Required unique name for the rule
    overwrite: null  # Defaults to null which acts as False, set to true to overwrite existing attributes
                     # Setting to a boolean value will prevent merging with the default rule
    merge_default_filters: true  # Default true
    merge_default_device_filters: true  # Default true
    merge_default_attribute_filters: true  # Default true
    delete_attribute: null  # Defaults to None; Read more about delete_attribute in the Delete Attribute section
    filters:
      - value: ^(Lo0|loopback0)$
        operator: ireg
        column: intName
    filter_string: null  # Filter string cannot be used with filters, attribute_filters, or device_filters
    attribute_filters: null
    device_filters: null
    attribute: null
    value:
      api_endpoint: null
      column: null
      static: null
      regex: null
      transform: null
      mapping: {}
      null_value: null
      sort: null
      sn_column: null  # Defaults to 'sn' if not set

Default Table Rule

A Default Table Rule is applied to all devices unless overridden by a specific table rule or disabled using the merge_default_* variable.

Default Table Rule Example
default:  # Applies to all rules except inventory unless overridden or flagged not to merge
  attribute: MGMT_IP
  overwrite: true  # Defaults to null, setting to a boolean value will propagate to all rules
  delete_attribute: null  # Defaults to None, can be set to true to delete the attribute if not matched
  attribute_filters: # Disable by setting merge_default_attribute_filters to false in rules
    - key: siteName
      value: HWLAB
      operator: eq
  filters:  # Disable by setting merge_default_filters to false in rules
    - column: primaryIp
      value: false
      operator: empty
  device_filters: &device_filters  # Disable by setting merge_default_device_filters to false in rules
    - column: vendor
      value: aws|azure|gcp
      operator: nreg
  value:  # Default value for all rules if not set in the rule itself
    api_endpoint: tables/inventory/interfaces
    column: primaryIp
    static: null
    regex: null
    transform: null
    mapping: {}
    null_value: null
    sort: null
    sn_column: null  # Defaults to 'sn' if not set

Merging Rules with Default

Printing the merged rule can be accomplished by using sync.config.model_dump_merged() method:

Exporting Merged Rule Example
import yaml
from ipf_dynamic_attributes import AttributeSync

sync = AttributeSync(config="mgmt-ip.yml")
print(yaml.dump(sync.config.model_dump_merged(), default_flow_style=False))

The merged rules are the result of combining the default rule with the specific rules defined in the configuration. Using the two examples above we get the following merged rule:

Merged Table Rule Example
rules:
  - name: Loopback0
    merge_default_filters: true
    merge_default_device_filters: true
    merge_default_attribute_filters: true
    delete_attribute: null
    overwrite: true
    filters:
      - value: ^(Lo0|loopback0)$
        operator: ireg
        column: intName
      - column: primaryIp
        value: false
        operator: empty
    filter_string: null
    attribute_filters:
      - key: siteName
        value: HWLAB
        operator: eq
    attribute: MGMT_IP
    value:
      api_endpoint: tables/inventory/interfaces
      column: primaryIp
    device_filters:
      - column: vendor
        value: aws|azure|gcp
        operator: nreg
    inventory: null  # Used Internally Only for merging multiple configuration files

This creates the following filter for the tables/inventory/interfaces API endpoint:

Merged Filter Example
{
    "and": [{
            "intName": ["ireg", "^(Lo0|loopback0)$"]
        }, {
            "primaryIp": ["empty", false]
        }, {
            "device.attributes": ["siteName", "eq", "HWLAB"]
        }, {
            "device.vendor": ["nreg", "aws|azure|gcp"]
        }
    ]
}
merge_default_filters: false
{
    "and": [{
            "intName": ["ireg", "^(Lo0|loopback0)$"]
        }, {
            "device.attributes": ["siteName", "eq", "HWLAB"]
        }, {
            "device.vendor": ["nreg", "aws|azure|gcp"]
        }
    ]
}
merge_default_device_filters: false
{
    "and": [{
            "intName": ["ireg", "^(Lo0|loopback0)$"]
        }, {
            "primaryIp": ["empty", false]
        }, {
            "device.attributes": ["siteName", "eq", "HWLAB"]
        }
    ]
}
merge_default_attribute_filters: false
{
    "and": [{
            "intName": ["ireg", "^(Lo0|loopback0)$"]
        }, {
            "primaryIp": ["empty", false]
        }, {
            "device.vendor": ["nreg", "aws|azure|gcp"]
        }
    ]
}

Filtering

Filters can be used in combination with attribute_filters and device_filters. Using this method creates an “and” filter query. For more complex queries, the filter_string can be used which is a JSON string that is passed directly to the IP Fabric API. This is easily found in the IP Fabric UI Table Description.

Table Description Example

Using the Table Description it is also possible to find the available columns and their supported operators (i.e. eq, reg, etc.).

Attribute filters (IP Fabric version 7.2) and Device filters (IP Fabric version 7.0) provide even more flexibility in filtering table endpoints. Please note these are not available in all tables and it is best to check the IP Fabric UI to ensure these are available in the table you are using.

Attribute & Device Filters

Attribute Value

The rule value is the value that will be set for the attribute. This either comes from data in the IP Fabric API or is a static value.

Column

The column is the name of the column in the API endpoint that will be used to set the value.

Table Column Example
rules:
  - name: Loopback0
    attribute: MGMT_IP
    overwrite: true
    value:
      api_endpoint: tables/inventory/interfaces  # Required API endpoint to query for the value
      column: primaryIp
      static: null
      regex: null
      transform: null
      mapping: {}
      null_value: null
      sort: null

In this example the value of the primaryIp column in the tables/inventory/interfaces API endpoint will be used as the MGMT_IP attribute value. The first match will be used and if other matches are found they will be ignored.

Sorting

The sort key is used to sort the values returned from the API. This is useful when there are multiple values in the table.

Table Sorting Example
rules:
  - name: Loopback0
    attribute: MGMT_IP
    value:
      api_endpoint: tables/inventory/interfaces
      column: primaryIp
      sort:
        column: intName
        order: asc  # or desc

Static

Static values will be used as is if the device sn is found in the API query.

Static values can only be combined with column if a regex is provided.

Static Value Example
rules:
  - name: HWLAB
    attribute: REGION
    overwrite: true
    filters:
      - column: siteName
        value: HWLAB
        operator: eq
    value:
      api_endpoint: tables/inventory/devices
      static: EMEA

This example searches the inventory table for devices in the HWLAB site and sets the REGION attribute to EMEA.

Null Value

The null_value key is used to set the attribute if the IP Fabric API returns a null value. This is useful when a default value is required to be set.

Since the value gets assigned to the attribute further rules or matches will not be processed. This means that the table needs to be properly filtered or sorted or this should be defined in the last rule processed for a “catch-all” to apply a default attribute value (i.e. REGION=unknown).

Null Value Example
rules:
  - name: Assign Cloud Region
    attribute: CLOUD_REGION
    overwrite: true
    value:
      api_endpoint: tables/cloud/nodes/inventory
      column: location
      null_value: GLOBAL

In this example the CLOUD_REGION attribute is set to GLOBAL if the API returns null for the location column.

Mapping

The mapping key is used to map values from the IP Fabric API to the attribute value.

Mapping Example
rules:
  - name: Azure
    attribute: REGION
    overwrite: true
    value:
      api_endpoint: tables/cloud/vendors/azure/inventory
      column: location
      null_value: CLOUD
      transform: lower
      default_mapping_value: UNKNOWN  # Optional, used if no mapping is found
      mapping:
        southafricanorth: EMEA
        southafricawest: EMEA

In this example the location column (which is transformed to lowercase) from the tables/cloud/nodes/inventory API endpoint is then looked up in the mapping dictionary to find the correct REGION value. This example also combines:

  • null_value value to set if the API returns a null value (setting a mapping null: CLOUD is not supported).
  • default_mapping_value value to set a default value if no mapping is found (mapping any_value: UNKNOWN).

Regex

The regex key is used to extract a value from the IP Fabric API using a regular expression. The pattern key is the regular expression pattern to match and the group key is the group number to extract. The transform key is used to transform the value before regex processing.

Regex Example
rules:
  - name: AWS
    attribute: REGION
    overwrite: true
    value:
      static: null  # Not used in this example, but can be set to a static value if the regex matches instead of a group
      api_endpoint: tables/cloud/vendors/aws/inventory
      column: region
      transform: upper
      regex:
        pattern: ^(\w\w)-  # Example: us-
        group: 1
        flags:
          - IGNORECASE
      null_value: CLOUD
      default_mapping_value: UNKNOWN  # Optional, used if no mapping is found
      mapping:
        US: NAMR
        CA: NAMR

In this example the REGION attribute is set using this logic:

  1. The region column from the tables/cloud/vendors/aws/inventory API endpoint is collected (us-east-1).
  2. If the value is null, the null_value key is used to set the attribute to CLOUD.
  3. If the value is set it is transformed to uppercase (US-EAST-1).
    1. Showing as an example, not necessary in this case since re.IGNORECASE is also set.
  4. Apply the regex ((US)-).
    1. Group 0 = US-.
    2. Group 1 = US.
  5. If a match is found and the static value was set then it would use the static value as the attribute value instead of a grouping.
    1. In this case, the static value is not set so it will continue to the next step.
  6. If no match is found or the group is out of range then the null_value is used to set the attribute to CLOUD.
  7. If a match and group is found then the value is looked up in the mapping dictionary (US = NAMR).
  8. If no mapping is found then the default_mapping_value is used to set the attribute to UNKNOWN.