# netbox-quicklinks
Plugin for [Netbox](https://netbox.dev/) that adds support for quick links based on unique
item values
## Introduction
This plugin adds a very simple URL shim into Netbox which allows users to link directly to
a device with a known parameter (for example the name or serial number) without knowing
the Netbox ID. This is solve the very specific problem of creating permalinks in places
that aren't easily updated (such as un-automated documentation or physical labels).
For example, maybe we have a server named `svr01` in our rack. The physical server is old
and gets replaced with a newer generation of hardware. For lifecycle management reason I
want to decomission the existing device with Netbox ID 1234 and create a brand new device
with Netbox ID 4321. When I make this change, any place that I have a link to `svr01` as
`https://netbox.example.com/dcim/devices/1234/` will still point to the old device. I
could add a note to the old device that it's been replaced and the new one is located at
`https://netbox.example.com/dcim/devices/4321/`, but it'd be more convenient if I could
permalink directly to `svr01` regardless of what device currently holds that name.
This is the functionality that this plugin adds.
## Configuration
The `quick_links` parameter creates a map of link aliases to a configured fully quallified
field attribute. For example:
```
PLUGINS_CONFIG = {
"netbox_quicklinks": {
"quick_links": {
"dev": {
"field": "dcim.models.Device.name",
"case_sensitive": True,
},
}
}
}
```
This configuration allows the URL `https://netbox.example.com/plugins/links/dev/svr01` to
redirect to the native URL for the device with the name `svr01` (which may be, for
example, `https://netbox.example.com/dicm/devices/1234/`). The map key (i.e. `dev` in the
example above) defines the URL namespace under `links/` that the redirect will be
available under. Under each quick link entry are the below settings:
- The value of the `field` key defines the model attribute that the lookup will query
against
- The boolean under the `case_sensitive` key defines whether the lookup is done with case
sensitive values or not
### Adding quick links to the UI
It may be desirable to expose the configured quick links within the UI so that users can
easily copy them. This can be easily acheived using the
[Custom Links](https://docs.netbox.dev/en/stable/customization/custom-links/) feature.
To do this, create a new custom link with the Content Type set to the object defined in
the plugin config. Then set the Link URL to
`/plugins/links/<quick_link entry>/{{ object.<field> }}` where `<quick_link entry>` is the
key of the config under `PLUGINS_CONFIG['netbox_quicklinks']['quick_links']` and `<field>`
is the field configured under
`PLUGINS_CONFIG['netbox_quicklinks']['quick_links'][<quick_link entry>]['field']`.
For example, to create a quick link for the configuration entry `dev` shown above in the
[Configuration](#configuration) section, you would create a custom link with a Content
Type of `DCIM > Device` and a Link URL of `/plugins/links/dev/{{ object.name }}`.
## Limitations
- This plugin does not support complex queries or redirects. For example, while you can
create an alias for IP addresses (using `"field": "ipam.models.IPAddress.address"`) this
can only link to the IP Address object itself, there is no support for redirecting to
the device that is assigned the IP.
- Netbox makes no guarantee about the uniqueness of any field not noted as such. It is
possible to configure quick links based on fields that may match multiple objects, in
which case an error will be raised.
## Developer Documentation
All project contributors and participants are expected to adhere to the
[Contributor Covenant Code of Conduct, v2](CODE_OF_CONDUCT.md)
([external link](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)).
The `main` branch has the latest (and potentially unstable) changes. The stable releases
are tracked on [Github](https://github.com/enpaul/netbox-quicklinks/releases),
[PyPi](https://pypi.org/project/netbox-quicklinks/#history), and in the
[Changelog](CHANGELOG.md).
- To report a bug, request a feature, or ask for assistance, please
[open an issue on the Github repository](https://github.com/enpaul/netbox-quicklinks/issues/new).
- To report a security concern or code of conduct violation, please contact the project
author directly at **me \[at\] enp dot one**.
- To submit an update, please
[fork the repository](https://docs.github.com/en/enterprise/2.20/user/github/getting-started-with-github/fork-a-repo)
and [open a pull request](https://github.com/enpaul/netbox-quicklinks/compare).
Developing this project requires [Python 3.11+](https://www.python.org/downloads/) and
[Poetry 1.5](https://python-poetry.org/docs/#installation) or later. GNU Make can
optionally be used to quickly setup a local development environment using `make dev`, but
this is not required. See `make help` for other available targets.
In addition, developers will require a development installation of Netbox. See setup
instructions
[here](https://github.com/netbox-community/netbox-plugin-tutorial/blob/main/tutorial/step01-initial-setup.md)
for getting started.
> ℹ️ **Note:** The pre-commit hooks require dependencies in the Poetry environment to run.
> To make a commit with the pre-commit hooks, you will need to run `poetry run git commit`
> or, alternatively,
> [launch an environment shell](https://python-poetry.org/docs/cli/#shell).
Raw data
{
"_id": null,
"home_page": "https://github.com/enpaul/netbox-quicklinks/",
"name": "netbox-quicklinks",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "netbox,plugin,quick,links",
"author": "Ethan Paul",
"author_email": "24588726+enpaul@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/8d/b4/4bf72302bc39935c6450a4d2d0a3f6d1ae5bff54830e2f1e43bf77544bf9/netbox_quicklinks-0.1.1.tar.gz",
"platform": null,
"description": "# netbox-quicklinks\n\nPlugin for [Netbox](https://netbox.dev/) that adds support for quick links based on unique\nitem values\n\n## Introduction\n\nThis plugin adds a very simple URL shim into Netbox which allows users to link directly to\na device with a known parameter (for example the name or serial number) without knowing\nthe Netbox ID. This is solve the very specific problem of creating permalinks in places\nthat aren't easily updated (such as un-automated documentation or physical labels).\n\nFor example, maybe we have a server named `svr01` in our rack. The physical server is old\nand gets replaced with a newer generation of hardware. For lifecycle management reason I\nwant to decomission the existing device with Netbox ID 1234 and create a brand new device\nwith Netbox ID 4321. When I make this change, any place that I have a link to `svr01` as\n`https://netbox.example.com/dcim/devices/1234/` will still point to the old device. I\ncould add a note to the old device that it's been replaced and the new one is located at\n`https://netbox.example.com/dcim/devices/4321/`, but it'd be more convenient if I could\npermalink directly to `svr01` regardless of what device currently holds that name.\n\nThis is the functionality that this plugin adds.\n\n## Configuration\n\nThe `quick_links` parameter creates a map of link aliases to a configured fully quallified\nfield attribute. For example:\n\n```\nPLUGINS_CONFIG = {\n \"netbox_quicklinks\": {\n \"quick_links\": {\n \"dev\": {\n \"field\": \"dcim.models.Device.name\",\n \"case_sensitive\": True,\n },\n }\n }\n}\n```\n\nThis configuration allows the URL `https://netbox.example.com/plugins/links/dev/svr01` to\nredirect to the native URL for the device with the name `svr01` (which may be, for\nexample, `https://netbox.example.com/dicm/devices/1234/`). The map key (i.e. `dev` in the\nexample above) defines the URL namespace under `links/` that the redirect will be\navailable under. Under each quick link entry are the below settings:\n\n- The value of the `field` key defines the model attribute that the lookup will query\n against\n- The boolean under the `case_sensitive` key defines whether the lookup is done with case\n sensitive values or not\n\n### Adding quick links to the UI\n\nIt may be desirable to expose the configured quick links within the UI so that users can\neasily copy them. This can be easily acheived using the\n[Custom Links](https://docs.netbox.dev/en/stable/customization/custom-links/) feature.\n\nTo do this, create a new custom link with the Content Type set to the object defined in\nthe plugin config. Then set the Link URL to\n`/plugins/links/<quick_link entry>/{{ object.<field> }}` where `<quick_link entry>` is the\nkey of the config under `PLUGINS_CONFIG['netbox_quicklinks']['quick_links']` and `<field>`\nis the field configured under\n`PLUGINS_CONFIG['netbox_quicklinks']['quick_links'][<quick_link entry>]['field']`.\n\nFor example, to create a quick link for the configuration entry `dev` shown above in the\n[Configuration](#configuration) section, you would create a custom link with a Content\nType of `DCIM > Device` and a Link URL of `/plugins/links/dev/{{ object.name }}`.\n\n## Limitations\n\n- This plugin does not support complex queries or redirects. For example, while you can\n create an alias for IP addresses (using `\"field\": \"ipam.models.IPAddress.address\"`) this\n can only link to the IP Address object itself, there is no support for redirecting to\n the device that is assigned the IP.\n- Netbox makes no guarantee about the uniqueness of any field not noted as such. It is\n possible to configure quick links based on fields that may match multiple objects, in\n which case an error will be raised.\n\n## Developer Documentation\n\nAll project contributors and participants are expected to adhere to the\n[Contributor Covenant Code of Conduct, v2](CODE_OF_CONDUCT.md)\n([external link](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)).\n\nThe `main` branch has the latest (and potentially unstable) changes. The stable releases\nare tracked on [Github](https://github.com/enpaul/netbox-quicklinks/releases),\n[PyPi](https://pypi.org/project/netbox-quicklinks/#history), and in the\n[Changelog](CHANGELOG.md).\n\n- To report a bug, request a feature, or ask for assistance, please\n [open an issue on the Github repository](https://github.com/enpaul/netbox-quicklinks/issues/new).\n- To report a security concern or code of conduct violation, please contact the project\n author directly at **\u200cme \\[at\u200c\\] enp dot\u200e \u200cone**.\n- To submit an update, please\n [fork the repository](https://docs.github.com/en/enterprise/2.20/user/github/getting-started-with-github/fork-a-repo)\n and [open a pull request](https://github.com/enpaul/netbox-quicklinks/compare).\n\nDeveloping this project requires [Python 3.11+](https://www.python.org/downloads/) and\n[Poetry 1.5](https://python-poetry.org/docs/#installation) or later. GNU Make can\noptionally be used to quickly setup a local development environment using `make dev`, but\nthis is not required. See `make help` for other available targets.\n\nIn addition, developers will require a development installation of Netbox. See setup\ninstructions\n[here](https://github.com/netbox-community/netbox-plugin-tutorial/blob/main/tutorial/step01-initial-setup.md)\nfor getting started.\n\n> \u2139\ufe0f **Note:** The pre-commit hooks require dependencies in the Poetry environment to run.\n> To make a commit with the pre-commit hooks, you will need to run `poetry run git commit`\n> or, alternatively,\n> [launch an environment shell](https://python-poetry.org/docs/cli/#shell).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Netbox plugin for supporting quick links based on unique item values",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/enpaul/netbox-quicklinks/",
"Repository": "https://github.com/enpaul/netbox-quicklinks/"
},
"split_keywords": [
"netbox",
"plugin",
"quick",
"links"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bb2e43843235e97e7bb63c7edecc41bea25f9c51badd5eb5f815cb8909b14629",
"md5": "e1a5d3b5c1a1dd2d9d83069dc55187fe",
"sha256": "4266532fdbafecf9a644500e3ba96c5dd23ead73b2457e9b4aeab2808cbc34ba"
},
"downloads": -1,
"filename": "netbox_quicklinks-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e1a5d3b5c1a1dd2d9d83069dc55187fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 7515,
"upload_time": "2023-11-02T21:36:33",
"upload_time_iso_8601": "2023-11-02T21:36:33.690682Z",
"url": "https://files.pythonhosted.org/packages/bb/2e/43843235e97e7bb63c7edecc41bea25f9c51badd5eb5f815cb8909b14629/netbox_quicklinks-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8db44bf72302bc39935c6450a4d2d0a3f6d1ae5bff54830e2f1e43bf77544bf9",
"md5": "3e8510826d792180b2cb7fa6990bccfd",
"sha256": "78eb0fcf5afd3e566bdd04399d4422917ea2dc50574d9eefac79eecaa45053f0"
},
"downloads": -1,
"filename": "netbox_quicklinks-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "3e8510826d792180b2cb7fa6990bccfd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 5993,
"upload_time": "2023-11-02T21:36:34",
"upload_time_iso_8601": "2023-11-02T21:36:34.685565Z",
"url": "https://files.pythonhosted.org/packages/8d/b4/4bf72302bc39935c6450a4d2d0a3f6d1ae5bff54830e2f1e43bf77544bf9/netbox_quicklinks-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-02 21:36:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "enpaul",
"github_project": "netbox-quicklinks",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "netbox-quicklinks"
}
JSON
