Documentation and error handling/logging fixes (#289)

* fixes typos in 3.0 changelog
* improves error handling for git repositories providing command mappers
* fix log message
* undo f-string to use best practices for log formatting
---------
Co-authored-by: Jeff Kala <[email protected]>

changes/289.added

@@ -0,0 +1 @@
+- Added additional error handling/logging to the git repository sync method

changes/289.fixed

@@ -0,0 +1,2 @@
+- Fixed typos in the 3.0 changelog
+- Fixed a logging typo in an adapter

docs/admin/release_notes/version_3.0.md

@@ -1,7 +1,7 @@
 # v3.0 Release Notes
 
 !!! warning
-    Nautobot Device Onboarding v2.0.0-2.0.2 contains a vulnerability where the credentials used to log into a device may be visible in clear text on the Job Results page under the Additional Data tab. It is recommended to review all OnbaordingTasks from the affected releases, delete any affeccted JobResults, and upgrade to v3.0.0. For more information please see the full write up on the issue which is available as [a security advisory](https://github.com/nautobot/nautobot-app-device-onboarding/security/advisories/GHSA-qf3c-rw9f-jh7v) on the repo. Nautobot Device Onboarding app versions v2.0.0-2.0.2 have been removed for PyPI to ensure all gaps are closed. v2.0.3 is published with disabled functionality and banner message encouraging to upgrade to v3.0.0. [CVE-2023-48700](https://www.cve.org/CVERecord?id=CVE-2023-48700) has been issued for this vulnerability.
+    Nautobot Device Onboarding v2.0.0-2.0.2 contains a vulnerability where the credentials used to log into a device may be visible in clear text on the Job Results page under the Additional Data tab. It is recommended to review all OnboardingTasks from the affected releases, delete any affected JobResults, and upgrade to v3.0.0. For more information please see the full write up on the issue which is available as [a security advisory](https://github.com/nautobot/nautobot-app-device-onboarding/security/advisories/GHSA-qf3c-rw9f-jh7v) on the repo. Nautobot Device Onboarding app versions v2.0.0-2.0.2 have been removed for PyPI to ensure all gaps are closed. v2.0.3 is published with disabled functionality and banner message encouraging to upgrade to v3.0.0. [CVE-2023-48700](https://www.cve.org/CVERecord?id=CVE-2023-48700) has been issued for this vulnerability.
 
 ## Release Overview
 

nautobot_device_onboarding/constants.py

@@ -48,3 +48,9 @@
     "FastEthernet": "100base-fx",
     "ethernet": "1000base-t",
 }
+
+# The git repository data source content identifier for custom command mappers.
+ONBOARDING_COMMAND_MAPPERS_CONTENT_IDENTIFIER = "nautobot_device_onboarding.onboarding_command_mappers"
+
+# The git repository data source folder name for custom command mappers.
+ONBOARDING_COMMAND_MAPPERS_REPOSITORY_FOLDER = "onboarding_command_mappers"

nautobot_device_onboarding/datasources.py

@@ -1,23 +1,52 @@
 """Datasources to override command_mapper yaml files."""
 
+from pathlib import Path
+
 from nautobot.apps.datasources import DatasourceContent
 from nautobot.extras.choices import LogLevelChoices
 
+from nautobot_device_onboarding.constants import (
+    ONBOARDING_COMMAND_MAPPERS_CONTENT_IDENTIFIER,
+    ONBOARDING_COMMAND_MAPPERS_REPOSITORY_FOLDER,
+)
+
 
 def refresh_git_command_mappers(repository_record, job_result, delete=False):  # pylint: disable=unused-argument
     """Callback for gitrepository updates on Command Mapper Repo."""
+    # Since we don't create any DB records we can just ignore deletions.
+    if delete:
+        return
+    if ONBOARDING_COMMAND_MAPPERS_CONTENT_IDENTIFIER not in repository_record.provided_contents:
+        return
     job_result.log(
-        "Successfully Pulled Command Mapper Repo",
-        level_choice=LogLevelChoices.LOG_DEBUG,
+        "Refreshing network sync job command mappers...",
+        level_choice=LogLevelChoices.LOG_INFO,
     )
+    repo_data_dir = Path(repository_record.filesystem_path) / ONBOARDING_COMMAND_MAPPERS_REPOSITORY_FOLDER
+    if not repo_data_dir.exists():
+        job_result.log(
+            "Command mapper repo folder does not exist. "  # pylint: disable=consider-using-f-string
+            "Create a sub folder in the repository at %s" % repo_data_dir,
+            repository_record,
+            level_choice=LogLevelChoices.LOG_WARNING,
+        )
+        return
+    try:
+        next(repo_data_dir.glob("*.yml"))
+    except StopIteration:
+        job_result.log(
+            "Command mapper repo folder found, but it doesn't contain any command mapper files. "
+            "They need to have the '.yml' extension.",
+            level_choice=LogLevelChoices.LOG_WARNING,
+        )
 
 
 datasource_contents = [
     (
         "extras.gitrepository",
         DatasourceContent(
             name="Network Sync Job Command Mappers",
-            content_identifier="nautobot_device_onboarding.onboarding_command_mappers",
+            content_identifier=ONBOARDING_COMMAND_MAPPERS_CONTENT_IDENTIFIER,
             icon="mdi-paw",
             callback=refresh_git_command_mappers,
         ),

nautobot_device_onboarding/nornir_plays/transform.py

@@ -5,6 +5,11 @@
 import yaml
 from nautobot.extras.models import GitRepository
 
+from nautobot_device_onboarding.constants import (
+    ONBOARDING_COMMAND_MAPPERS_CONTENT_IDENTIFIER,
+    ONBOARDING_COMMAND_MAPPERS_REPOSITORY_FOLDER,
+)
+
 DATA_DIR = os.path.abspath(os.path.join(os.path.dirname(os.path.dirname(__file__)), "command_mappers"))
 
 
@@ -17,7 +22,7 @@ def get_git_repo():
         == 1
     ):
         repository_record = GitRepository.objects.filter(
-            provided_contents__contains="nautobot_device_onboarding.onboarding_command_mappers"
+            provided_contents=[ONBOARDING_COMMAND_MAPPERS_CONTENT_IDENTIFIER]
         ).first()
         return repository_record
     return None
@@ -40,7 +45,7 @@ def add_platform_parsing_info():
     """Merges platform command mapper from repo or defaults."""
     repository_record = get_git_repo()
     if repository_record:
-        repo_data_dir = os.path.join(repository_record.filesystem_path, "onboarding_command_mappers")
+        repo_data_dir = os.path.join(repository_record.filesystem_path, ONBOARDING_COMMAND_MAPPERS_REPOSITORY_FOLDER)
         command_mappers_repo_path = load_command_mappers_from_dir(repo_data_dir)
     else:
         command_mappers_repo_path = {}

nautobot_device_onboarding/tests/test_transform.py

@@ -11,6 +11,7 @@
 from nautobot.extras.choices import JobResultStatusChoices
 from nautobot.extras.models import GitRepository, JobResult
 
+from nautobot_device_onboarding.constants import ONBOARDING_COMMAND_MAPPERS_CONTENT_IDENTIFIER
 from nautobot_device_onboarding.nornir_plays.transform import add_platform_parsing_info, load_command_mappers_from_dir
 
 MOCK_DIR = os.path.join("nautobot_device_onboarding", "tests", "mock")
@@ -56,7 +57,7 @@ def setUp(self):
             name="Test Git Repository",
             slug=self.repo_slug,
             remote_url="http://localhost/git.git",
-            provided_contents=["nautobot_device_onboarding.onboarding_command_mappers"],
+            provided_contents=[ONBOARDING_COMMAND_MAPPERS_CONTENT_IDENTIFIER],
         )
         self.repo.save()
         self.job_result = JobResult.objects.create(name=self.repo.name)
@@ -81,7 +82,7 @@ def populate_repo(self, path, url, *args, **kwargs):
 
     def test_git_repo_was_created(self, MockGitRepo):  # pylint:disable=invalid-name
         repo_count = GitRepository.objects.filter(
-            provided_contents=["nautobot_device_onboarding.onboarding_command_mappers"]
+            provided_contents=[ONBOARDING_COMMAND_MAPPERS_CONTENT_IDENTIFIER]
         ).count()
         self.assertEqual(1, repo_count)