You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ You can find further documentation [here](https://github.com/netboxlabs/netbox-c
6
6
7
7
## Requirements
8
8
9
-
* NetBox v4.2 or later
9
+
* NetBox v4.4-beta or later
10
10
11
11
## Installation
12
12
@@ -30,11 +30,12 @@ PLUGINS = [
30
30
```
31
31
$ ./manage.py migrate
32
32
```
33
+
33
34
4. Restart NetBox
34
35
```
35
36
sudo systemctl restart netbox netbox-rq
36
37
```
37
38
38
39
## Known Limitations
39
40
40
-
The Public Preview of NetBox Custom Objects is under active development as we proceed towards the General Availability release around NetBox 4.4. The best place to look for the latest list of known limitations is the [issues](https://github.com/netboxlabs/netbox-custom-objects/issues) list on the GitHub repository. These include features like Tags, Import/Export, Bulk Edit, Text Search and Branching.
41
+
The Public Preview of NetBox Custom Objects is under active development as we proceed towards the General Availability release around NetBox 4.4. The best place to look for the latest list of known limitations is the [issues](https://github.com/netboxlabs/netbox-custom-objects/issues) list on the GitHub repository.
`/api/plugins/custom-objects/custom-object-type-fields/`, referencing the ID of the Custom Object Type you just created:
32
32
33
33
```json
34
34
{
@@ -166,8 +166,44 @@ The response will include the created object with its assigned ID and additional
166
166
}
167
167
```
168
168
169
-
PATCH requests can be used to update all the above objects, as well as DELETE and GET operations, using the detail
170
-
URL for each model:
169
+
### API output in the browser
170
+
171
+
As with other NetBox objects, you can also view the API output for given Custom Objects by prepending `api/` to the URL, e.g. `api/plugins/custom-objects/dhcp_scope/`
[NetBox](https://github.com/netbox-community/netbox) is the world's leading source of truth for infrastructure, featuring an extensive and complex data model. But sometimes it can be useful to extend the NetBox data model to fit specific organizational needs. This plugin introduces a new paradigm for NetBox to help overcome these challenges: custom objects.
3
+
[NetBox](https://github.com/netbox-community/netbox) is the world's leading source of truth for infrastructure, featuring an extensive data model. Sometimes it can be useful to extend the NetBox data model to fit specific organizational needs. The Custom Objects plugin introduces a new paradigm for NetBox to help overcome these challenges, allowing NetBox adminstrators to extend the NetBox data model without writing a line of code.
4
4
5
5
For additional documentation on the REST API, go [here](api.md).
6
6
7
-
## Features
8
-
9
-
* Easily create new objects in NetBox - via the GUI, the REST API or `pynetbox`
10
-
11
-
* Each custom object inherits standard NetBox model functionality like REST APIs, list views, detail views and more
7
+
> [!TIP]
8
+
> NetBox Custom Objects is still in Public Preview. If you hit any problems please check the [exiting issues](https://github.com/netboxlabs/netbox-custom-objects/issues) before creating a new one. If you're unsure, start a [discussion](https://github.com/netboxlabs/netbox-custom-objects/discussions).
12
9
13
-
* Custom Objects can include fields of all standard types, like text, decimal, integer, boolean, choicesets, and more, but can also have 1-1 and 1-many fields to core NetBox models, plugin models and other Custom Object Types you have created.
10
+
## Features
14
11
15
-
* Fields on Custom Objects can model additional behaviour like uniqueness, default values, layout hints, required fields, and more.
12
+
* Easily create new object types in NetBox - via the GUI, the REST API or `pynetbox`
13
+
14
+
* Each Custom Object Type inherits standard NetBox model functionality including:
15
+
* List views, details views, etc
16
+
* Group-able fields
17
+
* An entry in the left pane for intuitive navigation
18
+
* Create Custom Fields that point to Custom Object Types
19
+
* REST APIs
20
+
* Search
21
+
* Changelogging
22
+
* Bookmarks
23
+
* Custom Links
24
+
* Cloning
25
+
* Import/Export
26
+
* EventRules
27
+
* Notifications
28
+
* Journaling
29
+
* Tags
30
+
31
+
* Custom Object Types can include 1-1 and 1-many Custom Object Type Fields of all standard types, like text, decimal, integer, boolean, etc, and can also include fields of choiceset, core NetBox models, plugin models and other Custom Object Types you have created.
32
+
33
+
* Custom Object Type Fields can model additional behaviour like uniqueness, default values, layout hints, required fields, and more.
16
34
17
35
## Terminology
18
36
@@ -33,7 +51,7 @@ Let's walk through the above DHCP Scope example, to highlight the steps involved
33
51
2. Choose a name for your Custom Object Type. In this case we will choose `dhcp_scope`
34
52
35
53
> [!TIP]
36
-
> Give your Custom Object Types URL friendly names
54
+
> Give your Custom Object Types URL friendly names
37
55
38
56
> [!TIP]
39
57
> By default the plural name for your Custom Object Type will be its name with `s` appended. So for example, multiple `dhcp_scope` Custom Objects will be referred to as `dhcp_scopes`.
@@ -49,83 +67,46 @@ Let's walk through the above DHCP Scope example, to highlight the steps involved
49
67
> The `Primary` flag on Custom Object Type Fields is used for Custom Object naming. By default when you create a Custom Object it will be called `<Custom Object Type Name> <Custom Object ID>`. So in this example the first `dhcp_scope` we create would be called `dhcp_scope 1` and so on.
50
68
> Setting `Primary` to `true` on a Custom Object Type Field causes the value of that field to be used as the name for the Custom Object.
51
69
70
+
> [!TIP]
71
+
> Uniqueness cannot be enforced for Custom Object Type Fields of type `MultiObject` or `boolean`
72
+
73
+
52
74
2. Specify a `Name` for your field, in this case we'll choose a URL friendly value: `range`.
53
75
3. Specify the `Label` for your field. This is a human readable name that will be used in the GUI. In this case we'll choose `DHCP Range`.
54
76
4. Choose a `Type` for your field. In this case we want our `range` field to be a 1-1 reference to a built-in NetBox object type, so we choose `Object`.
55
77
5. Then we need to specify which type of built-in object our `range` field will reference. Scroll down to `Related object type` and choose `IPAM > IP Range`.
56
78
6. Then click `Create`.
57
79
58
-
> [!NOTE]
59
-
> Some behaviour on Custom Object Type Fields is still under active development during the Public Preview. Please check the outstanding [issues](https://github.com/netboxlabs/netbox-custom-objects/issues) and [discussions](https://github.com/netboxlabs/netbox-custom-objects/discussions) before creating a new one.
80
+
60
81
61
82
### Interacting with Custom Objects
62
83
63
84
Typically, NetBox admins would be responsible for thinking through modelling requirements, and creating new Custom Object Types for other users to use in their day to day work. You have now created a new `DHCP Scope` Custom Object Type, so let's look at how others would interact with them.
64
85
65
-
> [!NOTE]
66
-
> When NetBox Custom Objects reaches General Availability, it will be possible to add new Custom Object Types in the left navigation pane, like other core NetBox or Plugin objects. Until then the instructions below outline the correct approach.
67
-
68
86
#### Creating a new Custom Object
69
87
70
88
Now that you've created your `DHCP Scope` Custom Object Type, let's go ahead and create a new `DHCP Scope`.
71
89
72
-
1.On the DHCP Scope detail view, click `+ Add` in the bottom right
90
+
1.Under the NetBox Custom Objects plugin in the left side navigation you will now see `Dhcp_scopes`. Click on `+` next to your new Custom Object Type.
73
91
2. As you added a single field, called `Range` of type `IPAM > IP Range` you are prompted to specify a range. Go and ahead and select one, then click `Create`.
74
-
3. You'll now see that your new `dhcp_scope` has been added into the list view at the bottom of the `DHCP Scope`Custom Object Type page.
92
+
3. You're now taken to the detail view for your new `DHCP Scope`object.
75
93
76
94
#### Standard list views for Custom Objects
77
95
78
-
As you saw in the previous step, all Custom Objects of a given Custom Object Type are viewable at the bottom of the Custom Object Type's detail page, but you can also view standard list views:
79
-
80
-
1. On the `DHCP Scope` detail view page, right click on `Dhcp_scopes` (you can also navigate to `plugins/custom-objects/dhcp_scope/`)
81
-
2. Now you will see a standard NetBox list view of your `dhcp_scopes` with the standard options including `Configure Table`, `+ Add`, etc
82
-
83
-
> [!NOTE]
84
-
> When NetBox Custom Objects reaches General Availability, it will be possible to navigate to Custom Object list views in the left navigation pane, as with core NetBox or Plugin objects. Until then the instructions above outline the correct approach.
85
-
86
-
3. As with other NetBox objects, you can also view the API output for given Custom Objects by prepending `api/` to the URL, e.g. `api/plugins/custom-objects/dhcp_scope/`
As with core NetBox objects, Custom Objects have their own list views. To see all your `DHCP Scopes` you can just click on your Custom Object Type in the Custom Object plugin section in the left side navigation. In the example above, click on `Custom Objects` -> `OBJECTS` -> `Dhcp_scopes`
97
+
98
+
You will now see a standard NetBox list view for your new Custom Objects with the standard options including `Configure Table`, `+ Add`, Import, Export, etc
118
99
119
100
### Deletions
120
101
121
102
#### Deleting Custom Object Types
122
103
123
-
When deleting a Custom Object Type, you are in effect, deleting an entire table in the database and should be done with caution. You will be warned about the impact of before you proceed, and this is why we suggest that only admins should be allowed to interact with Custom Objects Types.
104
+
When deleting a Custom Object Type, you are in effect, deleting an entire table in the database and this should be done with caution. You will be warned about the impact of before you proceed, and this is why we suggest that only admins should be allowed to interact with Custom Objects Types.
124
105
125
106
#### Deleting Custom Object Type Fields
126
107
127
-
When deleting a Custom Object Type Field, you are in effect, deleting an entire column in the database and should be done with caution. You will be warned about the impact of before you proceed, and this is why we suggest that only admins should be allowed to interact with Custom Objects Type Fields.
108
+
When deleting a Custom Object Type Field, you are in effect, deleting an entire column in the database and this should be done with caution. You will be warned about the impact of before you proceed, and this is why we suggest that only admins should be allowed to interact with Custom Objects Type Fields.
128
109
129
110
#### Deleting Custom Objects
130
111
131
-
Deleting Custom Objects, like a specific DHCP Scope object you have created, works just like it does for normal NetBox objects. You can delete a Custom Object on the Custom Object's detail view, or via one of the two list views. We recommend that you follow your usual permissions practices here.
112
+
Deleting Custom Objects, like a specific DHCP Scope object you have created, works just like it does for normal NetBox objects. You can delete a Custom Object on the Custom Object's detail view, or via the list view. We recommend that you follow your usual permissions practices here.
0 commit comments