Update documention and tests for custom field attributes

Author: Johan van den Dorpe

changes/205.fixed

@@ -0,0 +1 @@
+Added support for validating custom fields by referencing them as cf_<custom_field_name> in ComplianceError exceptions

docs/user/app_data_compliance.md

@@ -2,9 +2,9 @@
 
 ## Overview
 
-The Data Compliance feature audits any object within Nautobot according to a set of rules that you can define programmatically or from the built-in data validation rules (e.g. Min/Max, Regex, Required, or Unique rules). Rather than only checking for adherence to specified rules during the *creation or modification* of objects, Data Compliance will run a job that produces compliance statuses across *existing* objects (such as all pre-existing devices). 
+The Data Compliance feature audits any object within Nautobot according to a set of rules that you can define programmatically or from the built-in data validation rules (e.g. Min/Max, Regex, Required, or Unique rules). Rather than only checking for adherence to specified rules during the *creation or modification* of objects, Data Compliance will run a job that produces compliance statuses across *existing* objects (such as all pre-existing devices).
 
-This is ideal for implementing some kind of business logic or standardization requirement into Nautobot after data is already populated within the platform. Data Compliance will allow you to identify valid or invalid existing objects based on your specified data compliance and validation rules. Additionally, Data Compliance enables the ability to implement more complex rules using the full power of programming logic, in addition to the built-in data validation ones. 
+This is ideal for implementing some kind of business logic or standardization requirement into Nautobot after data is already populated within the platform. Data Compliance will allow you to identify valid or invalid existing objects based on your specified data compliance and validation rules. Additionally, Data Compliance enables the ability to implement more complex rules using the full power of programming logic, in addition to the built-in data validation ones.
 
 ### `DataComplianceRule` Class
 
@@ -15,9 +15,12 @@ The `DataComplianceRule` class takes advantage of the `CustomValidator` workflow
 Any `DataComplianceRule` class can have a `name` defined to provide a friendly name to be shown within in the UI. The `enforce` attribute can also be set to decide whether or not the `ComplianceError` caught in the `audit` method is raised again to the `clean` method, acting like a `ValidationError` wherever the original `full_clean` was called. Setting `enforce` to `True` changes the `DataComplianceRule` from a passive validation of data to an active enforcement of the logic within it.
 
 > **Note:** Individual rules implemented using the `DataComplianceRule` class are re-ran and re-validated when the target object is modified and saved, in addition to run ad-hoc using the `RunRegisteredDataComplianceRules` job. However, `DataCompliance` objects that are created by the job for the built-in validation rules when using the `Run built-in validation rules?` option will not update nor be re-validated until the job is explicitly ran once again.
-> 
+>
 > For example, if a user fixes an object attribute that was incompliant with a built-in rule and then navigates to its `Data Compliance` tab, the object will still show as invalid for that built-in rule. This will remain the case until the job is ran again with the `Run built-in validation rules?` option checked.
 
+!!! note
+    When raising a ComplianceError, the attribute must exist on the object. To raise errors for custom fields, use cf_custom_field_name as the attribute name.
+
 ## How to Use
 
 ### Step 1. Create Data Compliance Rules
@@ -52,7 +55,7 @@ class DesiredClassName(DataComplianceRule):
         # Your logic to determine if this function has succeeded or failed
         if "undesired_value" in self.context["object"].desired_attribute:
             raise ComplianceError({"desired_attribute": "Desired message why it's invalid."})
-    
+
     def audit(self):
         messages = {}
         for fn in [self.audit_desired_name_one, self.audit_desired_name_two]: # Add audit functions here
@@ -88,7 +91,7 @@ class DesiredClassName(DataComplianceRule):
         # Your logic to determine if this function has succeeded or failed
         if "undesired_value" in self.context["object"].desired_attribute:
             raise ComplianceError({"desired_attribute": "Desired message why it's invalid."})
-    
+
     def audit(self):
         messages = {}
         for fn in [self.audit_desired_name_one, self.audit_desired_name_two]: # Add audit functions here
@@ -136,12 +139,12 @@ from nautobot_data_validation_engine.custom_validators import DataComplianceRule
 class DeviceDataComplianceRules(DataComplianceRule):
     model = "dcim.device"
     enforce = False
-    
+
     # Checks if a device name contains any special characters other than a dash (-), underscore (_), or period (.) using regex
     def audit_device_name_chars(self):
         if not re.match("^[a-zA-Z0-9\-_.]+$", self.context["object"].name):
             raise ComplianceError({"name": "Device name contains unallowed special characters."})
-    
+
     def audit(self):
         messages = {}
         for fn in [self.audit_device_name_chars]:
@@ -155,12 +158,12 @@ class DeviceDataComplianceRules(DataComplianceRule):
 class RackDeviceComplianceRules(DataComplianceRule):
     model = "dcim.device"
     enforce = False
-    
+
     # Checks if a device is not assigned to a rack
     def audit_device_rack(self):
         if not self.context["object"].rack:
             raise ComplianceError({"rack": "Device should be assigned to a rack."})
-    
+
     def audit(self):
         messages = {}
         for fn in [self.audit_device_rack]:

nautobot_data_validation_engine/tests/test_data_compliance_rules.py

@@ -78,3 +78,34 @@ def test_validate_replaces_results(self):
             len(DataCompliance.objects.filter(compliance_class_name=TestFailedDataComplianceRule.__name__)),
             5,
         )
+
+    def test_custom_field_attribute_value(self):
+        # Simulate a Location with a custom field value
+        self.s.cf = {"foo": "bar"}
+        # Patch DataComplianceRule.context to include our instance
+        rule = TestPassedDataComplianceRule(self.s)
+        rule.context = {"object": self.s}
+
+        # Call _create_data_compliance_object with a custom field attribute
+        obj = rule._create_data_compliance_object(attribute="cf_foo", valid=True, message="msg")
+        self.assertEqual(obj.validated_attribute, "cf_foo")
+        self.assertEqual(obj.validated_attribute_value, "bar")
+
+    def test_custom_field_attribute_value_missing(self):
+        # Simulate a Location with no custom field value
+        self.s.cf = {}
+        rule = TestPassedDataComplianceRule(self.s)
+        rule.context = {"object": self.s}
+
+        obj = rule._create_data_compliance_object(attribute="cf_missing", valid=True, message="msg")
+        self.assertEqual(obj.validated_attribute, "cf_missing")
+        self.assertIsNone(obj.validated_attribute_value)
+
+    def test_regular_attribute_value(self):
+        # Test with a regular attribute
+        rule = TestPassedDataComplianceRule(self.s)
+        rule.context = {"object": self.s}
+
+        obj = rule._create_data_compliance_object(attribute="name", valid=True, message="msg")
+        self.assertEqual(obj.validated_attribute, "name")
+        self.assertEqual(obj.validated_attribute_value, self.s.name)