Skip to content

Commit 59bf75b

Browse files
mrmrcolemanmrmrcoleman
committed
Initial docs commit
1 parent 8b3e74a commit 59bf75b

File tree

3 files changed

+181
-101
lines changed

3 files changed

+181
-101
lines changed

‎README.md

Lines changed: 15 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,113 +1,27 @@
1-
# netbox-service-mappings
2-
Service Mappings plugin
1+
# NetBox Custom Objects
32

4-
1. Add `netbox_custom_objects` to `PLUGINS` in `configuration.py`.
3+
This [NetBox](https://netboxlabs.com/products/netbox/) plugin introduces the ability to create new object types in NetBox so that users can add models to suit their own needs. NetBox users have been able to extend the NetBox data model for some time using both Tags & Custom Fields and Plugins. Tags and Custom Fields are easy to use, but they have limitations when used at scale, and Plugins are very powerful but require Python/Django knowledge, and ongoing maintenance. Custom Objects provides users with a no-code "sweet spot" for data model extensibility, providing a lot of the power of NetBox plugins, but with the ease of use of Tags and Custom Fields.
4+
5+
You can find further documentation [here](docs/index.md).
6+
7+
## Requirements
8+
9+
* NetBox v4.2 or later
10+
* PostgreSQL 12 or later
11+
12+
## Installation
13+
14+
1. Add `netboxlabs_netbox_custom_objects` to `PLUGINS` in `configuration.py`.
515

616
```python
717
PLUGINS = [
818
# ...
9-
'netbox_custom_objects',
19+
'netboxlabs_netbox_custom_objects',
1020
]
1121
```
1222

1323
2. Run NetBox migrations:
1424

1525
```
1626
$ ./manage.py migrate
17-
```
18-
19-
## API
20-
21-
The three relevant models making up the Service Mappings system can be manipulated through CRUD operations using the
22-
standard NetBox API, using endpoints located at: `/api/plugins/service-mappings/`
23-
24-
```json
25-
{
26-
"mapping-type-fields": "http://127.0.0.1:8000/api/plugins/service-mappings/mapping-type-fields/",
27-
"mapping-types": "http://127.0.0.1:8000/api/plugins/service-mappings/mapping-types/",
28-
"mappings": "http://127.0.0.1:8000/api/plugins/service-mappings/mappings/"
29-
}
30-
```
31-
32-
### Service Mapping Types
33-
34-
Create a Service Mapping Type with a POST call to `/api/plugins/service-mappings/mapping-types/` using a payload
35-
similar to the following:
36-
37-
```json
38-
{
39-
"name": "My Service Type",
40-
"slug": "my-service-type"
41-
}
42-
```
43-
44-
### Mapping Type Fields
45-
46-
Then define the schema of the Service Mapping Type by creating fields of various types, with POST requests to
47-
`/api/plugins/service-mappings/mapping-type-fields/`:
48-
49-
```json
50-
{
51-
"custom_object_type": 9,
52-
"name": "internal_id",
53-
"label": "Internal ID",
54-
"type": "integer",
55-
"options": {
56-
"min": 0,
57-
"max": 9999
58-
}
59-
}
60-
```
61-
62-
Available `type` values are: `char`, `integer`, `boolean`, `date`, `datetime`, `object`, and `multiobject`. Attributes for
63-
specific field types can be specified using the `options` object (details TBD).
64-
65-
If the type is `object` or `multiobject`, the content type of the field is designated using the `app_label` and `model` attributes
66-
as shown here:
67-
68-
```json
69-
{
70-
"custom_object_type": 9,
71-
"name": "single_device",
72-
"label": "Single Device",
73-
"type": "object",
74-
"app_label": "dcim",
75-
"model": "device"
76-
}
77-
```
78-
79-
```json
80-
{
81-
"custom_object_type": 9,
82-
"name": "device_list",
83-
"label": "Device List",
84-
"type": "multiobject",
85-
"app_label": "dcim",
86-
"model": "device"
87-
}
88-
```
89-
90-
!!! note
91-
An `object` or `multiobject` field can point to any Custom Object, as well as any other existing object internal to NetBox.
92-
Use an `app_label` of `netbox_custom_objects` and a `model` of `customobject`.
93-
94-
### Custom Objects
95-
96-
Once the schema of a Custom Object Type is defined through its list of fields, you can create Custom Objects,
97-
which are instances of Custom Object Types with specific values populated into the fields defined in the schema.
98-
Create a Custom Object with a POST to `/api/plugins/custom-objects/custom-objects/`:
99-
100-
```json
101-
{
102-
"custom_object_type": 9,
103-
"name": "My Object",
104-
"data": {
105-
"internal_id": 102,
106-
"device_list": [34, 1],
107-
"single_device": 16
108-
}
109-
}
110-
```
111-
112-
PATCH requests can be used to update all the above objects, as well as DELETE and GET operations, using the detail
113-
URL for each model, i.e. `/api/plugins/custom-objects/custom-objects/15/`
27+
```

‎docs/api.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
## API
2+
3+
The three relevant models making up the Service Mappings system can be manipulated through CRUD operations using the
4+
standard NetBox API, using endpoints located at: `/api/plugins/service-mappings/`
5+
6+
```json
7+
{
8+
"mapping-type-fields": "http://127.0.0.1:8000/api/plugins/service-mappings/mapping-type-fields/",
9+
"mapping-types": "http://127.0.0.1:8000/api/plugins/service-mappings/mapping-types/",
10+
"mappings": "http://127.0.0.1:8000/api/plugins/service-mappings/mappings/"
11+
}
12+
```
13+
14+
### Service Mapping Types
15+
16+
Create a Service Mapping Type with a POST call to `/api/plugins/service-mappings/mapping-types/` using a payload
17+
similar to the following:
18+
19+
```json
20+
{
21+
"name": "My Service Type",
22+
"slug": "my-service-type"
23+
}
24+
```
25+
26+
### Mapping Type Fields
27+
28+
Then define the schema of the Service Mapping Type by creating fields of various types, with POST requests to
29+
`/api/plugins/service-mappings/mapping-type-fields/`:
30+
31+
```json
32+
{
33+
"custom_object_type": 9,
34+
"name": "internal_id",
35+
"label": "Internal ID",
36+
"type": "integer",
37+
"options": {
38+
"min": 0,
39+
"max": 9999
40+
}
41+
}
42+
```
43+
44+
Available `type` values are: `char`, `integer`, `boolean`, `date`, `datetime`, `object`, and `multiobject`. Attributes for
45+
specific field types can be specified using the `options` object (details TBD).
46+
47+
If the type is `object` or `multiobject`, the content type of the field is designated using the `app_label` and `model` attributes
48+
as shown here:
49+
50+
```json
51+
{
52+
"custom_object_type": 9,
53+
"name": "single_device",
54+
"label": "Single Device",
55+
"type": "object",
56+
"app_label": "dcim",
57+
"model": "device"
58+
}
59+
```
60+
61+
```json
62+
{
63+
"custom_object_type": 9,
64+
"name": "device_list",
65+
"label": "Device List",
66+
"type": "multiobject",
67+
"app_label": "dcim",
68+
"model": "device"
69+
}
70+
```
71+
72+
!!! note
73+
An `object` or `multiobject` field can point to any Custom Object, as well as any other existing object internal to NetBox.
74+
Use an `app_label` of `netbox_custom_objects` and a `model` of `customobject`.
75+
76+
### Custom Objects
77+
78+
Once the schema of a Custom Object Type is defined through its list of fields, you can create Custom Objects,
79+
which are instances of Custom Object Types with specific values populated into the fields defined in the schema.
80+
Create a Custom Object with a POST to `/api/plugins/custom-objects/custom-objects/`:
81+
82+
```json
83+
{
84+
"custom_object_type": 9,
85+
"name": "My Object",
86+
"data": {
87+
"internal_id": 102,
88+
"device_list": [34, 1],
89+
"single_device": 16
90+
}
91+
}
92+
```
93+
94+
PATCH requests can be used to update all the above objects, as well as DELETE and GET operations, using the detail
95+
URL for each model, i.e. `/api/plugins/custom-objects/custom-objects/15/`

‎docs/index.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# NetBox Custom Objects
2+
3+
[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.
4+
5+
## Features
6+
7+
* Easily create new objects in NetBox - via the GUI, the REST API or `pynetbox`
8+
9+
* Each custom object inherits standard NetBox model functionality like REST APIs, list views, detail views and more
10+
11+
* 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.
12+
13+
* Fields on Custom Objects can model additional behaviour like uniqueness, default values, layout hints, required fields, and more.
14+
15+
## Terminology
16+
17+
* A **Custom Object Type** is new object in NetBox. For example you may decide to add a new Custom Object Type to model a `DHCP Scope`. In NetBox Plugin terminology this is equivalent to a 'model'.
18+
19+
* A **Custom Object Type Field** a field on a given Custom Object Type. For example, you may decide to add a `range` field to your `DHCP Scope` Custom Object Type.
20+
21+
* A **Custom Object** is an instance of a Custom Object Type you have created. For example, having created your minimal `DHCP Scope` Custom Object Type, you can now create new DHCP Scopes. Each DHCP Scope you create is a Custom Object.
22+
23+
24+
## Workflow
25+
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.
27+
28+
### Create the Custom Object Type
29+
30+
1. Navigate to the Custom Objects plugin in the left navigation pane and click the `+` next to `Custom Object Types`
31+
2. Choose a name for your Custom Object Type. In this case we will choose `dhcp_scope`
32+
33+
> [!TIP]
34+
> Give your Custom Object Types URL friendly names
35+
36+
> [!TIP]
37+
> 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`.
38+
> This behaviour can be overridden using the `Readable plural name` field. For example if you have a Custom Object Type called `Child` you can use the `Readable plural name` field to specify `Children` instead of `Childs`
39+
40+
3. Click `Create`
41+
42+
### Adding fields to the Custom Object Type
43+
44+
1. After creating your Custom Object Type you will be taken to the Custom Object Type detail view. To add a field, click `+ Add Field`
45+
46+
> [!TIP]
47+
> 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.
48+
> 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.
49+
50+
2. Specify a `Name` for your field, in this case we'll choose a URL friendly value: `range`.
51+
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`.
52+
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`.
53+
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+
55+
56+
57+
58+
59+
60+
61+
62+
63+
64+
65+
## Known Limitations
66+
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.
68+
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.
70+
71+
* **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)