nautobot 2.0.4__py3-none-any.whl → 2.1.0b1__py3-none-any.whl

nautobot/docs/user-guide/feature-guides/custom-fields.md

@@ -1,350 +0,0 @@
-# Custom Fields
-
-Custom fields are a convenient method of adding new fields to existing Nautobot models without needing to modify the underlying source code or database schema. For more general information on how custom fields work, refer to the [custom fields model documentation](../platform-functionality/customfield.md).
-
-## When to use Custom Fields
-
-Custom fields are commonly used for fields that need different values across individual objects. For example, a custom field on devices to reference an internal ticket number that inventories each device in Nautobot. If you need a solution for marking multiple objects with a common flag, [tags](../platform-functionality/tag.md) may be a better fit.
-
-## Create a Custom Field
-
-Navigate to the custom fields page by clicking on **Extensibility -> Custom Fields** in the Nautobot menu. Click on **Add** to create a new custom field.
-
-### Custom Field Attributes
-
-+/- 2.0.0
-    CustomField model no longer has a `name` attribute in v2.0. Instead, its pre-existing `label` attribute (unique for all CustomField instances) replaced `name` to be used exclusively for display purposes in the UI.
-
-    CustomField model's `slug` attribute was renamed to `key` (unique for all CustomField instances), which contains a GraphQL-safe string used as the key in the underlying custom field data dictionary.
-
-    These aforementioned changes do not require users to do any manual work as they are properly handled by data migrations during the upgrade from Nautobot v1.x to v2.0. Note that if you have non-GraphQL-safe `slug` values in your database pre-migration, some of the resulting CustomField `key` values might be altered to ensure that `key` values for all CustomField instances are valid and unique.
-  
-#### Label
-
-The label is the human readable label of the custom field that will be displayed on the associated object detail view.
-
-![Custom Field Labels](./images/custom-fields/custom_field_detail_label.png)
-
-#### Grouping
-
-The optional grouping field allows you to group custom fields into collapsible menus.
-
-![Custom Field Grouping](./images/custom-fields/custom_field_detail_grouped.png)
-
-#### Key
-
-The key is used as the key in the underlying custom field data dictionary. This is automatically created from the label if not supplied. The default value should be sufficient for most deployments.
-
-#### Type
-
-The type of data that the custom field will store. Valid choices are documented in the [custom field model documentation](../platform-functionality/customfield.md#creating-custom-fields).
-
-#### Weight
-
-Weight determines how custom fields are sorted in forms and object detail views. Higher-weight fields will be ordered lower on the page; if multiple fields have the same weight, they will be listed alphabetically.
-
-#### Description
-
-The description of a custom field is shown as a mouseover tooltip in object detail views and as help text under form fields.
-
-![Custom Field Edit](./images/custom-fields/custom_field_edit.png)
-
-#### Required
-
-Check the required box if this field cannot be null on the associated objects.
-
-!!! warning
-    If an associated object does not have a valid value assigned to a required custom field, that field must be updated with a valid value before the object can be saved. Try to supply a valid default value when creating required custom fields. Since automatic provisioning is only performed when the assigned content types for a custom field change, if an existing custom field is changed from optional to required the associated objects will need to be updated manually.
-
-#### Default
-
-The default value for the custom field. This form field only accepts JSON data so if you want to set the field default to a string of `foo` you must supply the JSON string `"foo"`. Boolean field valid values are `true` and `false` (all lowercase). Date fields are strings in the format `"YYYY-MM-DD"`. Select and multi-select field default must match one of the field's choices.
-
-!!! note
-    The default value for a select or multi-select field must match one of the existing choices. If the desired default value is not in the list of choices, the choices must be updated and saved before the default can be changed. As a result of this behavior, default values cannot be set on select and multi-select fields when a custom field is created.
-
-#### Filter Logic
-
-+/- 1.4.0
-    Custom field [extended filtering](../platform-functionality/rest-api/filtering.md#lookup-expressions) introduced extended lookup expression filters for `exact` and `icontains`, duplicating the functionality of both the `Strict` and `Loose` settings.
-
-The filter logic setting applies to filtering on custom fields in the UI and API. For example, when filtering in the API to find a device with the custom field `cf1` set to `"abc"` you would query `/api/dcim/devices/?cf_cf1=abc`. If the filter logic setting is set to `Loose` this would match on `"ABC"` and `"abcdef"`. If the filter logic setting is set to `Strict` only devices with the custom field set to exactly "abc" (case sensitive) would be returned. If the filter logic setting is set to `disabled`, no filters will be available for this custom field, including extended lookup filters. The `Loose` and `Strict` settings only change the behavior of the default filter (`cf_customfieldname`) on `text`, `url` and `json` custom fields.
-
-#### Move to Advanced Tab
-
-When selected, the custom field will appear in the "Advanced" tab of the object detail view instead of the default tab.
-
-### Assignment
-
-#### Content Types
-
-The list of content types to add this custom field to. Only models that inherit from the `nautobot.extras.models.customfields.CustomFieldModel` model class can be selected.
-
-!!! note
-    When a custom field is created or associated to a new content type (model), all affected existing objects will be updated to add the custom field. The initial value will be set to the `default` value of the custom field. This update runs as a background task via [Celery](../administration/installation/services.md#worker-service), so it may take a few seconds or more before all objects reflect the new custom field, depending on the size of your database.
-
-### Validation Rules
-
-Validation rules are used for constraining custom fields to specific values.
-
-#### Minimum value
-
-Minimum allowed value for `Integer` fields.
-
-#### Maximum value
-
-Maximum allowed value for `Integer` fields.
-
-#### Validation Regex
-
-Regular expression to enforce on `Text`, `URL`, `Selection` and `Multiple selection` field values. Regex validation is handled by the [python re engine](https://docs.python.org/3/library/re.html) which uses a PCRE or perl-like regular expression syntax. Examples of common regex validations:
-
-Must start with companyname
-
-```no-highlight
-^companyname
-```
-
-Must end with 5 digit zip code
-
-```no-highlight
-[0-9]{5}$
-```
-
-Must only contain digits
-
-```no-highlight
-^\d+$
-```
-
-Must be exactly 8 alphanumeric characters
-
-```no-highlight
-^[0-9a-zA-Z]{8}$
-```
-
-Must be between 8 and 10 alphanumeric characters and underscore
-
-```no-highlight
-^\w+{8,10}$
-```
-
-Must contain anything that is not whitespace
-
-```no-highlight
-\S
-```
-
-### Custom Field Choices
-
-The choices to be presented for `Selection` and `Multiple selection` custom field types. These are displayed in the order of the weight values supplied with the lowest weight on top. If regex validation is being used, these choices must match the regular expression.
-
-![Custom Field Choices](./images/custom-fields/custom_field_choices.png)
-
-![Custom Field Select](./images/custom-fields/custom_field_select.png)
-
-## Editing Custom Fields
-
-Since automatic provisioning is only performed when a custom field's content types change, some changes made to existing custom fields are not reflected on the associated objects automatically. Some examples of cases where this might cause unexpected behavior are changes to the `required`, `default` and validation fields.
-
-If a custom field is created with `required=False` and then later changed to `required=True`, all of the associated objects that do not yet have a value for this field will fail validation the next time they're saved unless updated with a valid value. Similarly, changes to the validation fields for a custom field will not automatically result in changes to affected objects, but may require changes the next time those objects are edited in order to bring them into compliance with the updated validation rules.
-
-If a custom field's `default` value is changed, newly created objects will use the new default, but existing objects that were set to the previous default value will *not* automatically be updated.
-
-## Deleting Custom Fields
-
-Custom fields are removed from associated objects when a content type is removed from the custom field, including when the custom field is deleted. This update runs as a background task via [Celery](../administration/installation/services.md#worker-service), so it may take a few seconds or more before the custom field data is removed from all objects, depending on the size of your database.
-
-## Retrieving Custom Field Data
-
-Custom fields augment an existing model so retrieving custom field values is different from native fields. All custom field data is stored as a dictionary in the model field named `_custom_field_data` but there is a property named `cf` to make accessing this field easier. Example:
-
-### Retrieve Custom Field Data in Nautobot Shell
-
-```py
-# retrieve all custom field data
->>> device.cf
-{'eol_date': '1970-01-01',
- 'support_group': 'Network Operations (555-4357)',
- 'dmz_device': True,
- 'cmdb_id': 12345}
-
-# retrieve a single field
->>> device.cf.get("eol_date")
-'1970-01-01'
-```
-
-The `key` of the custom field is used as the key for the associated object's data dictionary.
-
-### Retrieve Custom Field Data in the Rest API
-
-Custom fields are returned in the API for all supported models in the `custom_fields` key:
-
-??? info "`GET http://localhost:8080/api/dcim/devices/ffd8df99-6d1a-41c3-b19f-b8357eefc481/`"
-
-    ```json
-    {
-      "id": "ffd8df99-6d1a-41c3-b19f-b8357eefc481",
-      ...
-      "custom_fields": {
-        "dmz_device": true,
-        "eol_date": "1970-01-01",
-        "cmdb_id": 12345,
-        "support_group": "Network Operations (555-4357)"
-      }
-    }
-    ```
-
-### GraphQL
-
-#### Retrieve Data for a Custom Field in GraphQL
-
-Individual custom fields can be retrieved in GraphQL queries by using the `cf_<fieldname>` field name format:
-
-```no-highlight
-{
-  devices {
-    cf_support_group
-    name
-    id
-  }
-}
-```
-
-??? info "Example GraphQL output"
-
-    ```json
-    {
-      "data": {
-        "devices": [
-          {
-            "name": "phx-leaf1-1-1",
-            "cf_support_group": "Network Operations (555-4357)",
-            "id": "8bd9ed2b-3774-4806-9d17-c9f21f2c73e4"
-          },
-          {
-            "name": "stl-leaf1-2-1",
-            "cf_support_group": "Network Operations (555-4357)",
-            "id": "b22bb7f4-6a6d-4426-9d27-5dcb0471ed2a"
-          },
-          {
-            "name": "Test Device",
-            "cf_support_group": "Network Testing (555-8080)",
-            "id": "ffd8df99-6d1a-41c3-b19f-b8357eefc481"
-          }
-        ]
-      }
-    }
-    ```
-
-#### Retrieve Data For All Custom Fields in GraphQL
-
-All custom field data can be retrieved in GraphQL queries by using the `_custom_field_data` field:
-
-```no-highlight
-{
-  devices(id:"8bd9ed2b-3774-4806-9d17-c9f21f2c73e4") {
-    name
-    id
-    _custom_field_data
-  }
-}
-```
-
-??? info "Example GraphQL output"
-
-    ```json
-    {
-      "data": {
-        "devices": [
-          {
-            "name": "phx-leaf1-1-1",
-            "id": "8bd9ed2b-3774-4806-9d17-c9f21f2c73e4",
-            "_custom_field_data": {
-              "eol_date": "1970-01-01",
-              "support_group": "Network Operations (555-4357)",
-              "dmz_device": true,
-              "cmdb_id": 12345,
-            }
-          }
-        ]
-      }
-    }
-    ```
-
-#### Filter Queries on Custom Field Data in GraphQL
-
-Queries can also be filtered by custom field values using any of the filters available in the UI and Rest API:
-
-```no-highlight
-# Retrieve devices where custom field support_group
-# does not contain "Network Operations" (case insensitive)
-{
-  devices(cf_support_group__nic: "Network Operations") {
-    name
-    id
-    cf_support_group
-  }
-}
-```
-
-??? info "Example GraphQL output"
-
-    ```json
-    {
-      "data": {
-        "devices": [
-          {
-            "name": "Test Device",
-            "id": "ffd8df99-6d1a-41c3-b19f-b8357eefc481",
-            "cf_support_group": "Network Testing (555-8080)"
-          }
-        ]
-      }
-    }
-    ```
-
-## Modifying Custom Field Data
-
-### Modify Custom Field Data in Nautobot Shell
-
-Custom field data behaves like a python dictionary in the Nautobot Shell. When modifying custom fields through the Nautobot Shell, make sure to use the `.validated_save()` method to save the object to ensure that custom field validation is performed.  Example:
-
-```py
->>> device.cf["support_group"]
-'Network Operations (555-4357)'
->>> device.cf["support_group"] = "Network Testing (555-8080)"
->>> device.validated_save()
->>> device.cf["support_group"]
-'Network Testing (555-8080)'
-```
-
-If you do not use `.validated_save()` when creating or updating objects, the custom field dictionary will not be populated with default values or even empty values and this can lead to unintuitive behaviour.
-
-### Modify Custom Field Data in the Rest API
-
-Individual custom field data can be modified by sending a PATCH to the Rest API and setting the new value in the `custom_fields` key:
-
-```no-highlight
-PATCH http://localhost:8080/api/dcim/devices/ffd8df99-6d1a-41c3-b19f-b8357eefc481/
-{
-    "custom_fields": {
-        "support_group": "Rest API test"
-    }
-}
-```
-
-??? info "Example API output"
-
-    ```json
-    {
-      "id": "ffd8df99-6d1a-41c3-b19f-b8357eefc481",
-      ...
-      "custom_fields": {
-        "dmz_device": true,
-        "eol_date": "1970-01-01",
-        "cmdb_id": 12345,
-        "support_group": "Rest API test"
-      }
-    }
-    ```

nautobot/docs/user-guide/feature-guides/getting-started/creating-devices.md

@@ -1,130 +0,0 @@
-# Creating Devices in Nautobot
-
-Every piece of hardware which is installed within a location or rack exists in Nautobot as a device.
-
-More information on Devices can be found in the [Devices](../../core-data-model/dcim/device.md#devices) section of the Nautobot documentation.
-
-A network Device in Nautobot has a few required attributes:
-
-* A Device Role
-* A Device Type
-    * A Device Type requires a Manufacturer
-* A Location
-    * A Location requires a Location Type
-
-Looking at the list above, there are five objects in Nautobot that must be present prior to creating a related Device.
-The following sections will guide you through how to create each object type.
-
-## Creating a Device Role
-
-Devices can be organized by functional roles, which are fully customizable by the user.
-
-More information on Device Roles can be found in the [Device Roles](../../core-data-model/dcim/device.md#device-roles) section of the Nautobot documentation.
-
-To create a new Device, you will need an existing Device Role or need to create a new Device Role instance.
-
-!!! note
-     You might create roles for core switches, distribution switches, and access switches within your network.
-
-To create a new Device Role:
-
-1. Click on **Devices** in the top navigation menu
-2. Find **Device Roles** on the drop-down menu
-3. Select `+`
-4. In the `Add a new device role` form, populate the `Name`
-5. Click on Create
-
-![Create a device role](../images/getting-started-nautobot-ui/3-create-role.png)
-
-## Creating a Manufacturer
-
-A Manufacturer represents the "make" of a device; e.g. Cisco or Dell. Each device type must be assigned to a manufacturer.
-
-More information on Manufacturers is in the [Manufacturers](../../core-data-model/dcim/devicetype.md#manufacturers) section of the Nautobot documentation.
-
-To create a new Device Type, you will need an existing Manufacturer or need to create a new Manufacturer instance.
-
-To create a new Manufacturer:
-
-1. Click on **Devices** in the top navigation menu
-2. Find **Manufacturers** on the drop-down
-3. Select **+**
-4. In the `Add a new manufacturer` form, populate the `Name`
-5. Click on `Create`
-
-![Create a manufacturer](../images/getting-started-nautobot-ui/2-create-manufacturer.png)
-
-## Creating a Device Type
-
-A device type represents a particular make and model of hardware that exists in the real world.
-Device types define the physical attributes of a device (rack height and depth) and its individual components (console, power, network interfaces, and so on).
-
-More information on Device Types is in the [Device Types](../../core-data-model/dcim/devicetype.md#device-types_1) section of the Nautobot documentation.
-
-To create a new Device, you will need an existing Device Type or need to create a new Device Type instance.
-
-To create a new Device Type:
-
-1. Click on **Devices** in the top navigation menu
-2. Find **Device Types**
-3. Select **+** to go to the `Add a new device type` form
-4. Select the `Manufacturer` from the drop-down selector
-5. Populate the `Model` (name)
-6. Click on `Create`
-
-![Create a device type](../images/getting-started-nautobot-ui/4-create-device-type.png)
-
-## Creating a Location Type
-
-To create a location, you need to specify a Location Type for the location. The Location Type(s) that you define for your network may vary depending on the nature of your organization and its needs, but might include for example "region", "city", "site", "building" and/or "room". Take some time to think about this before you begin entering data as it will be a fundamental aspect of how you record your network in Nautobot.
-
-More information on Location Type is found in the [Locations](../../core-data-model/dcim/locationtype.md#location-types) section of the Nautobot documentation.
-
-To create a new Location Type:
-
-1. Click on **Organization** in the top navigation menu
-2. Find **LocationTypes**
-3. Select **+** to go to the `Add a new location type` form
-4. Select a `Parent` LocationType if needed
-5. Populate the LocationType's `Name`
-6. Select the desired `ContentTypes` for this LocationType (in this case `dcim.device`).
-7. Click on `Create` at the bottom of the form
-
-![Create a location type](../images/getting-started-nautobot-ui/1-create-location-type.png)
-
-## Creating a Location
-
-Once you've established your hierarchy of Location Types, you can begin to create the actual Locations of these types. You generally will start with the most general Locations (for example, if your base Location Type is "Region", you might create an "Americas" location of this type) and work your way down to the most specific Locations (for example, "Room 100 in the Headquarters building").
-
-More information on Locations is found in the [Locations](../../core-data-model/dcim/location.md#locations) section of the Nautobot documentation.
-
-To create a new Device, you will need an existing Location or need to create a new Location instance.
-
-To create a new Location:
-
-1. Click on **Organization** in the top navigation menu
-2. Find **Locations**
-3. Select **+** to go to the `Add a new location` form
-4. Select a `LocationType`
-5. Select a `Parent` Location if needed
-6. Populate the Location's `Name`
-7. Set the `Status` to `Active` in the drop-down selector
-8. Click on `Create` at the bottom of the form (not shown)
-
-![Create a location](../images/getting-started-nautobot-ui/6-create-location.png)
-
-## Creating a Device
-
-To create a new Device:
-
-1. Click on **Devices** in the top navigation menu
-2. Find **Devices**
-3. Select **+** to go to the `Add a new device` form
-4. Populate the `Name`
-5. Select the `Role` from the drop-down selector
-6. Select the `Device Type` from the down-down selector
-7. Select the `Location` from the drop-down selector
-8. Set the `Status` to the appropriate value in the drop-down selector
-9. Click on `Create` at the bottom of the form (not shown)
-
-![Create a device](../images/getting-started-nautobot-ui/5-create-device.png)

nautobot/docs/user-guide/feature-guides/getting-started/creating-location-types-and-locations.md

@@ -1,113 +0,0 @@
-# Location Types and Locations
-
-Location Types describe the hierarchical nature of your organization's infrastructure and is used to organize Locations. They can be nested recursively.
-A Location Type might represent a continent, country, city, campus, or other area.
-
-Locations retain hierarchical nature of Location Types but are more specific. For example, a Location of Location Type continent could be Asia, Europe, Americas and etc. or a Location of Location type city could be London, Tokyo, Manhattan and etc.
-
-Additional information on Location Types is in the [Location Type section of the Nautobot documentation](../../core-data-model/dcim/locationtype.md).
-Additional information on Locations is in the [Location section of the Nautobot documentation](../../core-data-model/dcim/location.md).
-
-In the following exercise, we will create three Location Types and their corresponding locations:
-
-Location Types:
-
-* Continent
-    * Intended to hold Locations that represent Countries in North America
-* Country
-    * Intended to hold Locations that represent Markets in Canada
-* Market
-    * Intended to hold Locations that represent Sites in the Vancouver Market
-* Site
-    * Intended to represent Site Location Type Locations
-
-Locations:
-
-* North America
-    * A location of Location Type Continent
-* Canada
-    * A location of Location Type Country exists within North America
-* Vancouver
-    * A location of Location Type Market exists within Canada
-* Vancouver 1
-    * A location of Location Type Site exists within Vancouver
-
-## Creating Location Types and Locations
-
-To create a Location Type:
-
-1. Click on **Organization** in the top menu
-2. Click on **Location Types** in the **Organization** drop-down menu
-    * From this page you can view any existing Location Types
-3. Click on the blue `+ Add` button
-
-![Location Type page](../images/getting-started-nautobot-ui/7-location-type-page.png)
-
-The screenshots below show the creation of each Location Type.
-
-Continent:
-
-1. Leave the `Parent` blank; **Continent** will be a top-tier Location Type
-2. Populate the `Name` to be `Continent`
-3. Click on the `Create and Add Another` button
-
-Country:
-
-1. Select **Continent** as the `Parent` from the drop-down menu selector
-2. Populate the `Name` to be `Country`
-3. Click on the `Create and Add Another` button
-
-Market:
-
-1. Select **Country** as the `Parent` from the drop-down menu selector
-2. Populate the `Name` to be `Market`
-3. Click on the `Create and Add Another` button
-
-Site:
-
-1. Select **Market** as the `Parent` from the drop-down menu selector
-2. Populate the `Name` to be `Site`
-3. Click on the `Create` button
-
-![Create location type](../images/getting-started-nautobot-ui/1-create-location-type.png)
-
-To create a Location of a certain Location Type:
-
-1. Click on **Organization** in the top menu
-2. Click on **Locations** in the **Organization** drop-down menu
-    * From this page you can view any existing Locations
-3. Click on the blue `+ Add` button
-
-![Location page](../images/getting-started-nautobot-ui/8-location-page.png)
-
-The screenshots below show the creation of each Location.
-
-North America:
-
-1. Leave the `Parent` blank; **North America** will be a top-tier Location
-2. Select **Continent** from the Location Type drop-down menu selector
-3. Populate the `Name` to be `North America`
-4. Click on the `Create and Add Another` button
-
-Canada:
-
-1. Select **Country** from the Location Type drop-down menu selector
-2. Select **North America** as the `Parent` from the drop-down menu selector
-3. Populate the `Name` to be `Canada`
-4. Click on the `Create and Add Another` button
-
-Vancouver:
-
-1. Select **Market** from the Location Type drop-down menu selector
-2. Select **Canada** as the `Parent` from the drop-down menu selector
-3. Populate the `Name` to be `Vancouver`
-4. Click on the `Create and Add Another` button
-
-Vancouver 1:
-
-1. Select **Site** from the Location Type drop-down menu selector
-2. Select **Vancouver** as the `Parent` from the drop-down menu selector
-3. Populate the `Name` to be `Vancouver 1`
-4. Click on the `Create` button
-
-![Create location](../images/getting-started-nautobot-ui/6-create-location.png)

nautobot/docs/user-guide/feature-guides/getting-started/index.md

@@ -1,29 +0,0 @@
-# Introduction and Scope
-
-The audience for this user guide is users new to Nautobot.
-This guide will demonstrate how to use and perform common operations in Nautobot's Web UI.
-
-It is intended to assist the user with:
-
-* Understanding the prerequisites for adding a new Device
-* Creating the necessary prerequisite objects to add a new Device
-* Adding new Devices
-* Adding and understanding Location Types and Locations
-* Adding and understanding Platforms
-* Adding and understanding Tenants and Tenant Groups
-* Adding Interfaces to a Device
-* Adding VLANs and understanding VLAN Groups
-* Understanding IP Address Management (IPAM) in Nautobot
-* How to navigate to the object you are interested in
-* How to use the Search Bar to find the object you are interested in
-
-This guide does not cover every possible operation in Nautobot's Web UI. However, after reading this guide and working through the included exercises, the user should have a good feel for:
-
-* Performing basic tasks
-* How to navigate to a specific object and its related objects
-* The Web UI's general structure and organization
-* Extrapolating to use the Web UI for almost any task
-
-## Requirements
-
-1. A functional Nautobot [installation](../../administration/installation/index.md)