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.
rules:
- name: Loopback0 # Required unique name for the 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: # Applies to all rules except inventory unless overridden or flagged not to merge
attribute: MGMT_IP
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:
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:
rules:
- name: Loopback0
merge_default_filters: true
merge_default_device_filters: true
merge_default_attribute_filters: true
delete_attribute: null
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
This creates the following filter for the tables/inventory/interfaces
API endpoint:
{
"and": [{
"intName": ["ireg", "^(Lo0|loopback0)$"]
}, {
"primaryIp": ["empty", false]
}, {
"device.attributes": ["siteName", "eq", "HWLAB"]
}, {
"device.vendor": ["nreg", "aws|azure|gcp"]
}
]
}
{
"and": [{
"intName": ["ireg", "^(Lo0|loopback0)$"]
}, {
"device.attributes": ["siteName", "eq", "HWLAB"]
}, {
"device.vendor": ["nreg", "aws|azure|gcp"]
}
]
}
{
"and": [{
"intName": ["ireg", "^(Lo0|loopback0)$"]
}, {
"primaryIp": ["empty", false]
}, {
"device.attributes": ["siteName", "eq", "HWLAB"]
}
]
}
{
"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.
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 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.
rules:
- name: Loopback0
attribute: MGMT_IP
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.
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.
rules:
- name: HWLAB
attribute: REGION
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 to null 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
).
rules:
- name: Assign Cloud Region
attribute: CLOUD_REGION
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.
rules:
- name: Azure
attribute: REGION
value:
api_endpoint: tables/cloud/vendors/azure/inventory
column: location
null_value: CLOUD
transform: lower
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 the
null_value
key to set if the API returns a null value (setting a mapping null: CLOUD
is not supported).
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.
rules:
- name: AWS
attribute: REGION
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
mapping:
US: NAMR
CA: NAMR
In this example the REGION
attribute is set using this logic:
- The
region
column from thetables/cloud/vendors/aws/inventory
API endpoint is collected (us-east-1
). - If the value is null, the
null_value
key is used to set the attribute toCLOUD
. - If the value is set it is transformed to uppercase (
US-EAST-1
).- Showing as an example, not necessary in this case since
re.IGNORECASE
is also set.
- Showing as an example, not necessary in this case since
- Apply the regex (
(US)-
).- Group 0 =
US-
. - Group 1 =
US
.
- Group 0 =
- 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.- In this case, the
static
value is not set so it will continue to the next step.
- In this case, the
- If no match is found or the group is out of range then the
null_value
is used to set the attribute toCLOUD
. - If a match and group is found then the value is looked up in the mapping dictionary (
US = NAMR
).