Event Rule Actions

Event rules dispatch to an action when a matching event occurs, such as sending a webhook request or running a script. Plugins can register their own action types to extend the list of actions an event rule can perform, by subclassing NetBox's EventRuleAction class.

event_rules.py

from django.utils.translation import gettext_lazy as _
from netbox.event_rules import EventRuleAction

from .models import Ticket

class OpenTicketAction(EventRuleAction):
    slug = 'my_plugin.open_ticket'
    label = _('Open ticket')
    description = _('Open a ticket in the external ticketing system')
    object_model = Ticket
    object_required = True

    def enqueue(self, *, event_rule, event_context, action_object, action_data):
        ...

To register one or more event rule actions with NetBox, define a list named event_rule_actions at the end of this file:

event_rules.py

event_rule_actions = [OpenTicketAction]

Tip

The path to the list of event rule actions can be modified by setting event_rule_actions in the PluginConfig instance.

A dotted namespace prefix (e.g. my_plugin.open_ticket) is strongly recommended for slug to avoid collisions with other plugins or with action types added to NetBox core in the future.

slug must begin with a lowercase letter, and may contain only letters, digits, underscores, and dot-separated segments thereafter. Hyphens are not allowed, even though they're common in plugin/package names -- use an underscore instead, e.g. my_plugin.open_ticket as in the example above. register_event_rule_action() raises ImproperlyConfigured immediately for a slug outside this pattern, rather than allowing it to fail later during GraphQL schema assembly.

slug/label are only required at registration time, not at class definition, so an intermediate base class shared by several concrete actions may leave them unset.

Actions must be stateless

Registration instantiates the class once, and that single instance serves every event rule, request, and background worker thread for the lifetime of the process. Do not stash per-event data on self in enqueue() or validate() -- concurrent dispatches would race over it. Everything an action needs is passed in as an argument.

Target Objects

If an action operates against a specific object (e.g. a webhook targets a Webhook instance, and a script targets a Script instance), set object_model to the relevant model class. NetBox uses this to render the object-selection field on the event rule form and to validate the selected object's type. object_required defaults to False (matching object_model's default of None); set it to True alongside object_model if the target object must always be selected. (Setting object_required without an object_model raises ImproperlyConfigured at registration, as it could never be satisfied.) Override get_object_queryset() to customize which objects are eligible for selection (e.g. to filter or further restrict the queryset).

The object-selection field is labeled with object_model's verbose name; set object_label to override it.

If an action leaves object_model as None, event rules using it must not specify a target object: supplying one is rejected as a validation error rather than being silently stored.

Bulk Import

To support resolving a target object from a CSV value during bulk import of event rules, override resolve_import_object(). Raise django.core.exceptions.ObjectDoesNotExist (or a subclass) if the supplied value doesn't resolve to an object. If this method is not overridden, event rules using this action type cannot be targeted at an object via bulk import.

Unregistered Actions

An event rule's action_type is stored as a plain string, and is not validated against the set of currently-registered actions at the database level. This means an event rule can reference an action type provided by a plugin that is later uninstalled or disabled, without the row being deleted or corrupted. While its action type is unavailable:

The event rule is skipped during event processing (it does not raise an error, and does not prevent other event rules from being processed).
It is displayed with an "unavailable" indicator in the UI. action_is_available is exposed as a read-only field via the REST API, and as a filter (?action_is_available=false), so affected event rules can be found in bulk.
It cannot be saved via the UI or REST API -- even to edit an unrelated field -- until its action_type is changed to a currently-registered value.

Reinstalling the plugin (and thereby re-registering the action type) automatically restores the event rule to working order, with no need to re-save it.

`EventRuleAction`

Base class for a registered Event Rule action. Subclass this to add a new action type that an EventRule can dispatch to, whether defined in NetBox core or in a plugin.

Registration instantiates the class once; that single instance serves every event rule, request, and background worker thread for the lifetime of the process. Implementations must therefore be stateless: enqueue() and validate() must not stash per-event data on self, as concurrent dispatches would race over it. Everything an action needs is passed in as arguments.

Attributes:

Name	Type	Description
`slug`		A unique identifier for this action (e.g. "webhook", or "myplugin.run_check" for a plugin-provided action). Must begin with a lowercase letter, and may contain only letters, digits, underscores, and dot-separated segments thereafter -- no hyphens (use an underscore instead, e.g. "my_plugin.open_ticket"). A dotted namespace prefix is strongly recommended for plugin-provided actions to avoid collisions with other plugins or future core actions.
`label`		The human-friendly name shown in the UI/API.
`description`		An optional, longer description shown alongside the label (e.g. as a tooltip in the action_type dropdown).
`object_model`		The model class (if any) which EventRule.action_object must be an instance of. May be left as None if this action never operates against a target object, in which case supplying an action_object is treated as a validation error.
`object_required`		Whether an action_object must be supplied for this action to be usable. Defaults to False; set True (alongside object_model) when a target object is mandatory. An action may declare object_model but still treat the object as optional.
`object_label`		The label for the object selection field on the event rule form. Defaults to object_model's verbose name.

`get_object_queryset()`

Return the queryset of objects eligible for selection as this action's action_object, or None if object_model is not set.

`get_object_label()`

Return the label for this action's object selection field, or None if object_model is not set. Defaults to object_model's verbose name, unless object_label has been set explicitly.

`resolve_import_object(value)`

Optional hook: resolve a CSV/bulk-import "action object" string to a model instance. Raise django.core.exceptions.ObjectDoesNotExist (or a subclass) if the value doesn't resolve. Return None (the default) if this action doesn't support bulk import.

`validate(*, action_object, action_data)`

Optional hook: add custom validation, raising ValidationError on failure. No-op by default; no need to call super() -- _validate() above runs the base checks regardless.

`enqueue(*, event_rule, event_context, action_object, action_data)`

Perform (or schedule) this action in response to a queued event. Implementations should not raise for conditions that are the fault of this EventRule's own configuration alone; log and return instead, so that other EventRules processed in the same batch are unaffected.