feat: ✨ Decommissioning Job

examples/backbone_design/designs/core_site/designs/0001_design.yaml.j2

@@ -1,4 +1,8 @@
 ---
+regions:
+  - "!update:name": "{{ region.name }}"
+    description: "new description for testing"
+
 sites:
   - name: "{{ site_name }}"
     region__slug: "{{ region.slug }}"
@@ -51,6 +55,15 @@ racks:
           status__name: "Reserved"
 {% endmacro %}
 
+{% macro device_edit(device_name) -%}
+  - "!update:name": "{{ device_name }}"
+    local_context_data: {
+      "snmp-location": "some-cool-place",
+    }
+
+{% endmacro %}
+
 devices:
   {{ device("core01", "rack1", core_1_loopback) }}
   {{ device("core02", "rack2", core_2_loopback) }}
+  {{ device_edit("core02.iad5") }}

nautobot_design_builder/__init__.py

@@ -33,5 +33,11 @@ def context_repository(cls):
         """Retrieve the Git Repository slug that has been configured for the Design Builder."""
         return settings.PLUGINS_CONFIG[cls.name]["context_repository"]
 
+    # pylint: disable=no-self-argument
+    @classproperty
+    def pre_decommission_hook(cls) -> str:
+        """Retrieve the pre decommission hook callable for the Design Builder, if configured."""
+        return settings.PLUGINS_CONFIG[cls.name].get("pre_decommission_hook", "")
+
 
 config = DesignBuilderConfig  # pylint:disable=invalid-name

nautobot_design_builder/jobs.py

@@ -0,0 +1,166 @@
+"""Generic Design Builder Jobs."""
+from django.contrib.contenttypes.models import ContentType
+from django.utils.module_loading import import_string
+
+from nautobot.extras.models import Status
+from nautobot.extras.jobs import Job, MultiObjectVar
+
+from nautobot_design_builder import DesignBuilderConfig
+from nautobot_design_builder.models import DesignInstance, JournalEntry
+from nautobot_design_builder.choices import DesignInstanceStatusChoices
+
+
+class DesignInstanceDecommissioning(Job):
+    """Job to decommission Design Instances."""
+
+    design_instances = MultiObjectVar(
+        model=DesignInstance,
+        query_params={"status": "active"},
+        description="Design Instances to decommission.",
+    )
+
+    class Meta:  # pylint: disable=too-few-public-methods
+        """Meta class."""
+
+        name = "Decommission Design Instances."
+        description = """Job to decommission one or many Design Instances from Nautobot."""
+
+    def _proceed_after_pre_decommission_hook(self, design_instance):
+        """If configured, run a pre decomission hook.
+
+        It should return True if it's good to go, or False and the reason of the failure.
+        """
+        pre_decommission_hook = DesignBuilderConfig.pre_decommission_hook
+        if not pre_decommission_hook:
+            return True
+
+        self.log_info(
+            f"Checking if the design instance {design_instance} can be decommissioned by external dependencies."
+        )
+
+        try:
+            func = import_string(pre_decommission_hook)
+        except ImportError as error:
+            msg = (
+                "There was an issue attempting to import the pre decommission hook "
+                f"{pre_decommission_hook}, this is expected with a local configuration issue and not related to"
+                " the Design Builder App, please contact your system admin for further details.\n"
+            )
+            raise ValueError(msg + str(error)) from error
+
+        result, reason = func(design_instance)
+
+        if not result:
+            self.log_failure(f"The pre hook validation failed due to: {reason}")
+            return False
+
+        self.log_success(f"No dependency issues found for {design_instance}.")
+        return True
+
+    def _process_journal_entry_with_full_control(self, journal_entry):
+        """It takes care of decommission changes for objects with full control.
+
+        Returns True if the decommissioning was successful.
+        """
+        other_journal_entries = (
+            JournalEntry.objects.filter(_design_object_id=journal_entry.design_object.id)
+            .exclude(id=journal_entry.id)
+            .exclude(journal__design_instance__status__name=DesignInstanceStatusChoices.DECOMMISSIONED)
+        )
+
+        if other_journal_entries:
+            self.log_failure(
+                journal_entry.design_object,
+                message=(
+                    "This object is referenced by other active Journals: ",
+                    f"{list(other_journal_entries.values_list('id', flat=True))}",
+                ),
+            )
+            return False
+
+        journal_entry.design_object.delete()
+
+        self.log_success(obj=journal_entry.design_object, message=f"Object {journal_entry.design_object} removed.")
+
+        return True
+
+    def _process_journal_entry_without_full_control(self, journal_entry):
+        """It takes care of decommission changes for objects without full control.
+
+        Returns True if the decommissioning was successful.
+        """
+        for attribute in journal_entry.changes["differences"].get("added", {}):
+            value_changed = journal_entry.changes["differences"]["added"][attribute]
+            old_value = journal_entry.changes["differences"]["removed"][attribute]
+            if isinstance(value_changed, dict):
+                # If the value is a dictionary (e.g., config context), we only update the
+                # keys changed, honouring the current value of the attribute
+                current_value = getattr(journal_entry.design_object, attribute)
+                keys_to_remove = []
+                for key in current_value:
+                    if key in value_changed:
+                        if old_value:
+                            current_value = old_value[key]
+                        else:
+                            keys_to_remove.append(key)
+                for key in keys_to_remove:
+                    del current_value[key]
+                setattr(journal_entry.design_object, attribute, current_value)
+            else:
+                setattr(journal_entry.design_object, attribute, old_value)
+
+            journal_entry.design_object.save()
+
+        self.log_success(
+            obj=journal_entry.design_object,
+            message="Because full control is not given, we have restored the object to its previous state.",
+        )
+
+        return True
+
+    def run(self, data, commit):
+        """Execute job."""
+        design_instances = data["design_instances"]
+        self.log_info(
+            message=f"Starting decommissioning of design instances: {', '.join([instance.name for instance in design_instances])}",
+        )
+
+        found_cross_references = False
+
+        for design_instance in design_instances:
+            if not self._proceed_after_pre_decommission_hook(design_instance):
+                self.log_warning(design_instance, message="Dependency issues found to this Design Instance.")
+                continue
+
+            self.log_info(obj=design_instance, message="Working on resetting objects for this Design Instance...")
+
+            # TODO: When update mode is available, this should cover the journals stacked
+            latest_journal = design_instance.journal_set.order_by("created").last()
+            self.log_info(latest_journal, "Journal to be decommissioned.")
+
+            for journal_entry in latest_journal.entries.exclude(_design_object_id=None).order_by("-last_updated"):
+                self.log_debug(f"Decommissioning changes for {journal_entry.design_object}.")
+
+                if journal_entry.full_control:
+                    # With full control, we can delete the design_object is there are no active references by other Journals
+                    if not self._process_journal_entry_with_full_control(journal_entry):
+                        found_cross_references = True
+                else:
+                    # If we don't have full control, we recover the value of the items changed to the previous value
+                    self._process_journal_entry_without_full_control(journal_entry)
+
+            content_type = ContentType.objects.get_for_model(DesignInstance)
+            design_instance.status = Status.objects.get(
+                content_types=content_type, name=DesignInstanceStatusChoices.DECOMMISSIONED
+            )
+            design_instance.save()
+
+            if found_cross_references:
+                raise ValueError(
+                    "Because of cross-references between design instances, decommissioning has been cancelled."
+                )
+
+            self.log_success(f"{design_instance} has been successfully decommissioned from Nautobot.")
+
+
+jobs = (DesignInstanceDecommissioning,)

nautobot_design_builder/tables.py

@@ -19,7 +19,7 @@ class DesignTable(BaseTable):
 
     job = Column(linkify=True)
     name = Column(linkify=True)
-    instance_count = Column(accessor=Accessor("instance_count"), verbose_name="Instances")
+    instance_count = Column(linkify=True, accessor=Accessor("instance_count"), verbose_name="Instances")
     actions = ButtonsColumn(Design, buttons=("changelog",), prepend_template=DESIGNTABLE)
 
     class Meta(BaseTable.Meta):  # pylint: disable=too-few-public-methods
@@ -29,6 +29,13 @@ class Meta(BaseTable.Meta):  # pylint: disable=too-few-public-methods
         fields = ("name", "job", "instance_count")
 
 
+DESIGNINSTANCETABLE = """
+<a href="{% url "extras:job" class_path="plugins/nautobot_design_builder.jobs/DesignInstanceDecommissioning" %}?design_instances={{record.pk}}" class="btn btn-xs btn-primary" title="Decommission">
+    <i class="mdi mdi-delete-sweep"></i>
+</a>
+"""
+
+
 class DesignInstanceTable(StatusTableMixin, BaseTable):
     """Table for list view."""
 
@@ -41,6 +48,7 @@ class DesignInstanceTable(StatusTableMixin, BaseTable):
             "delete",
             "changelog",
         ),
+        prepend_template=DESIGNINSTANCETABLE,
     )
 
     class Meta(BaseTable.Meta):  # pylint: disable=too-few-public-methods