Skip to content

Commit 3d1ee9f

Browse files
mrmrcolemanmrmrcoleman
committed
Updated index.md
1 parent 59bf75b commit 3d1ee9f

File tree

1 file changed

+71
-3
lines changed

1 file changed

+71
-3
lines changed

‎docs/index.md

Lines changed: 71 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323

2424
## Workflow
2525

26-
Let's walk through the above DHCP Scope example, to highlight the steps involved in creating your own Custom Object Type, and then creating instances of that Custom Object Type.
26+
Let's walk through the above DHCP Scope example, to highlight the steps involved in creating your own Custom Object Type, and then interacting with instances of that Custom Object Type.
2727

2828
### Create the Custom Object Type
2929

@@ -51,21 +51,89 @@ Let's walk through the above DHCP Scope example, to highlight the steps involved
5151
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`.
5252
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`.
5353
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`.
54+
6. Then click `Create`.
5455

56+
> [!NOTE]
57+
> 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.
5558
59+
### Interacting with Custom Objects
5660

61+
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.
5762

63+
> [!NOTE]
64+
> 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.
5865
66+
#### Creating a new Custom Object
5967

68+
Now that you've created your `DHCP Scope` Custom Object Type, let's go ahead and create a new `DHCP Scope`.
6069

70+
1. On the DHCP Scope detail view, click `+ Add` in the bottom right
71+
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`.
72+
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.
6173

74+
#### Standard list views for Custom Objects
6275

76+
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 as you would with other NetBox objects.
6377

78+
1. On the `DHCP Scope` detail view page, right click on `Dhcp_scopes` (you can also navigate to `plugins/custom-objects/dhcp_scope/`)
79+
2. Now you will see a standard NetBox list view of your `dhcp_scopes` with the standard options including `Configure Table`, `+ Add`, etc
80+
81+
> [!NOTE]
82+
> 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.
83+
84+
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/`
85+
86+
```
87+
HTTP 200 OK
88+
Allow: GET, POST, HEAD, OPTIONS
89+
Content-Type: application/json
90+
Vary: Accept
91+
92+
{
93+
"count": 1,
94+
"next": null,
95+
"previous": null,
96+
"results": [
97+
{
98+
"id": 1,
99+
"url": "http://localhost:8001/api/plugins/custom-objects/dhcp_scope/1/",
100+
"range": {
101+
"id": 1,
102+
"url": "http://localhost:8001/api/ipam/ip-ranges/1/",
103+
"display": "192.168.0.1-100/24",
104+
"family": {
105+
"value": 4,
106+
"label": "IPv4"
107+
},
108+
"start_address": "192.168.0.1/24",
109+
"end_address": "192.168.0.100/24",
110+
"description": ""
111+
}
112+
}
113+
]
114+
}
115+
```
116+
117+
### Deletions
118+
119+
#### Deleting Custom Object Types
120+
121+
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.
122+
123+
#### Deleting Custom Object Type Fields
124+
125+
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.
126+
127+
#### Deleting Custom Objects
128+
129+
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.
64130

65131
## Known Limitations
66132

67-
There are currently a few limitations to the functionality provided by this plugin that are worth highlighting. We hope to address these in future releases.
133+
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.
134+
135+
Below is a handy list of the main areas we are working on.
68136

69-
* **Branches may not persist across minor version upgrades of NetBox.** Users are strongly encouraged to merge or remove all open branches prior to upgrading to a new minor release of NetBox (e.g. from v4.1 to v4.2). This is because database migrations introduced by the upgrade will _not_ be applied to branch schemas, potentially resulting in an invalid state. However, it should be considered safe to upgrade to new patch releases (e.g. v4.1.0 to v4.1.1) with open branches.
137+
* **Custom Objects do not show up in the left-navigation pane.** Users are strongly encouraged to merge or remove all open branches prior to upgrading to a new minor release of NetBox (e.g. from v4.1 to v4.2). This is because database migrations introduced by the upgrade will _not_ be applied to branch schemas, potentially resulting in an invalid state. However, it should be considered safe to upgrade to new patch releases (e.g. v4.1.0 to v4.1.1) with open branches.
70138

71139
* **Open branches will not reflect newly installed plugins.** Any branches created before installing a new plugin will not be updated to support its models. Note, however, that installing a new plugin will generally not impede the use of existing branches. Users are encouraged to install all necessary plugins prior to creating branches. (This also applies to database migrations introduced by upgrading a plugin.)

0 commit comments

Comments
 (0)