diff --git a/docs/administration/permissions.md b/docs/administration/permissions.md index a73eddcd8..666f8a90b 100644 --- a/docs/administration/permissions.md +++ b/docs/administration/permissions.md @@ -20,7 +20,9 @@ There are four core actions that can be permitted for each type of object within * **Change** - Modify an existing object * **Delete** - Delete an existing object -In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `run` permission for scripts allows a user to execute custom scripts. These can be specified when granting a permission in the "additional actions" field. +In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `sync` action for data sources allows a user to synchronize data from a remote source, and the `render_config` action for devices and virtual machines allows rendering configuration templates. + +Some models have registered custom actions that appear as checkboxes when creating or editing a permission. These are grouped by model under "Custom actions" in the permission form. Additional custom actions (such as those not yet registered or for backwards compatibility) can be entered manually in the "Additional actions" field. !!! note Internally, all actions granted by a permission (both built-in and custom) are stored as strings in an array field named `actions`. diff --git a/docs/plugins/development/permissions.md b/docs/plugins/development/permissions.md new file mode 100644 index 000000000..246254a97 --- /dev/null +++ b/docs/plugins/development/permissions.md @@ -0,0 +1,36 @@ +# Custom Model Actions + +Plugins can register custom permission actions for their models. These actions appear as checkboxes in the ObjectPermission form, making it easy for administrators to grant or restrict access to plugin-specific functionality without manually entering action names. + +For example, a plugin might define a "sync" action for a model that syncs data from an external source, or a "bypass" action that allows users to bypass certain restrictions. + +## Registering Model Actions + +To register custom actions for a model, call `register_model_actions()` in your plugin's `ready()` method: + +```python +# __init__.py +from netbox.plugins import PluginConfig + +class MyPluginConfig(PluginConfig): + name = 'my_plugin' + # ... + + def ready(self): + super().ready() + from utilities.permissions import ModelAction, register_model_actions + from .models import MyModel + + register_model_actions(MyModel, [ + ModelAction('sync', help_text='Synchronize data from external source'), + ModelAction('export', help_text='Export data to external system'), + ]) + +config = MyPluginConfig +``` + +Once registered, these actions will appear grouped under your model's name when creating or editing an ObjectPermission that includes your model as an object type. + +::: utilities.permissions.ModelAction + +::: utilities.permissions.register_model_actions diff --git a/mkdocs.yml b/mkdocs.yml index dc758f197..9af7e1b31 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -151,6 +151,7 @@ nav: - Filters & Filter Sets: 'plugins/development/filtersets.md' - Search: 'plugins/development/search.md' - Event Types: 'plugins/development/event-types.md' + - Permissions: 'plugins/development/permissions.md' - Data Backends: 'plugins/development/data-backends.md' - Webhooks: 'plugins/development/webhooks.md' - User Interface: 'plugins/development/user-interface.md' diff --git a/netbox/utilities/permissions.py b/netbox/utilities/permissions.py index c442b2030..b1f612266 100644 --- a/netbox/utilities/permissions.py +++ b/netbox/utilities/permissions.py @@ -21,6 +21,13 @@ __all__ = ( @dataclass class ModelAction: + """ + Represents a custom permission action for a model. + + Attributes: + name: The action identifier (e.g. 'sync', 'render_config') + help_text: Optional description displayed in the ObjectPermission form + """ name: str help_text: str = '' @@ -34,6 +41,14 @@ class ModelAction: def register_model_actions(model: type[Model], actions: list[ModelAction | str]): + """ + Register custom permission actions for a model. These actions will appear as + checkboxes in the ObjectPermission form when the model is selected. + + Args: + model: The model class to register actions for + actions: A list of ModelAction instances or action name strings + """ label = f'{model._meta.app_label}.{model._meta.model_name}' for action in actions: if isinstance(action, str):