netbox-custom-widget 0.1.0__tar.gz

netbox_custom_widget-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

netbox_custom_widget-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: netbox-custom-widget
+Version: 0.1.0
+Summary: NetBox plugin for custom API dashboard widgets - call any API and display results
+Author-email: sieteunoseis <jeremy.worden@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/sieteunoseis/netbox-custom-widget
+Project-URL: Repository, https://github.com/sieteunoseis/netbox-custom-widget
+Project-URL: Issues, https://github.com/sieteunoseis/netbox-custom-widget/issues
+Keywords: netbox,netbox-plugin,dashboard,widget,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Dynamic: license-file
+
+# NetBox Custom Widget
+
+A NetBox plugin that provides configurable dashboard widgets for calling external APIs and displaying results. Similar to Homepage's Custom API widget.
+
+## Features
+
+- Call any HTTP API endpoint and display JSON results on your NetBox dashboard
+- Configurable field mappings with dot-notation for nested JSON access
+- Auto-refresh via HTMX at configurable intervals
+- Adaptive color coding for status values (e.g., UCCE process monitoring)
+- Pre-define endpoints in plugin configuration for automatic provisioning
+- Full CRUD interface for managing API endpoints
+
+## Installation
+
+```bash
+pip install netbox-custom-widget
+```
+
+Add to your NetBox configuration:
+
+```python
+PLUGINS = ['netbox_custom_widget']
+```
+
+## Configuration
+
+Define API endpoints in your `plugins.py`:
+
+```python
+PLUGINS_CONFIG = {
+    'netbox_custom_widget': {
+        'verify_ssl': False,
+        'endpoints': [
+            {
+                'name': 'My API Status',
+                'url': 'https://api.example.com/status',
+                'headers': {'Authorization': 'Bearer token123'},
+                'mappings': [
+                    {'field': 'status', 'label': 'Status', 'color': 'adaptive'},
+                    {'field': 'uptime', 'label': 'Uptime', 'suffix': 'hours'},
+                ],
+                'display_mode': 'list',
+                'refresh_interval': 30,
+            },
+        ],
+    }
+}
+```
+
+## Requirements
+
+- NetBox >= 4.0.0
+- Python >= 3.10

netbox_custom_widget-0.1.0/README.md

@@ -0,0 +1,54 @@
+# NetBox Custom Widget
+
+A NetBox plugin that provides configurable dashboard widgets for calling external APIs and displaying results. Similar to Homepage's Custom API widget.
+
+## Features
+
+- Call any HTTP API endpoint and display JSON results on your NetBox dashboard
+- Configurable field mappings with dot-notation for nested JSON access
+- Auto-refresh via HTMX at configurable intervals
+- Adaptive color coding for status values (e.g., UCCE process monitoring)
+- Pre-define endpoints in plugin configuration for automatic provisioning
+- Full CRUD interface for managing API endpoints
+
+## Installation
+
+```bash
+pip install netbox-custom-widget
+```
+
+Add to your NetBox configuration:
+
+```python
+PLUGINS = ['netbox_custom_widget']
+```
+
+## Configuration
+
+Define API endpoints in your `plugins.py`:
+
+```python
+PLUGINS_CONFIG = {
+    'netbox_custom_widget': {
+        'verify_ssl': False,
+        'endpoints': [
+            {
+                'name': 'My API Status',
+                'url': 'https://api.example.com/status',
+                'headers': {'Authorization': 'Bearer token123'},
+                'mappings': [
+                    {'field': 'status', 'label': 'Status', 'color': 'adaptive'},
+                    {'field': 'uptime', 'label': 'Uptime', 'suffix': 'hours'},
+                ],
+                'display_mode': 'list',
+                'refresh_interval': 30,
+            },
+        ],
+    }
+}
+```
+
+## Requirements
+
+- NetBox >= 4.0.0
+- Python >= 3.10

netbox_custom_widget-0.1.0/netbox_custom_widget/__init__.py

@@ -0,0 +1,93 @@
+"""
+NetBox Custom Widget Plugin
+
+Configurable dashboard widgets for calling external APIs and displaying results.
+"""
+
+import logging
+
+from django.conf import settings
+from django.db.models.signals import post_migrate
+from netbox.plugins import PluginConfig
+
+__version__ = "0.1.0"
+
+logger = logging.getLogger(__name__)
+
+
+def provision_endpoints(sender, **kwargs):
+    """Create or update CustomAPIEndpoint objects from plugin configuration."""
+    if sender.name != "netbox_custom_widget":
+        return
+
+    from django.db import OperationalError, ProgrammingError
+
+    try:
+        from .models import CustomAPIEndpoint
+
+        config = settings.PLUGINS_CONFIG.get("netbox_custom_widget", {})
+        endpoints_config = config.get("endpoints", [])
+        global_verify_ssl = config.get("verify_ssl", True)
+
+        for ep_config in endpoints_config:
+            name = ep_config.get("name")
+            if not name:
+                logger.warning("Skipping endpoint config without 'name'")
+                continue
+
+            defaults = {
+                "url": ep_config.get("url", ""),
+                "http_method": ep_config.get("http_method", "GET"),
+                "headers": ep_config.get("headers", {}),
+                "body": ep_config.get("body", ""),
+                "mappings": ep_config.get("mappings", []),
+                "display_mode": ep_config.get("display_mode", "list"),
+                "refresh_interval": ep_config.get("refresh_interval", 30),
+                "verify_ssl": ep_config.get("verify_ssl", global_verify_ssl),
+                "timeout": ep_config.get("timeout", 30),
+                "description": ep_config.get("description", ""),
+            }
+
+            obj, created = CustomAPIEndpoint.objects.update_or_create(
+                name=name,
+                defaults=defaults,
+            )
+
+            if created:
+                logger.info(f"Created API endpoint: {name}")
+            else:
+                logger.debug(f"Updated API endpoint: {name}")
+
+    except (OperationalError, ProgrammingError):
+        pass
+    except Exception as e:
+        logger.warning(f"Could not provision endpoints: {e}")
+
+
+class CustomWidgetConfig(PluginConfig):
+    """Plugin configuration for NetBox Custom Widget."""
+
+    name = "netbox_custom_widget"
+    verbose_name = "Custom Widget"
+    description = "Configurable dashboard widgets for calling external APIs"
+    version = __version__
+    author = "Jeremy Worden"
+    author_email = "jeremy.worden@gmail.com"
+    base_url = "custom-widget"
+    min_version = "4.0.0"
+
+    required_settings = []
+
+    default_settings = {
+        "verify_ssl": True,
+        "endpoints": [],
+    }
+
+    def ready(self):
+        """Register signal and import widgets."""
+        super().ready()
+        post_migrate.connect(provision_endpoints, sender=self)
+        from . import widgets  # noqa: F401
+
+
+config = CustomWidgetConfig

netbox_custom_widget-0.1.0/netbox_custom_widget/api/serializers.py

@@ -0,0 +1,40 @@
+"""API serializers for NetBox Custom Widget plugin."""
+
+from netbox.api.serializers import NetBoxModelSerializer
+from rest_framework import serializers
+
+from ..models import CustomAPIEndpoint
+
+
+class CustomAPIEndpointSerializer(NetBoxModelSerializer):
+    """Serializer for CustomAPIEndpoint."""
+
+    url = serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_custom_widget-api:customapiendpoint-detail"
+    )
+    endpoint_url = serializers.CharField(source="url", read_only=True)
+
+    class Meta:
+        model = CustomAPIEndpoint
+        fields = [
+            "id",
+            "url",
+            "display",
+            "name",
+            "endpoint_url",
+            "http_method",
+            "headers",
+            "body",
+            "mappings",
+            "display_mode",
+            "refresh_interval",
+            "verify_ssl",
+            "timeout",
+            "description",
+            "comments",
+            "tags",
+            "custom_fields",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ["id", "url", "display", "name"]

netbox_custom_widget-0.1.0/netbox_custom_widget/api/urls.py

@@ -0,0 +1,10 @@
+"""API URL configuration for NetBox Custom Widget plugin."""
+
+from netbox.api.routers import NetBoxRouter
+
+from . import views
+
+router = NetBoxRouter()
+router.register("endpoints", views.CustomAPIEndpointViewSet)
+
+urlpatterns = router.urls

netbox_custom_widget-0.1.0/netbox_custom_widget/api/views.py

@@ -0,0 +1,15 @@
+"""API views for NetBox Custom Widget plugin."""
+
+from netbox.api.viewsets import NetBoxModelViewSet
+
+from ..filtersets import CustomAPIEndpointFilterSet
+from ..models import CustomAPIEndpoint
+from .serializers import CustomAPIEndpointSerializer
+
+
+class CustomAPIEndpointViewSet(NetBoxModelViewSet):
+    """API viewset for CustomAPIEndpoint objects."""
+
+    queryset = CustomAPIEndpoint.objects.prefetch_related("tags")
+    serializer_class = CustomAPIEndpointSerializer
+    filterset_class = CustomAPIEndpointFilterSet

netbox_custom_widget-0.1.0/netbox_custom_widget/filtersets.py

@@ -0,0 +1,26 @@
+"""Filtersets for NetBox Custom Widget plugin."""
+
+import django_filters
+from netbox.filtersets import NetBoxModelFilterSet
+
+from .models import CustomAPIEndpoint, DisplayModeChoices, HTTPMethodChoices
+
+
+class CustomAPIEndpointFilterSet(NetBoxModelFilterSet):
+    """Filterset for CustomAPIEndpoint model."""
+
+    name = django_filters.CharFilter(lookup_expr="icontains")
+    http_method = django_filters.MultipleChoiceFilter(choices=HTTPMethodChoices)
+    display_mode = django_filters.MultipleChoiceFilter(choices=DisplayModeChoices)
+
+    class Meta:
+        model = CustomAPIEndpoint
+        fields = ["id", "name", "http_method", "display_mode"]
+
+    def search(self, queryset, name, value):
+        """Search across multiple fields."""
+        if not value.strip():
+            return queryset
+        from django.db.models import Q
+
+        return queryset.filter(Q(name__icontains=value) | Q(url__icontains=value) | Q(description__icontains=value))

netbox_custom_widget-0.1.0/netbox_custom_widget/forms.py

@@ -0,0 +1,91 @@
+"""Forms for NetBox Custom Widget plugin."""
+
+from django import forms
+from netbox.forms import NetBoxModelBulkEditForm, NetBoxModelFilterSetForm, NetBoxModelForm, NetBoxModelImportForm
+from utilities.forms.fields import CommentField, TagFilterField
+from utilities.forms.rendering import FieldSet
+
+from .models import CustomAPIEndpoint, DisplayModeChoices, HTTPMethodChoices
+
+
+class CustomAPIEndpointForm(NetBoxModelForm):
+    """Form for creating/editing CustomAPIEndpoint objects."""
+
+    comments = CommentField()
+
+    fieldsets = (
+        FieldSet("name", "description", name="General"),
+        FieldSet("url", "http_method", "headers", "body", "verify_ssl", "timeout", name="API Configuration"),
+        FieldSet("mappings", "display_mode", "refresh_interval", name="Display"),
+        FieldSet("comments", "tags", name="Details"),
+    )
+
+    class Meta:
+        model = CustomAPIEndpoint
+        fields = [
+            "name",
+            "url",
+            "http_method",
+            "headers",
+            "body",
+            "mappings",
+            "display_mode",
+            "refresh_interval",
+            "verify_ssl",
+            "timeout",
+            "description",
+            "comments",
+            "tags",
+        ]
+        widgets = {
+            "body": forms.Textarea(attrs={"rows": 3}),
+        }
+
+
+class CustomAPIEndpointFilterForm(NetBoxModelFilterSetForm):
+    """Filter form for CustomAPIEndpoint list view."""
+
+    model = CustomAPIEndpoint
+
+    name = forms.CharField(required=False)
+    http_method = forms.MultipleChoiceField(choices=HTTPMethodChoices, required=False)
+    display_mode = forms.MultipleChoiceField(choices=DisplayModeChoices, required=False)
+    tag = TagFilterField(model)
+
+
+class CustomAPIEndpointImportForm(NetBoxModelImportForm):
+    """Import form for CustomAPIEndpoint objects."""
+
+    class Meta:
+        model = CustomAPIEndpoint
+        fields = [
+            "name",
+            "url",
+            "http_method",
+            "headers",
+            "body",
+            "mappings",
+            "display_mode",
+            "refresh_interval",
+            "verify_ssl",
+            "timeout",
+            "description",
+            "comments",
+            "tags",
+        ]
+
+
+class CustomAPIEndpointBulkEditForm(NetBoxModelBulkEditForm):
+    """Bulk edit form for CustomAPIEndpoint objects."""
+
+    model = CustomAPIEndpoint
+
+    http_method = forms.ChoiceField(choices=HTTPMethodChoices, required=False)
+    display_mode = forms.ChoiceField(choices=DisplayModeChoices, required=False)
+    refresh_interval = forms.IntegerField(required=False)
+    verify_ssl = forms.NullBooleanField(required=False)
+    timeout = forms.IntegerField(required=False)
+    description = forms.CharField(max_length=200, required=False)
+    comments = CommentField()
+
+    nullable_fields = ["description", "comments", "body"]

netbox_custom_widget-0.1.0/netbox_custom_widget/migrations/0001_initial.py

@@ -0,0 +1,132 @@
+import django.db.models.deletion
+import taggit.managers
+import utilities.json
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ("extras", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="CustomAPIEndpoint",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                ("created", models.DateTimeField(auto_now_add=True, null=True)),
+                ("last_updated", models.DateTimeField(auto_now=True, null=True)),
+                (
+                    "custom_field_data",
+                    models.JSONField(
+                        blank=True,
+                        default=dict,
+                        encoder=utilities.json.CustomFieldJSONEncoder,
+                    ),
+                ),
+                (
+                    "name",
+                    models.CharField(
+                        help_text="Display name for this endpoint",
+                        max_length=100,
+                        unique=True,
+                    ),
+                ),
+                (
+                    "url",
+                    models.CharField(
+                        help_text="API endpoint URL",
+                        max_length=500,
+                    ),
+                ),
+                (
+                    "http_method",
+                    models.CharField(
+                        default="GET",
+                        max_length=10,
+                    ),
+                ),
+                (
+                    "headers",
+                    models.JSONField(
+                        blank=True,
+                        default=dict,
+                        help_text="Custom HTTP headers as JSON (e.g., authorization)",
+                    ),
+                ),
+                (
+                    "body",
+                    models.TextField(
+                        blank=True,
+                        help_text="Request body for POST requests",
+                    ),
+                ),
+                (
+                    "mappings",
+                    models.JSONField(
+                        blank=True,
+                        default=list,
+                        help_text="Field mapping configuration as JSON array",
+                    ),
+                ),
+                (
+                    "display_mode",
+                    models.CharField(
+                        default="list",
+                        max_length=10,
+                    ),
+                ),
+                (
+                    "refresh_interval",
+                    models.PositiveIntegerField(
+                        default=30,
+                        help_text="Auto-refresh interval in seconds (0 to disable)",
+                    ),
+                ),
+                (
+                    "verify_ssl",
+                    models.BooleanField(
+                        default=True,
+                        help_text="Verify SSL certificates",
+                    ),
+                ),
+                (
+                    "timeout",
+                    models.PositiveIntegerField(
+                        default=30,
+                        help_text="Request timeout in seconds",
+                    ),
+                ),
+                (
+                    "description",
+                    models.TextField(blank=True),
+                ),
+                (
+                    "comments",
+                    models.TextField(blank=True),
+                ),
+                (
+                    "tags",
+                    taggit.managers.TaggableManager(
+                        through="extras.TaggedItem",
+                        to="extras.Tag",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "API Endpoint",
+                "verbose_name_plural": "API Endpoints",
+                "ordering": ["name"],
+            },
+        ),
+    ]

netbox_custom_widget-0.1.0/netbox_custom_widget/models.py

@@ -0,0 +1,106 @@
+"""Models for NetBox Custom Widget plugin."""
+
+from django.db import models
+from django.urls import reverse
+from netbox.models import NetBoxModel
+from utilities.choices import ChoiceSet
+
+
+class HTTPMethodChoices(ChoiceSet):
+    """HTTP method choices."""
+
+    key = "CustomAPIEndpoint.http_method"
+
+    METHOD_GET = "GET"
+    METHOD_POST = "POST"
+
+    CHOICES = [
+        (METHOD_GET, "GET", "blue"),
+        (METHOD_POST, "POST", "green"),
+    ]
+
+
+class DisplayModeChoices(ChoiceSet):
+    """Display mode choices for widget rendering."""
+
+    key = "CustomAPIEndpoint.display_mode"
+
+    MODE_LIST = "list"
+    MODE_BLOCK = "block"
+
+    CHOICES = [
+        (MODE_LIST, "List", "blue"),
+        (MODE_BLOCK, "Block", "gray"),
+    ]
+
+
+class CustomAPIEndpoint(NetBoxModel):
+    """
+    Stores configuration for an external API endpoint.
+
+    Each endpoint defines a URL, authentication, field mappings,
+    and display settings for use in dashboard widgets.
+    """
+
+    name = models.CharField(
+        max_length=100,
+        unique=True,
+        help_text="Display name for this endpoint",
+    )
+    url = models.CharField(
+        max_length=500,
+        help_text="API endpoint URL",
+    )
+    http_method = models.CharField(
+        max_length=10,
+        choices=HTTPMethodChoices,
+        default=HTTPMethodChoices.METHOD_GET,
+    )
+    headers = models.JSONField(
+        default=dict,
+        blank=True,
+        help_text="Custom HTTP headers as JSON (e.g., authorization)",
+    )
+    body = models.TextField(
+        blank=True,
+        help_text="Request body for POST requests",
+    )
+    mappings = models.JSONField(
+        default=list,
+        blank=True,
+        help_text="Field mapping configuration as JSON array",
+    )
+    display_mode = models.CharField(
+        max_length=10,
+        choices=DisplayModeChoices,
+        default=DisplayModeChoices.MODE_LIST,
+    )
+    refresh_interval = models.PositiveIntegerField(
+        default=30,
+        help_text="Auto-refresh interval in seconds (0 to disable)",
+    )
+    verify_ssl = models.BooleanField(
+        default=True,
+        help_text="Verify SSL certificates",
+    )
+    timeout = models.PositiveIntegerField(
+        default=30,
+        help_text="Request timeout in seconds",
+    )
+    description = models.TextField(
+        blank=True,
+    )
+    comments = models.TextField(
+        blank=True,
+    )
+
+    class Meta:
+        ordering = ["name"]
+        verbose_name = "API Endpoint"
+        verbose_name_plural = "API Endpoints"
+
+    def __str__(self):
+        return self.name
+
+    def get_absolute_url(self):
+        return reverse("plugins:netbox_custom_widget:customapiendpoint", args=[self.pk])