14132 Add EventRule - change webhook and add in script processing to …

…events (netbox-community#14267) --------- Co-authored-by: Jeremy Stretch <[email protected]>
mmhuang · Nov 30, 2023 · a38a382 · a38a382
1 parent b83fcc6
commit a38a382
Show file tree

Hide file tree

Showing 55 changed files with 1,564 additions and 584 deletions.
diff --git a/docs/configuration/required-parameters.md b/docs/configuration/required-parameters.md
@@ -59,10 +59,7 @@ DATABASE = {
 
 ## REDIS
 
-[Redis](https://redis.io/) is an in-memory data store similar to memcached. While Redis has been an optional component of
-NetBox since the introduction of webhooks in version 2.4, it is required starting in 2.6 to support NetBox's caching
-functionality (as well as other planned features). In 2.7, the connection settings were broken down into two sections for
-task queuing and caching, allowing the user to connect to different Redis instances/databases per feature.
+[Redis](https://redis.io/) is a lightweight in-memory data store similar to memcached. NetBox employs Redis for background task queuing and other features.
 
 Redis is configured using a configuration setting similar to `DATABASE` and these settings are the same for both of the `tasks` and `caching` subsections:
 
@@ -81,15 +78,15 @@ REDIS = {
     'tasks': {
         'HOST': 'redis.example.com',
         'PORT': 1234,
-        'USERNAME': 'netbox'
+        'USERNAME': 'netbox',
         'PASSWORD': 'foobar',
         'DATABASE': 0,
         'SSL': False,
     },
     'caching': {
         'HOST': 'localhost',
         'PORT': 6379,
-        'USERNAME': ''
+        'USERNAME': '',
         'PASSWORD': '',
         'DATABASE': 1,
         'SSL': False,

diff --git a/docs/development/application-registry.md b/docs/development/application-registry.md
@@ -31,7 +31,7 @@ A dictionary of particular features (e.g. custom fields) mapped to the NetBox mo
         'dcim': ['site', 'rack', 'devicetype', ...],
         ...
     },
-    'webhooks': {
+    'event_rules': {
         'extras': ['configcontext', 'tag', ...],
         'dcim': ['site', 'rack', 'devicetype', ...],
     },

diff --git a/docs/development/models.md b/docs/development/models.md
@@ -10,19 +10,19 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 
 Depending on its classification, each NetBox model may support various features which enhance its operation. Each feature is enabled by inheriting from its designated mixin class, and some features also make use of the [application registry](./application-registry.md#model_features).
 
-| Feature                                                    | Feature Mixin           | Registry Key       | Description                                                                    |
-|------------------------------------------------------------|-------------------------|--------------------|--------------------------------------------------------------------------------|
-| [Change logging](../features/change-logging.md)            | `ChangeLoggingMixin`    | -                  | Changes to these objects are automatically recorded in the change log          |
-| Cloning                                                    | `CloningMixin`          | -                  | Provides the `clone()` method to prepare a copy                                |
-| [Custom fields](../customization/custom-fields.md)         | `CustomFieldsMixin`     | `custom_fields`    | These models support the addition of user-defined fields                       |
-| [Custom links](../customization/custom-links.md)           | `CustomLinksMixin`      | `custom_links`     | These models support the assignment of custom links                            |
-| [Custom validation](../customization/custom-validation.md) | `CustomValidationMixin` | -                  | Supports the enforcement of custom validation rules                            |
-| [Export templates](../customization/export-templates.md)   | `ExportTemplatesMixin`  | `export_templates` | Users can create custom export templates for these models                      |
-| [Job results](../features/background-jobs.md)              | `JobsMixin`             | `jobs`             | Users can create custom export templates for these models                      |
-| [Journaling](../features/journaling.md)                    | `JournalingMixin`       | `journaling`       | These models support persistent historical commentary                          |
-| [Synchronized data](../integrations/synchronized-data.md)  | `SyncedDataMixin`       | `synced_data`      | Certain model data can be automatically synchronized from a remote data source |
-| [Tagging](../models/extras/tag.md)                         | `TagsMixin`             | `tags`             | The models can be tagged with user-defined tags                                |
-| [Webhooks](../integrations/webhooks.md)                    | `WebhooksMixin`         | `webhooks`         | NetBox is capable of generating outgoing webhooks for these objects            |
+| Feature                                                    | Feature Mixin           | Registry Key       | Description                                                                             |
+|------------------------------------------------------------|-------------------------|--------------------|-----------------------------------------------------------------------------------------|
+| [Change logging](../features/change-logging.md)            | `ChangeLoggingMixin`    | -                  | Changes to these objects are automatically recorded in the change log                   |
+| Cloning                                                    | `CloningMixin`          | -                  | Provides the `clone()` method to prepare a copy                                         |
+| [Custom fields](../customization/custom-fields.md)         | `CustomFieldsMixin`     | `custom_fields`    | These models support the addition of user-defined fields                                |
+| [Custom links](../customization/custom-links.md)           | `CustomLinksMixin`      | `custom_links`     | These models support the assignment of custom links                                     |
+| [Custom validation](../customization/custom-validation.md) | `CustomValidationMixin` | -                  | Supports the enforcement of custom validation rules                                     |
+| [Export templates](../customization/export-templates.md)   | `ExportTemplatesMixin`  | `export_templates` | Users can create custom export templates for these models                               |
+| [Job results](../features/background-jobs.md)              | `JobsMixin`             | `jobs`             | Users can create custom export templates for these models                               |
+| [Journaling](../features/journaling.md)                    | `JournalingMixin`       | `journaling`       | These models support persistent historical commentary                                   |
+| [Synchronized data](../integrations/synchronized-data.md)  | `SyncedDataMixin`       | `synced_data`      | Certain model data can be automatically synchronized from a remote data source          |
+| [Tagging](../models/extras/tag.md)                         | `TagsMixin`             | `tags`             | The models can be tagged with user-defined tags                                         |
+| [Event rules](../features/event-rules.md)                  | `EventRulesMixin`       | `event_rules`      | Event rules can send webhooks or run custom scripts automatically in response to events |
 
 ## Models Index
 
@@ -111,7 +111,7 @@ Component models represent individual physical or virtual components belonging t
 
 ### Component Template Models
 
-These function as templates to effect the replication of device and virtual machine components. Component template models support a limited feature set, including change logging, custom validation, and webhooks.
+These function as templates to effect the replication of device and virtual machine components. Component template models support a limited feature set, including change logging, custom validation, and event rules.
 
 * [dcim.ConsolePortTemplate](../models/dcim/consoleporttemplate.md)
 * [dcim.ConsoleServerPortTemplate](../models/dcim/consoleserverporttemplate.md)

diff --git a/docs/features/api-integration.md b/docs/features/api-integration.md
@@ -26,9 +26,9 @@ To learn more about this feature, check out the [GraphQL API documentation](../i
 
 ## Webhooks
 
-A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are an excellent mechanism for building event-based automation processes.
+A webhook is a mechanism for conveying to some external system a change that has taken place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. To do this, first create a [webhook](../models/extras/webhook.md) identifying the remote receiver (URL), HTTP method, and any other necessary parameters. Then, define an [event rule](../models/extras/eventrule.md) which is triggered by device changes to transmit the webhook.
 
-To learn more about this feature, check out the [webhooks documentation](../integrations/webhooks.md).
+When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are an excellent mechanism for building event-based automation processes. To learn more about this feature, check out the [webhooks documentation](../integrations/webhooks.md).
 
 ## Prometheus Metrics
 

diff --git a/docs/features/event-rules.md b/docs/features/event-rules.md
@@ -0,0 +1,31 @@
+# Event Rules
+
+NetBox includes the ability to execute certain functions in response to internal object changes. These include:
+
+* [Scripts](../customization/custom-scripts.md) execution
+* [Webhooks](../integrations/webhooks.md) execution
+
+For example, suppose you want to automatically configure a monitoring system to start monitoring a device when its operational status is changed to active, and remove it from monitoring for any other status. You can create a webhook in NetBox for the device model and craft its content and destination URL to effect the desired change on the receiving system. You can then associate an event rule with this webhook and the webhook will be sent automatically by NetBox whenever the configured constraints are met.
+
+Each event must be associated with at least one NetBox object type and at least one event (e.g. create, update, or delete).
+
+## Conditional Event Rules
+
+An event rule may include a set of conditional logic expressed in JSON used to control whether an event triggers for a specific object. For example, you may wish to trigger an event for devices only when the `status` field of an object is "active":
+
+```json
+{
+  "and": [
+    {
+      "attr": "status.value",
+      "value": "active"
+    }
+  ]
+}
+```
+
+For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md).
+
+## Event Rule Processing
+
+When a change is detected, any resulting events are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing event(s) to be processed. The events are then extracted from the queue by the `rqworker` process. The current event queue and any failed events can be inspected in the admin UI under System > Background Tasks.
diff --git a/docs/index.md b/docs/index.md
@@ -32,7 +32,7 @@ In addition to its expansive and robust data model, NetBox offers myriad mechani
 * Custom fields
 * Custom model validation
 * Export templates
-* Webhooks
+* Event rules
 * Plugins
 * REST & GraphQL APIs
 

diff --git a/docs/integrations/webhooks.md b/docs/integrations/webhooks.md
@@ -1,11 +1,9 @@
 # Webhooks
 
-NetBox can be configured to transmit outgoing webhooks to remote systems in response to internal object changes. The receiver can act on the data in these webhook messages to perform related tasks.
+NetBox can be configured via [Event Rules](../features/event-rules.md) to transmit outgoing webhooks to remote systems in response to internal object changes. The receiver can act on the data in these webhook messages to perform related tasks.
 
 For example, suppose you want to automatically configure a monitoring system to start monitoring a device when its operational status is changed to active, and remove it from monitoring for any other status. You can create a webhook in NetBox for the device model and craft its content and destination URL to effect the desired change on the receiving system. Webhooks will be sent automatically by NetBox whenever the configured constraints are met.
 
-Each webhook must be associated with at least one NetBox object type and at least one event (create, update, or delete). Users can specify the receiver URL, HTTP request type (`GET`, `POST`, etc.), content type, and headers. A request body can also be specified; if left blank, this will default to a serialized representation of the affected object.
-
 !!! warning "Security Notice"
     Webhooks support the inclusion of user-submitted code to generate the URL, custom headers, and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users.
 
@@ -70,26 +68,12 @@ If no body template is specified, the request body will be populated with a JSON
 }
 ```
 
-## Conditional Webhooks
-
-A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active":
-
-```json
-{
-  "and": [
-    {
-      "attr": "status.value",
-      "value": "active"
-    }
-  ]
-}
-```
-
-For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md).
+!!! note
+    The setting of conditional webhooks has been moved to [Event Rules](../features/event-rules.md) since NetBox 3.7
 
 ## Webhook Processing
 
-When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks.
+Using [Event Rules](../features/event-rules.md), when a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks.
 
 A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI.
 

diff --git a/docs/models/extras/eventrule.md b/docs/models/extras/eventrule.md
@@ -0,0 +1,35 @@
+# EventRule
+
+An event rule is a mechanism for automatically taking an action (such as running a script or sending a webhook) in response to an event in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating an event for device objects and designating a webhook to be transmitted. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver.
+
+See the [event rules documentation](../features/event-rules.md)  for more information.
+
+## Fields
+
+### Name
+
+A unique human-friendly name.
+
+### Content Types
+
+The type(s) of object in NetBox that will trigger the rule.
+
+### Enabled
+
+If not selected, the event rule will not be processed.
+
+### Events
+
+The events which will trigger the rule. At least one event type must be selected.
+
+| Name       | Description                          |
+|------------|--------------------------------------|
+| Creations  | A new object has been created        |
+| Updates    | An existing object has been modified |
+| Deletions  | An object has been deleted           |
+| Job starts | A job for an object starts           |
+| Job ends   | A job for an object terminates       |
+
+### Conditions
+
+A set of [prescribed conditions](../../reference/conditions.md) against which the triggering object will be evaluated. If the conditions are defined but not met by the object, no action will be taken. An event rule that does not define any conditions will _always_ trigger.
diff --git a/docs/plugins/development/models.md b/docs/plugins/development/models.md
@@ -123,14 +123,17 @@ For more information about database migrations, see the [Django documentation](h
 
 ::: netbox.models.features.CustomValidationMixin
 
+::: netbox.models.features.EventRulesMixin
+
+!!! note
+    `EventRulesMixin` was renamed from `WebhooksMixin` in NetBox v3.7.
+
 ::: netbox.models.features.ExportTemplatesMixin
 
 ::: netbox.models.features.JournalingMixin
 
 ::: netbox.models.features.TagsMixin
 
-::: netbox.models.features.WebhooksMixin
-
 ## Choice Sets
 
 For model fields which support the selection of one or more values from a predefined list of choices, NetBox provides the `ChoiceSet` utility class. This can be used in place of a regular choices tuple to provide enhanced functionality, namely dynamic configuration and colorization. (See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/models/fields/#choices) on the `choices` parameter for supported model fields.)

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -87,6 +87,7 @@ nav:
         - Auth & Permissions: 'features/authentication-permissions.md'
         - API & Integration: 'features/api-integration.md'
         - Customization: 'features/customization.md'
+        - Event Rules: 'features/event-rules.md'
     - Installation & Upgrade:
         - Installing NetBox: 'installation/index.md'
         - 1. PostgreSQL: 'installation/1-postgresql.md'
@@ -215,6 +216,7 @@ nav:
             - CustomField: 'models/extras/customfield.md'
             - CustomFieldChoiceSet: 'models/extras/customfieldchoiceset.md'
             - CustomLink: 'models/extras/customlink.md'
+            - EventRule: 'models/extras/eventrule.md'
             - ExportTemplate: 'models/extras/exporttemplate.md'
             - ImageAttachment: 'models/extras/imageattachment.md'
             - JournalEntry: 'models/extras/journalentry.md'

diff --git a/netbox/core/models/contenttypes.py b/netbox/core/models/contenttypes.py
@@ -26,7 +26,7 @@ def with_feature(self, feature):
         Return the ContentTypes only for models which are registered as supporting the specified feature. For example,
         we can find all ContentTypes for models which support webhooks with
 
-            ContentType.objects.with_feature('webhooks')
+            ContentType.objects.with_feature('event_rules')
         """
         if feature not in registry['model_features']:
             raise KeyError(