# NetBox Inventory Plugin
A [Netbox](https://github.com/netbox-community/netbox) plugin for hardware inventory.
## Features
Keep track of your hardware, whether it is installed or in storage. You can
define assets that represent hardware that can be used as a device, module, inventory item or rack in NetBox.
Each asset can have a storage location defined, when not in use. You can assign
an asset to a device, module or inventory item. The plugin can keep serial number
and asset tag between asset and device, module, inventory item or rack in sync if
enabled in settings.
On Site and Location detail views there is a new tab Assets that can show assets
that are stored or installed at that location or both. Rack details view also has
a tab for installed Assets. This provides a unified view of all assets at a given
location.
To properly support inventory items (that are used in NetBox to model SFP and
similar modules) the plugin defines inventory item types that are equivalent to
device types and module types.
Inventory item types can be assigned into inventory item groups. On a group detail
view you have an overview of the number of contained assets broken down by asset
status or inventory item type and status. This way you can quickly see how many
of a certain type of hardware you still have spare.
Inventory item groups can be nested, so you can for example model all pluggables
as one top-level group with child groups for SFP+ modules, SFP28 modules and so
on.
### Automatic management of asset status
Each asset has a status attribute that can indicate use of the asset. These
statuses can be set as needed by each NetBox installation.
Two statuses can have a special meaning. One to indicate asset is in storage and one
to indicate asset is in use.
netbox_inventory can automatically set status to the value specified in
`used_status_name` configuration item when an asset is assigned to a device, module
or inventory item.
When you remove an asset from device, module or inventory item the plugin will set
asset status to `stored_status_name` configuration item.
To disable automatically changing status, set these two config parameters to `None`.
### Prevent unwanted changes for tagged assets
With `asset_disable_editing_fields_for_tags` and `asset_disable_deletion_for_tags` you can prevent changes to specified asset data for assets that have certain tags attached. Changes are only prevented via web interface. API modifications are allowed.
The idea is that an external system uses some assets stored in netbox_inventory, and you want to prevent accidental changes to data directly in NetBox web interface. Only that external system should modify the data.
## Compatibility
This plugin requires netbox version 4.1 to work. Older versions of the plugin
support older netbox version as per table below:
| NetBox Version | Plugin Version |
|----------------|----------------|
| 3.7 | 1.6.x |
| 4.0 | 2.0.x |
| 4.1 | 2.1.x,2.2.x |
## Installing
Review [official Netbox plugin documentation](https://docs.netbox.dev/en/stable/plugins/#installing-plugins) for installation instructions.
You install the plugin from pypi with pip. Make sure you activate Netbox's virtual
environment first:
```bash
$ source /opt/netbox/venv/bin/activate
(venv) $ pip install netbox-inventory
```
For adding to a NetBox Docker setup see
[the general instructions for using netbox-docker with plugins](https://github.com/netbox-community/netbox-docker/wiki/Using-Netbox-Plugins).
You can install a development version directly from GitHub:
```bash
pip install https://github.com/ArnesSI/netbox-inventory/archive/master.tar.gz
```
or by adding to your `local_requirements.txt` or `plugin_requirements.txt` (netbox-docker):
```bash
https://github.com/ArnesSI/netbox-inventory/archive/master.tar.gz
```
After installation, enable the plugin in `/opt/netbox/netbox/netbox/configuration.py`,
or if you use netbox-docker, your `/configuration/plugins.py` file :
```python
PLUGINS = [
'netbox_inventory'
]
PLUGINS_CONFIG = {
"netbox_inventory": {},
}
```
Available configuration settings you can use in `PLUGINS_CONFIG` are described
below under [settings](#settings).
The last step is to apply database migrations and update netbox search index:
```bash
(venv) $ cd /opt/netbox/netbox/
(venv) $ python3 manage.py migrate
(venv) $ python3 manage.py reindex --lazy
```
If you're running under netbox-docker, you can skip this as migrations and index updates are applied if needed automatically when you bring up the containers.
### Settings
If you want to override the defaults for the plugin, you can do so in your via `/opt/netbox/netbox/netbox/configuration.py`,
or if you use netbox-docker, your `/configuration/plugins.py` file :
```python
PLUGINS = [
'netbox_inventory'
]
PLUGINS_CONFIG = {
"netbox_inventory": {
# Example settings below, see "Available settings"
# in README.md for all possible settings
"used_status_name": "used",
"stored_status_name": "stored",
"sync_hardware_serial_asset_tag": True,
},
}
```
#### Available settings
| Setting | Default value | Description |
|---------|---------------|-------------|
| `top_level_menu` | `True`| Add netbox-inventory to the top level of netbox navigation menu under Inventory heading. If set to False the plugin will add a menu item under the Plugins menu item.
| `used_status_name` | `'used'`| Status that indicates asset is in use. See "Automatic management of asset status" below for more info on this setting.
| `used_additional_status_names` | `[]` (empty list) | List of statuses that are also considered as in use.
| `stored_status_name` | `'stored'`| Status that indicates asset is in storage. See "Automatic management of asset status" below for more info on this setting.
| `stored_additional_status_names` | `['retired',]`| List of statuses that are also considered as not in use by various filters.
| `sync_hardware_serial_asset_tag` | `False` | When an asset is assigned or unassigned to a device, module or inventory item, update its serial number and asset tag to be in sync with the asset? For device and module device type or module type is also updated to match asset. For inventory items, manufacturer and part ID are updated to match asset. |
| `asset_import_create_purchase` | `False` | When importing assets, automatically create any given purchase, delivery or supplier if it doesn't exist already |
| `asset_import_create_device_type` | `False` | When importing a device type asset, automatically create manufacturer and/or device type if it doesn't exist |
| `asset_import_create_module_type` | `False` | When importing a module type asset, automatically create manufacturer and/or module type if it doesn't exist |
| `asset_import_create_inventoryitem_type` | `False` | When importing an inventory type asset, automatically create manufacturer and/or inventory item type if it doesn't exist |
| `asset_import_create_rack_type` | `False` | When importing a rack type asset, automatically create manufacturer and/or rack type if it doesn't exist |
| `asset_import_create_tenant` | `False` | When importing an asset, with owner or tenant, automatically create tenant if it doesn't exist |
| `asset_disable_editing_fields_for_tags` | `{}` | A dictionary of tags and fields that should be disabled for editing. This is useful if you want to prevent editing of certain fields for certain assets. The dictionary is in the form of `{tag: [field1, field2]}`. Example: `{'no-edit': ['serial_number', 'asset_tag']}`. This only affects the UI, the API can still be used to edit the fields. |
| `asset_disable_deletion_for_tags` | `[]` | List of tags that will disable deletion of assets. This only affects the UI, not the API. |
| `asset_custom_fields_search_filters` | `{}` | A dictionary of custom fields and lookup types that will be added to the search filters for assets. The dictionary is in the form of `{field: [lookup_type]}`. Example: `{'asset_mac': ['icontains', 'exact']}`. |
| `asset_warranty_expire_warning_days` | `90` | Days from warranty expiration to show as warning in Warranty remaining field |
| `prefill_asset_name_create_inventoryitem` | `False` | When hardware inventory item is created from an asset, prefill the InventoryItem name to match the asset name. |
| `prefill_asset_tag_create_inventoryitem` | `False` | When hardware inventory item is created from an asset, prefill the tags to match the tags associated to the asset. |
You can extend or define your own status choices for Asset, via [`FIELD_CHOICES`](https://docs.netbox.dev/en/stable/configuration/data-validation/#field_choices) setting in Netbox:
```
FIELD_CHOICES = {
'netbox_inventory.Asset.status+': (
('repair', 'In repair', 'orange'),
),
}
```
If you add more statuses, you should also adjust `used_additional_status_names` and `stored_additional_status_names` settings.
## Common questions
### I'd like to attach documents to asset, purchase, supplier, etc
Netbox inventory supports limited file attachments for its various models. You can add images to assets, inventory item types and that is it.
If you would like to attach various other documents to purchases, deliveries, suppliers... first ask yourself if you really need those documents in netbox or could you use some other tool that is possibly in use in your organization. Netbox itself is not great at managing documents. If you decide to manage documents outside netbox, you can porobably still achieve some sort of integration by using [custom links feature](https://netboxlabs.com/docs/netbox/en/stable/customization/custom-links/) to link from a netbox inventory object directly to a document in your document system.
If you really want to store document in netbox itself, then consider using [netbox_attachments plugin](https://github.com/Kani999/netbox-attachments). Here is a sample netbox configuration that will allow adding documents to suppliers, purchases and deliveries:
```python
PLUGINS = [
'netbox_inventory',
'netbox_attachments',
]
PLUGINS_CONFIG = {
'netbox_attachments': {
'apps': ['netbox_inventory',],
'display_setting': {
"netbox_inventory.supplier": "left_page",
"netbox_inventory.purchase": "full_width_page",
"netbox_inventory.delivery": "righ_page",
"netbox_inventory.asset": "hidden",
"netbox_inventory.inventoryitemtype": "hidden",
"netbox_inventory.inventoryitemgroup": "hidden",
},
},
}
```
Here is what it looks like when viewing a purchase:
## Models
Current plugin data model:
## Screenshots
Asset - List View
Asset - Individual View
Asset - Edit / Add View
Asset - Lots of filtering options
Suppliers - Individual View
Inventory Item Type - List View
Raw data
{
"_id": null,
"home_page": null,
"name": "netbox-inventory",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "netbox, netbox-plugin, inventory",
"author": null,
"author_email": "Matej Vadnjal <matej.vadnjal@arnes.si>",
"download_url": "https://files.pythonhosted.org/packages/58/89/c5dd491c86d95c1f1855d56f238afc56b8abe30e435156d72fa825f85fc3/netbox_inventory-2.2.1.tar.gz",
"platform": null,
"description": "# NetBox Inventory Plugin\n\nA [Netbox](https://github.com/netbox-community/netbox) plugin for hardware inventory.\n\n## Features\n\nKeep track of your hardware, whether it is installed or in storage. You can\ndefine assets that represent hardware that can be used as a device, module, inventory item or rack in NetBox.\n\nEach asset can have a storage location defined, when not in use. You can assign\nan asset to a device, module or inventory item. The plugin can keep serial number\nand asset tag between asset and device, module, inventory item or rack in sync if\nenabled in settings.\n\nOn Site and Location detail views there is a new tab Assets that can show assets\nthat are stored or installed at that location or both. Rack details view also has\na tab for installed Assets. This provides a unified view of all assets at a given\nlocation.\n\nTo properly support inventory items (that are used in NetBox to model SFP and\nsimilar modules) the plugin defines inventory item types that are equivalent to\ndevice types and module types. \n\nInventory item types can be assigned into inventory item groups. On a group detail\nview you have an overview of the number of contained assets broken down by asset\nstatus or inventory item type and status. This way you can quickly see how many\nof a certain type of hardware you still have spare.\n\nInventory item groups can be nested, so you can for example model all pluggables\nas one top-level group with child groups for SFP+ modules, SFP28 modules and so\non.\n\n### Automatic management of asset status\n\nEach asset has a status attribute that can indicate use of the asset. These\nstatuses can be set as needed by each NetBox installation.\n\nTwo statuses can have a special meaning. One to indicate asset is in storage and one\nto indicate asset is in use.\n\nnetbox_inventory can automatically set status to the value specified in\n`used_status_name` configuration item when an asset is assigned to a device, module\nor inventory item.\n\nWhen you remove an asset from device, module or inventory item the plugin will set\nasset status to `stored_status_name` configuration item.\n\nTo disable automatically changing status, set these two config parameters to `None`.\n\n### Prevent unwanted changes for tagged assets\n\nWith `asset_disable_editing_fields_for_tags` and `asset_disable_deletion_for_tags` you can prevent changes to specified asset data for assets that have certain tags attached. Changes are only prevented via web interface. API modifications are allowed.\n\nThe idea is that an external system uses some assets stored in netbox_inventory, and you want to prevent accidental changes to data directly in NetBox web interface. Only that external system should modify the data.\n\n## Compatibility\n\nThis plugin requires netbox version 4.1 to work. Older versions of the plugin\nsupport older netbox version as per table below:\n\n| NetBox Version | Plugin Version |\n|----------------|----------------|\n| 3.7 | 1.6.x |\n| 4.0 | 2.0.x |\n| 4.1 | 2.1.x,2.2.x |\n\n## Installing\n\nReview [official Netbox plugin documentation](https://docs.netbox.dev/en/stable/plugins/#installing-plugins) for installation instructions.\n\nYou install the plugin from pypi with pip. Make sure you activate Netbox's virtual\nenvironment first:\n\n```bash\n$ source /opt/netbox/venv/bin/activate\n(venv) $ pip install netbox-inventory\n```\n\nFor adding to a NetBox Docker setup see\n[the general instructions for using netbox-docker with plugins](https://github.com/netbox-community/netbox-docker/wiki/Using-Netbox-Plugins).\n\nYou can install a development version directly from GitHub:\n\n```bash\npip install https://github.com/ArnesSI/netbox-inventory/archive/master.tar.gz\n```\n\nor by adding to your `local_requirements.txt` or `plugin_requirements.txt` (netbox-docker):\n\n```bash\nhttps://github.com/ArnesSI/netbox-inventory/archive/master.tar.gz\n```\n\nAfter installation, enable the plugin in `/opt/netbox/netbox/netbox/configuration.py`,\n or if you use netbox-docker, your `/configuration/plugins.py` file :\n\n```python\nPLUGINS = [\n 'netbox_inventory'\n]\n\nPLUGINS_CONFIG = {\n \"netbox_inventory\": {},\n}\n```\n\nAvailable configuration settings you can use in `PLUGINS_CONFIG` are described\nbelow under [settings](#settings).\n\nThe last step is to apply database migrations and update netbox search index:\n\n```bash\n(venv) $ cd /opt/netbox/netbox/\n(venv) $ python3 manage.py migrate\n(venv) $ python3 manage.py reindex --lazy\n```\n\nIf you're running under netbox-docker, you can skip this as migrations and index updates are applied if needed automatically when you bring up the containers.\n\n### Settings\n\nIf you want to override the defaults for the plugin, you can do so in your via `/opt/netbox/netbox/netbox/configuration.py`,\n or if you use netbox-docker, your `/configuration/plugins.py` file :\n\n```python\nPLUGINS = [\n 'netbox_inventory'\n]\n\nPLUGINS_CONFIG = {\n \"netbox_inventory\": {\n # Example settings below, see \"Available settings\"\n # in README.md for all possible settings\n \"used_status_name\": \"used\",\n \"stored_status_name\": \"stored\",\n \"sync_hardware_serial_asset_tag\": True,\n },\n}\n```\n\n#### Available settings\n\n| Setting | Default value | Description |\n|---------|---------------|-------------|\n| `top_level_menu` | `True`| Add netbox-inventory to the top level of netbox navigation menu under Inventory heading. If set to False the plugin will add a menu item under the Plugins menu item.\n| `used_status_name` | `'used'`| Status that indicates asset is in use. See \"Automatic management of asset status\" below for more info on this setting.\n| `used_additional_status_names` | `[]` (empty list) | List of statuses that are also considered as in use.\n| `stored_status_name` | `'stored'`| Status that indicates asset is in storage. See \"Automatic management of asset status\" below for more info on this setting.\n| `stored_additional_status_names` | `['retired',]`| List of statuses that are also considered as not in use by various filters.\n| `sync_hardware_serial_asset_tag` | `False` | When an asset is assigned or unassigned to a device, module or inventory item, update its serial number and asset tag to be in sync with the asset? For device and module device type or module type is also updated to match asset. For inventory items, manufacturer and part ID are updated to match asset. |\n| `asset_import_create_purchase` | `False` | When importing assets, automatically create any given purchase, delivery or supplier if it doesn't exist already |\n| `asset_import_create_device_type` | `False` | When importing a device type asset, automatically create manufacturer and/or device type if it doesn't exist |\n| `asset_import_create_module_type` | `False` | When importing a module type asset, automatically create manufacturer and/or module type if it doesn't exist |\n| `asset_import_create_inventoryitem_type` | `False` | When importing an inventory type asset, automatically create manufacturer and/or inventory item type if it doesn't exist |\n| `asset_import_create_rack_type` | `False` | When importing a rack type asset, automatically create manufacturer and/or rack type if it doesn't exist |\n| `asset_import_create_tenant` | `False` | When importing an asset, with owner or tenant, automatically create tenant if it doesn't exist |\n| `asset_disable_editing_fields_for_tags` | `{}` | A dictionary of tags and fields that should be disabled for editing. This is useful if you want to prevent editing of certain fields for certain assets. The dictionary is in the form of `{tag: [field1, field2]}`. Example: `{'no-edit': ['serial_number', 'asset_tag']}`. This only affects the UI, the API can still be used to edit the fields. |\n| `asset_disable_deletion_for_tags` | `[]` | List of tags that will disable deletion of assets. This only affects the UI, not the API. |\n| `asset_custom_fields_search_filters` | `{}` | A dictionary of custom fields and lookup types that will be added to the search filters for assets. The dictionary is in the form of `{field: [lookup_type]}`. Example: `{'asset_mac': ['icontains', 'exact']}`. |\n| `asset_warranty_expire_warning_days` | `90` | Days from warranty expiration to show as warning in Warranty remaining field |\n| `prefill_asset_name_create_inventoryitem` | `False` | When hardware inventory item is created from an asset, prefill the InventoryItem name to match the asset name. |\n| `prefill_asset_tag_create_inventoryitem` | `False` | When hardware inventory item is created from an asset, prefill the tags to match the tags associated to the asset. |\n\nYou can extend or define your own status choices for Asset, via [`FIELD_CHOICES`](https://docs.netbox.dev/en/stable/configuration/data-validation/#field_choices) setting in Netbox:\n\n```\nFIELD_CHOICES = {\n 'netbox_inventory.Asset.status+': (\n ('repair', 'In repair', 'orange'),\n ),\n}\n```\n\nIf you add more statuses, you should also adjust `used_additional_status_names` and `stored_additional_status_names` settings.\n\n## Common questions\n\n### I'd like to attach documents to asset, purchase, supplier, etc\n\nNetbox inventory supports limited file attachments for its various models. You can add images to assets, inventory item types and that is it.\n\nIf you would like to attach various other documents to purchases, deliveries, suppliers... first ask yourself if you really need those documents in netbox or could you use some other tool that is possibly in use in your organization. Netbox itself is not great at managing documents. If you decide to manage documents outside netbox, you can porobably still achieve some sort of integration by using [custom links feature](https://netboxlabs.com/docs/netbox/en/stable/customization/custom-links/) to link from a netbox inventory object directly to a document in your document system.\n\nIf you really want to store document in netbox itself, then consider using [netbox_attachments plugin](https://github.com/Kani999/netbox-attachments). Here is a sample netbox configuration that will allow adding documents to suppliers, purchases and deliveries:\n\n```python\nPLUGINS = [\n 'netbox_inventory',\n 'netbox_attachments',\n]\n\nPLUGINS_CONFIG = {\n 'netbox_attachments': {\n 'apps': ['netbox_inventory',],\n 'display_setting': {\n \"netbox_inventory.supplier\": \"left_page\",\n \"netbox_inventory.purchase\": \"full_width_page\",\n \"netbox_inventory.delivery\": \"righ_page\",\n \"netbox_inventory.asset\": \"hidden\",\n \"netbox_inventory.inventoryitemtype\": \"hidden\",\n \"netbox_inventory.inventoryitemgroup\": \"hidden\",\n },\n },\n}\n```\n\nHere is what it looks like when viewing a purchase:\n\n\n\n## Models\n\nCurrent plugin data model:\n\n\n\n## Screenshots\n\nAsset - List View\n\n\n\nAsset - Individual View\n\n\n\nAsset - Edit / Add View\n\n\n\nAsset - Lots of filtering options\n\n\n\nSuppliers - Individual View\n\n\n\nInventory Item Type - List View\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Inventory asset management in NetBox",
"version": "2.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/ArnesSI/netbox-inventory/issues/",
"Homepage": "https://github.com/ArnesSI/netbox-inventory/"
},
"split_keywords": [
"netbox",
" netbox-plugin",
" inventory"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f81827fe46ecd6d5fb425b122ac7a2e4a7faae75c9037133b475f67f4efaa26e",
"md5": "c2ffaced666a55a44ed2a20d356854c8",
"sha256": "af21a996fa11e81d48ea94619c077f4166c82c73147df554c9a0757db1fc2626"
},
"downloads": -1,
"filename": "netbox_inventory-2.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2ffaced666a55a44ed2a20d356854c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 94692,
"upload_time": "2024-12-18T11:27:34",
"upload_time_iso_8601": "2024-12-18T11:27:34.265030Z",
"url": "https://files.pythonhosted.org/packages/f8/18/27fe46ecd6d5fb425b122ac7a2e4a7faae75c9037133b475f67f4efaa26e/netbox_inventory-2.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5889c5dd491c86d95c1f1855d56f238afc56b8abe30e435156d72fa825f85fc3",
"md5": "9c1abaa6cecdf6073c3484de36092006",
"sha256": "81bc25764c2779d2239f65247b09ee0678874049ea36ff0c78e583ab9ed2b8e0"
},
"downloads": -1,
"filename": "netbox_inventory-2.2.1.tar.gz",
"has_sig": false,
"md5_digest": "9c1abaa6cecdf6073c3484de36092006",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 63905,
"upload_time": "2024-12-18T11:27:35",
"upload_time_iso_8601": "2024-12-18T11:27:35.480925Z",
"url": "https://files.pythonhosted.org/packages/58/89/c5dd491c86d95c1f1855d56f238afc56b8abe30e435156d72fa825f85fc3/netbox_inventory-2.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 11:27:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ArnesSI",
"github_project": "netbox-inventory",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "netbox-inventory"
}
JSON
