nautobot-workflow-engine 1.0.1__tar.gz

nautobot_workflow_engine-1.0.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: nautobot-workflow-engine
+Version: 1.0.1
+Summary: Workflow Engine
+Keywords: nautobot,nautobot-app,nautobot-plugin
+Author: Eric Fetty
+Requires-Python: >=3.10,<3.14
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: all
+Requires-Dist: jinja2 (>=3.1)
+Requires-Dist: nautobot (>=3.0.0,<4.0.0)
+Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: requests (>=2.31)
+Description-Content-Type: text/markdown
+
+# Nautobot Workflow Engine
+
+Define automation in YAML, synchronize it through Nautobot's repository integration,
+and launch it from dynamic forms. Execute Python scripts in Nautobot or job templates
+in AWX, with ordered actions, reusable results, scheduling, and run history.
+
+## Capabilities
+
+- Typed inputs, Nautobot object lookups, dependent choices, conditional visibility,
+  validation, and tabular CSV input.
+- Pre-actions, main actions, and post-actions in definition order.
+- Reusable Python helpers and repository-backed Jinja filters.
+- Immediate or scheduled runs, including optional ServiceNow change windows.
+- Execution logs, AWX job monitoring, reporting, and estimated time savings.
+
+## Get Started
+
+The current package requires **Nautobot 3.x** and **Python 3.10 through 3.13**. The
+selected Nautobot release must also support that Python version. These are package
+requirements, not a claim that every combination has been tested.
+
+1. Follow [installation and configuration](docs/admin/install.md) using an approved
+   package in your Nautobot deployment.
+2. Configure a trusted workflow source and synchronize its Workflow Engine content.
+3. Run the non-destructive [hostname tutorial](docs/user/app_getting_started.md).
+4. Use the [authoring reference](docs/user/app_use_cases.md) to add inputs and actions.
+
+AWX and ServiceNow are optional. Individual workflows may require additional apps,
+Python packages, inventory, or service permissions. Examples are starting points for
+review and adaptation, not production-ready deployment definitions.
+
+## Documentation
+
+- [Overview](docs/user/app_overview.md) and [documentation home](docs/index.md).
+- [Workflow authoring](docs/user/app_use_cases.md) and [custom filters](docs/dev/extending.md).
+- [AWX and ServiceNow](docs/user/external_interactions.md).
+- [Compatibility](docs/admin/compatibility_matrix.md), [upgrades](docs/admin/upgrade.md),
+  and [release notes](docs/admin/release_notes/index.md).
+- [Security and data handling](docs/admin/security.md).
+
+## Examples
+
+The [custom-filter workflow](examples/workflows/custom-filter-demo.yaml) uses
+[an echo script](examples/scripts/echo_hostname.py) and shared helpers without changing
+inventory. Other examples illustrate inventory operations and optional vendor
+integrations. Review their model, script, and service dependencies before use.
+
+## Trust and Execution Logs
+
+Workflow scripts and filters are trusted code running inside Nautobot, not sandboxed
+submissions. Limit who can modify their source and who can launch or inspect runs.
+Detailed script execution logging is intentional. Treat inputs, results, output,
+diagnostics, and backups as operational data; do not submit or print credentials.
+
+## Contributing
+
+Read the [contribution guide](docs/dev/contributing.md),
+[development environment guide](docs/dev/dev_environment.md), and
+[architecture overview](docs/dev/arch_decision.md). Keep changes focused, use synthetic
+fixtures, preserve migrations, and include regression coverage for behavioral changes.
+
+## Publication Status
+
+Open-source preparation is in progress. Apache-2.0 is the intended license, subject
+to copyright-owner approval and a provenance review. No project-wide license grant
+is asserted here until those steps are complete. A private vulnerability-reporting
+contact and final artifact validation are also required before public release.

nautobot_workflow_engine-1.0.1/README.md

@@ -0,0 +1,67 @@
+# Nautobot Workflow Engine
+
+Define automation in YAML, synchronize it through Nautobot's repository integration,
+and launch it from dynamic forms. Execute Python scripts in Nautobot or job templates
+in AWX, with ordered actions, reusable results, scheduling, and run history.
+
+## Capabilities
+
+- Typed inputs, Nautobot object lookups, dependent choices, conditional visibility,
+  validation, and tabular CSV input.
+- Pre-actions, main actions, and post-actions in definition order.
+- Reusable Python helpers and repository-backed Jinja filters.
+- Immediate or scheduled runs, including optional ServiceNow change windows.
+- Execution logs, AWX job monitoring, reporting, and estimated time savings.
+
+## Get Started
+
+The current package requires **Nautobot 3.x** and **Python 3.10 through 3.13**. The
+selected Nautobot release must also support that Python version. These are package
+requirements, not a claim that every combination has been tested.
+
+1. Follow [installation and configuration](docs/admin/install.md) using an approved
+   package in your Nautobot deployment.
+2. Configure a trusted workflow source and synchronize its Workflow Engine content.
+3. Run the non-destructive [hostname tutorial](docs/user/app_getting_started.md).
+4. Use the [authoring reference](docs/user/app_use_cases.md) to add inputs and actions.
+
+AWX and ServiceNow are optional. Individual workflows may require additional apps,
+Python packages, inventory, or service permissions. Examples are starting points for
+review and adaptation, not production-ready deployment definitions.
+
+## Documentation
+
+- [Overview](docs/user/app_overview.md) and [documentation home](docs/index.md).
+- [Workflow authoring](docs/user/app_use_cases.md) and [custom filters](docs/dev/extending.md).
+- [AWX and ServiceNow](docs/user/external_interactions.md).
+- [Compatibility](docs/admin/compatibility_matrix.md), [upgrades](docs/admin/upgrade.md),
+  and [release notes](docs/admin/release_notes/index.md).
+- [Security and data handling](docs/admin/security.md).
+
+## Examples
+
+The [custom-filter workflow](examples/workflows/custom-filter-demo.yaml) uses
+[an echo script](examples/scripts/echo_hostname.py) and shared helpers without changing
+inventory. Other examples illustrate inventory operations and optional vendor
+integrations. Review their model, script, and service dependencies before use.
+
+## Trust and Execution Logs
+
+Workflow scripts and filters are trusted code running inside Nautobot, not sandboxed
+submissions. Limit who can modify their source and who can launch or inspect runs.
+Detailed script execution logging is intentional. Treat inputs, results, output,
+diagnostics, and backups as operational data; do not submit or print credentials.
+
+## Contributing
+
+Read the [contribution guide](docs/dev/contributing.md),
+[development environment guide](docs/dev/dev_environment.md), and
+[architecture overview](docs/dev/arch_decision.md). Keep changes focused, use synthetic
+fixtures, preserve migrations, and include regression coverage for behavioral changes.
+
+## Publication Status
+
+Open-source preparation is in progress. Apache-2.0 is the intended license, subject
+to copyright-owner approval and a provenance review. No project-wide license grant
+is asserted here until those steps are complete. A private vulnerability-reporting
+contact and final artifact validation are also required before public release.

nautobot_workflow_engine-1.0.1/nautobot_workflow_engine/__init__.py

@@ -0,0 +1,35 @@
+"""App declaration for nautobot_workflow_engine."""
+
+# Metadata is inherited from Nautobot. If not including Nautobot in the environment, this should be added
+import os
+from importlib import metadata
+
+from nautobot.apps import NautobotAppConfig
+
+__version__ = metadata.version(__name__)
+
+
+class WorkflowEngineConfig(NautobotAppConfig):
+    """App configuration for the nautobot_workflow_engine app."""
+
+    name = "nautobot_workflow_engine"
+    verbose_name = "Workflow Engine"
+    version = __version__
+    author = "Eric Fetty"
+    description = "General-purpose workflow engine for Nautobot"
+    base_url = "workflow-engine"
+    required_settings = []
+    default_settings = {
+        "awx_external_integration_name": "AWX",
+        "workflow_dir": "workflows",
+        "filters_dir": "filters",
+        "awx_poll_seconds": 5,
+        "show_disabled": False,
+        "show_add_new_item": os.getenv("SHOW_ADD_NEW_ITEM", "").split(","),
+    }
+    caching_config = {}
+    docs_view_name = "plugins:nautobot_workflow_engine:docs"
+    searchable_models = ["workflow"]
+
+
+config = WorkflowEngineConfig  # pylint:disable=invalid-name

nautobot_workflow_engine-1.0.1/nautobot_workflow_engine/app-config-schema.json

@@ -0,0 +1,31 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+        "awx_external_integration_name": {
+            "type": "string",
+            "default": "AWX"
+        },
+        "workflow_dir": {
+            "type": "string",
+            "default": "workflows"
+        },
+        "filters_dir": {
+            "type": "string",
+            "default": "filters"
+        },
+        "awx_poll_seconds": {
+            "type": "integer",
+            "default": 5
+        },
+        "show_disabled": {
+            "type": "boolean",
+            "default": false
+        },
+        "show_add_new_item": {
+            "type": "array",
+            "default": []
+        }
+    },
+    "additionalProperties": false
+}

nautobot_workflow_engine-1.0.1/nautobot_workflow_engine/datasources.py

@@ -0,0 +1,257 @@
+"""Git repository sync functionality for workflows."""
+
+import re
+from pathlib import Path
+
+import yaml
+from django.conf import settings
+from django.contrib.contenttypes.models import ContentType
+from nautobot.apps.datasources import DatasourceContent
+from nautobot.extras.models import GitRepository
+
+from .executors import clear_repo_script_cache, validate_repo_filter_modules
+from .models import Workflow, WorkflowAction, WorkflowFilterModule, WorkflowHelper, WorkflowInput
+
+PLUGIN_CFG = settings.PLUGINS_CONFIG.get("nautobot_workflow_engine", {})
+
+
+def _process_includes(job_result, file_handler):
+    """Process any includes in the content."""
+    content = file_handler.read_text(encoding="utf-8")
+    include_pattern = re.compile(r"""^\s*{%\s*include\s+[\"'](?P<path>[\w\/\.\-]+)[\"']\s*%}""")
+    for line in content.splitlines():
+        match = include_pattern.search(line)
+        if match:
+            # Load the template path from the match
+            template_path = match.group("path")
+            template_file = file_handler.parent / template_path
+            if template_file.exists():
+                # If the template file exists, read its content and replace the include
+                template_content = template_file.read_text(encoding="utf-8")
+                content = content.replace(line, template_content)
+            else:
+                # If the template file doesn't exist, log a warning
+                job_result.log(f"Template file not found: {template_file}")
+
+    return content
+
+
+def _get_action_list(data, *keys):
+    """Return first non-empty action list for any provided YAML key alias."""
+    for key in keys:
+        value = data.get(key)
+        if value is None:
+            continue
+        if isinstance(value, list):
+            return value
+        # Be forgiving if user accidentally provides an empty scalar/object.
+        return []
+    return []
+
+
+def _is_filter_module_path(relative_path):
+    """Return True when the repository-relative path is inside the configured filters directory."""
+    filters_dir = Path(PLUGIN_CFG.get("filters_dir", "filters"))
+    filters_parts = filters_dir.parts
+    rel_parts = relative_path.parts
+    return len(rel_parts) >= len(filters_parts) and rel_parts[: len(filters_parts)] == filters_parts
+
+
+def _sync_repo_python_modules(repository_record, repo_path, job_result):
+    """Store repository Python modules in helper or filter-module models."""
+    WorkflowHelper.objects.filter(source_repo=repository_record).delete()
+    WorkflowFilterModule.objects.filter(source_repo=repository_record).delete()
+
+    for py_file in repo_path.rglob("*.py"):
+        if "__pycache__" in str(py_file) or py_file.name.startswith("."):
+            continue
+
+        relative_path = py_file.relative_to(repo_path)
+        model = WorkflowFilterModule if _is_filter_module_path(relative_path) else WorkflowHelper
+        model.objects.create(
+            source_repo=repository_record,
+            file_path=str(relative_path),
+            content=py_file.read_text(encoding="utf-8"),
+        )
+
+        if model is WorkflowFilterModule:
+            job_result.log(message=f"Stored filter module: {relative_path}")
+        else:
+            job_result.log(message=f"Stored Python file: {relative_path}")
+
+
+def sync_workflows_from_repo(repository_record: GitRepository, job_result, delete=False):
+    """Sync workflow definitions and helper files from a Git repository."""
+    repo_path = Path(repository_record.filesystem_path)
+    wf_dir = PLUGIN_CFG["workflow_dir"]
+    workflows_path = repo_path / wf_dir
+    if not workflows_path.exists():
+        clear_repo_script_cache(repository_record)
+        return
+
+    # Track workflows found in this sync
+    synced_workflow_keys = set()
+
+    _sync_repo_python_modules(repository_record, repo_path, job_result)
+    validate_repo_filter_modules(repository_record)
+
+    for yml in sorted(list(workflows_path.glob("*.y*ml"))):
+        content = _process_includes(job_result, yml)
+        data = yaml.safe_load(content)
+
+        # Track this workflow key
+        workflow_key = data.get("key")
+        if workflow_key:
+            synced_workflow_keys.add(workflow_key)
+
+        # Check if workflow is explicitly disabled in YAML
+        yaml_enabled = data.get("enabled", True)
+
+        wf, _ = Workflow.objects.update_or_create(
+            key=data["key"],
+            defaults={
+                "name": data.get("name", data["key"]),
+                "description": data.get("description", ""),
+                "category": data.get("category", ""),
+                "enabled": yaml_enabled,  # Use enabled flag from YAML
+                "manual_duration_minutes": data.get("manual_duration_minutes"),
+                "raw_definition": data,
+                "source_repo": repository_record,
+            },
+        )
+        wf.inputs.all().delete()
+        for order, ip in enumerate(data.get("inputs", []), start=1):
+            ct = None
+            if ip.get("type") in ("object", "multiobject") and ip.get("model"):
+                app_label, model = ip["model"].split(".")
+                try:
+                    ct = ContentType.objects.get(app_label=app_label, model=model.lower())
+                except ContentType.DoesNotExist:
+                    raise ValueError(f"[Workflow {wf.key}] Invalid model for input {ip['key']}: {ip['model']}")
+
+            # Normalize validators:
+            # - support either a single "regex" (with optional message/flags near root)
+            # - or a list under "validators", e.g. [{"regex": "...", "flags": ["IGNORECASE"], "message": "..."}]
+            validators = ip.get("validators")
+            if not validators:
+                if "regex" in ip:
+                    v = {"regex": ip.get("regex")}
+                    if "message" in ip:
+                        v["message"] = ip["message"]
+                    if "flags" in ip:
+                        v["flags"] = ip["flags"]
+                    validators = [v]
+
+            WorkflowInput.objects.create(
+                workflow=wf,
+                key=ip["key"],
+                label=ip.get("label", ip["key"]),
+                input_type=ip["type"],
+                content_type=ct,
+                required=ip.get("required", False),
+                default=ip.get("default"),
+                depends_on=ip.get("depends_on", []),
+                filter_query=ip.get("filter", {}).get("query"),
+                choices=ip.get("choices"),
+                columns=ip.get("columns"),
+                visible_when=ip.get("show_if"),
+                validators=validators,
+                order=order,
+            )
+        # Use bulk deletion to avoid get_absolute_url issues
+        WorkflowAction.objects.filter(workflow=wf).delete()
+
+        phased_actions = [
+            ("pre", _get_action_list(data, "pre_actions", "pre-actions", "before_actions", "before-actions")),
+            # backwards-compatible existing key
+            ("main", _get_action_list(data, "actions", "main_actions", "main-actions")),
+            ("post", _get_action_list(data, "post_actions", "post-actions", "after_actions", "after-actions")),
+        ]
+
+        for phase, actions in phased_actions:
+            for order, act in enumerate(actions, start=1):
+
+                if act.get("type") == "nautobot":
+                    script_path = (act.get("script") or "").lstrip("/")
+                    if not script_path:
+                        raise ValueError(f"[Workflow {wf.key}] 'script' is required for nautobot actions")
+
+                    # Verify the script exists in WorkflowHelper
+                    if not WorkflowHelper.objects.filter(source_repo=repository_record, file_path=script_path).exists():
+                        raise ValueError(f"[Workflow {wf.key}] Script not found in repository: {script_path}")
+
+                    WorkflowAction.objects.create(
+                        workflow=wf,
+                        phase=phase,
+                        order=order,
+                        action_type="nautobot",
+                        name=act.get("name", "nautobot"),
+                        when=act.get("when", ""),
+                        script_path="/" + script_path,
+                        with_vars=act.get("with", {}),
+                    )
+
+                elif act.get("type") == "awx":
+                    WorkflowAction.objects.create(
+                        workflow=wf,
+                        phase=phase,
+                        order=order,
+                        action_type="awx",
+                        name=act.get("name", "awx"),
+                        when=act.get("when", ""),
+                        awx_template_id=act.get("template_id"),
+                        awx_extra_vars=act.get("extra_vars", {}),
+                        monitor=act.get("monitor", True),
+                    )
+
+                else:
+                    raise ValueError(
+                        f"[Workflow {wf.key}] Unsupported action type in phase '{phase}': {act.get('type')}"
+                    )
+
+    # Disable workflows that are no longer in the repository (instead of deleting)
+    if delete:
+        workflows_to_disable = Workflow.objects.filter(
+            source_repo=repository_record,
+            enabled=True,  # Only disable currently enabled workflows
+        ).exclude(key__in=synced_workflow_keys)
+
+        disabled_count = 0
+
+        for workflow in workflows_to_disable:
+            # Count related objects for logging
+            action_count = workflow.actions.count()
+            input_count = workflow.inputs.count()
+            run_count = workflow.runs.count()
+
+            job_result.log(
+                message=f"Disabling workflow '{workflow.name}' (key: {workflow.key}) "
+                f"with {action_count} actions, {input_count} inputs, {run_count} runs - no longer in repository"
+            )
+
+            # Disable instead of delete to preserve history
+            workflow.enabled = False
+            workflow.save()
+            disabled_count += 1
+
+        if disabled_count > 0:
+            job_result.log(
+                message=f"Disabled {disabled_count} workflows no longer present in repository. Run history preserved."
+            )
+
+    clear_repo_script_cache(repository_record)
+
+
+datasource_contents = []
+
+datasource_contents.append(
+    (
+        "extras.gitrepository",
+        DatasourceContent(
+            name="workflows",
+            content_identifier="nautobot_workflow_engine.workflows",
+            icon="mdi-file-document-outline",
+            callback=sync_workflows_from_repo,
+        ),
+    )
+)