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

nautobot/docs/user-guide/feature-guides/ip-address-merge-tool.md

@@ -1,63 +0,0 @@
-# Duplicate IP Address Merge Tool
-
-In order to satisfy new uniqueness constraints, upgrading from Nautobot v1.x to v2.0 can create duplicate `IPAddress` objects in the existing database. This tool is designated to help users to reduce unnecessary duplicate `IPAddress` objects by merging them into a single IP Address with all the desired attributes.
-
-## When to use this tool
-
-After upgrading to Nautobot v2.0 and running the data migrations necessary, duplicate `IPAddress` objects might exist in your database. We define duplicate `IPAddress` objects as those which have the same `host` attribute but exist in different `namespaces`. If you have no use case to keep those duplicate `IPAddress` objects around, we recommend you to use this tool to de-duplicate those `IPAddress` objects and keep your database clean and manageable. But if you do have reasons to maintain duplicate `IPAddress` objects, this tool is not for you.
-
-!!! important
-    One of the possible reasons to maintain duplicate `IPAddress` objects can be that you have use cases for duplicate `IPAddress` objects with different `nat_inside` attributes. Only one `nat_inside` IP address can be assigned per object.
-
-## How to access this tool
-
-To use this tool:
-
-1. Go to the `IPAM` tab on the navigation menu and click on `IP Addresses`. This will take you to the list view of all `IPAddress` objects that exist in the database.
-2. On the top right of the page, you will find a group of buttons representing different available actions and the first one should be `Find and Merge Duplicate IPs`.
-3. Click on that button to access the tool.
-
-![Merge Button](./images/ip-address-merge-tool/ip_merge_button.png)
-
-## How it works
-
-1. If you de-select all other duplicates and attempt to merge, nothing will happen (the operation is a no-op) and the object will be skipped over as if you had clicked the `Skip and Go to the Next Duplicate` button.
-2. All of the selected `IPAddress` objects will be deleted and a new `IPAddress` object with all of the desired attributes will be created.
-3. All `Interface` assignments of the deleted `IPAddress` objects will be automatically updated to reference the newly created `IPAddress` object.
-4. All `VMInterface` assignments of the deleted `IPAddress` objects will be automatically updated to reference the newly created `IPAddress` object.
-5. The newly created `IPAddress` object will be added to `IPAddress` assignments of related `Service` objects.
-6. `primary_ip4/primary_ip6` of `Devices` that are referencing the deleted `IPAddress` objects will be automatically updated to reference the newly created `IPAddress` object.
-
-## How to use this tool
-
-Clicking on the `Find and Merge Duplicate IPs` button will automatically query your database for duplicate `IPAddress` objects and group them by their respective `host` values. The tool will present the duplicate `IPAddress` objects in order from lowest to highest `mask_length` values.
-
-![IP Address Merge View](./images/ip-address-merge-tool/merge_view.png)
-
-### Merging all presented IP addresses
-
-When a set of potentially duplicate `IPAddress` objects are found, the tool will present them and all of their editable attributes as a table. Select the desired value for each attribute and click on the `Merge and Go to the Next Duplicate` button. Nautobot will combine all of the selected `IPAddress` objects into a new `IPAddress` with the attributes you selected.
-If more duplicate addresses are present, with a different `host` value, you will be presented with a new table showing the next set of duplicates, and can repeat this process as needed.
-
-![Merging All Duplicate IPs](./images/ip-address-merge-tool/merge_button.png)
-
-### Merging a subset of presented IP addresses
-
-If you want to keep some of the `IPAddress` objects as distinct records but merge others, you can uncheck the check-boxes in the first column corresponding to the objects you do not wish to merge. From the remaining checked records, select the desired attributes and click on the `Merge and Go to the Next Duplicate` button. This operation will only combine the `IPAddress` objects that you have checked.
-
-![Merging Some Duplicate IPs](./images/ip-address-merge-tool/unselect_ips.png)
-
-!!! note
-    Unchecking a given `IP Address` prevents its attribute values from being selected for the merge. Moreover, if there are not at least two boxes checked, there is no merging to perform, and so clicking on the `Merge and Go to the Next Duplicate` button will proceed to the next set of duplicate IP addresses without making any changes to the current set.
-
-### Skip Merging All Duplicate IP Addresses Presented
-
-If you decide that these `IPAddress` objects presented do not need to be merged, you can click on the `Skip and Go to the Next Duplicate` button to skip merging these `IPAddress` objects and go to the next set of duplicate `IPAddress` objects with a different `host` value.
-
-![Skip Merging Duplicate IPs](./images/ip-address-merge-tool/skip_button.png)
-
-### No more Duplicate IP Addresses
-
-If you have gone through all duplicate `IPAddress` objects, you will be taken back to the list view of `IPAddress` objects with a message indicating that `No additional duplicate IPs found.`.
-
-![No More Duplicate IPs](./images/ip-address-merge-tool/no_more_dup_ips.png)

nautobot/docs/user-guide/feature-guides/relationships.md

@@ -1,125 +0,0 @@
-# Relationships
-
-Relationships are defined between one (or more) objects in your source of truth to reflect business logic or other relationships that may be useful to you but that haven't been defined. Relationships define specific links between objects that might be specific to your network or data.
-
-For more technical details on how to use this feature, please see the documentation on [Relationships](../platform-functionality/relationship.md).
-
-## Relationship details
-
-This table defines repository parameters that are required to establish a relationship.
-
-|Field|Explanation|
-|:--|:--|
-|Label|Label of the relationship as displayed to users.|
-|Key|Internal relationship key. Please use underscores rather than dashes.|
-|Description|(Optional) Meaningful description to provide additional relationship details.|
-|[Type](../platform-functionality/relationship.md#relationship-types)|Cardinality of this relationship.|
-|Source type|The source object type to which this relationship applies.|
-|Source Label|(Optional) Label for related destination objects, as displayed on the source object.|
-|Source filter|(Optional) Filterset filter matching the applicable source objects of the selected type.|
-|Destination type|The destination object type to which this relationship applies.|
-|Destination Label|(Optional) Label for related destination objects, as displayed on the destination object.|
-|Destination filter|(Optional) Filterset filter matching the applicable destination objects of the selected type.|
-
-+/- 2.0.0
-    Relationship model now uses its `label` attribute (unique for all Relationship instances) exclusively for display purposes in the UI.
-
-    Relationship's `slug` attribute was renamed to `key` (unique for all Relationship instances), which contains a GraphQL-safe string used as the key in the underlying relationship data dictionary.
-
-    These 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. If you have duplicate Relationship `slug` values in your database pre-migration, some of the Relationship `key` values might altered to ensure that `key` values for all Relationship instances are unique.
-
-As seen in the table above relationships offers many additional optional options for more advanced functionality, those options will be discussed further during this user guide.
-
-## Using a Relationship
-
-This section will focus on examples relationships.
-
-### Adding a Relationship
-
-To create a relationship, navigate to **Extensibility > Data Management > Relationships**
-
-A simple relationship between `Device to VLAN` which is a `many-to-many` relationship. This relationship is `many-to-many` because more than one Devices can be assigned more than one VLANs. This relationship object is shown below.
-
-![many-to-many example](./images/relationships/01-relationships.png)
-
-### Extensibility of a Relationship
-
-Now that this relationship is created we can navigate over to a Device detail view and we see `VLANs` is now listed under the `Relationships` section.
-
-![device-to-vlan relationship](./images/relationships/02-relationships.png)
-
-What if your business requirements or terminology differs from what you want? For example lets say you want `VLANs` to be called `VIDs`, you can simply update the relationship `source label` field based on your needs.
-
-You can see now the relationship name is `VIDs` instead of `VLANs`.
-
-![updated-source-label](./images/relationships/03-relationships.png)
-
-!!! info
-    In a similar fashion the destination label can be changed to meet business requirements.
-
-Business requirements are one concept to take into account when making `labels`, but making the relationship data more meaningful is an option worth exploring.
-
-In the snippet below the source label was updated to `Configured VLANs`. The result on the device detail view is evident and provides additional context that is otherwise missing. `VLANs: 3 VLANs` doesn't give the same context as `Configured VLANs: 3 VLANs`.
-
-![updated-source-label-expanded](./images/relationships/10-relationships.png)
-
-In a similar fashion the destination label can make it move evident that these VLANs are in use on the devices. A destination label `In use on devices: 3 devices` is far superior to the default of `Devices: 3 devices`. Providing these labels makes it easier for users of the system to understand the relationships, especially if they weren't the initial implementor of the relationship.
-
-![updated-destination-label-expanded](./images/relationships/11-relationships.png)
-
-Next, some of the visibility options will be discussed. The first option to be demonstrated is the ability to `Move to Advanced tab`. In some cases a particular relationship may not be relevant to the typical user (maybe it's used exclusively in automation) and so you may want the relationship data to be displayed on the `Advanced` tab instead of within the default detail view of the object.
-
-First the option needs to be enabled.
-![advanced-tab-relationship](./images/relationships/04-relationships.png)
-
-Once the option is enabled you will see the relationship is now moved to the `Advanced` tab.
-
-![advanced-tab-relationship-view](./images/relationships/05-relationships.png)
-
-Another visibility option is the `Hide on Source Object` and `Hide on Destination Object`, these do exactly what you'd expect. If enabled (via checkbox) the relationship will not be displayed on the object under the `Relationships` section.
-
-!!! info
-    If the `Move to Advanced tab` and the `Hide on Object` are both enabled, the `Hide on Object` takes precedence and the relationship is not shown on the advanced tab.
-
-The two options above add flexibility to how the data is visualized within the Nautobot UI, the final option to enhance the relationship feature is the ability to match source or destination objects by providing a [filterset](../platform-functionality/relationship.md#relationship-filters).
-
-To continue on this example say we want to limit the relationship on the device to be able to only relate VLANs that have specific attributes. Perhaps only VLANs with the role of server and ID of 1000.
-
-The filterset below can be used to accomplish this.
-
-![relationship-filterset](./images/relationships/06-relationships.png)
-
-Once this has been applied you can navigate to the Device and attempt to add the relationship. As seen in the screenshot below only `VLANs` matching the filterset are shown and available to be related.
-
-![available-filtered](./images/relationships/07-relationships.png)
-
-As detailed in the [extras](https://docs.nautobot.com/projects/core/en/stable/models/extras/relationship/) documentation the API can be used to determine what can be filtered on. Below is a quick example of how to do that.
-
-### Constructing a Relationship Filter
-
-The first step is to navigate to the API documentation. This can be done by going to a browser and navigating to `https://<server-name>/api/docs`.
-
-This will load the Swagger documentation, the next step would be to navigate to the endpoint you're trying to filter.
-
-!!! info
-    The easiest way to navigate the Swagger documentation for the necessary endpoint is to search using the content-type defined in your relationship object.
-
-In this example the `Destination type` chosen was `ipam | VLAN`. We can use that to search in the Swagger docs for `ipam/vlans`.
-
-![swagger-crud](./images/relationships/08-relationships.png)
-
-As seen above this endpoint supports all the methods, but if we dig into the `GET` method we will see the parameters that are available.
-
-![get-parameters](./images/relationships/09-relationships.png)
-
-!!! warn
-    The screenshot above is only a subset of the available filters.
-
-!!! info
-    A great way to test a filterset before applying it to a relationship would be to use the `try it out` feature from within the API docs page.
-
-### Additional Examples
-
-Many relationship examples are available on the public [sandbox](https://demo.nautobot.com/extras/relationships/)
-
-These cover many of the different `Types` of relationships available in Nautobot.

nautobot/docs/user-guide/index.md

@@ -1 +0,0 @@
-# User Guide

nautobot/docs/user-guide/platform-functionality/change-logging.md

@@ -1,21 +0,0 @@
-# Change Logging
-
-Every time an object in Nautobot is created, updated, or deleted, a serialized copy of that object is saved to the database, along with meta data including the current time and the user associated with the change. These records form a persistent record of changes both for each individual object as well as Nautobot as a whole. The global change log can be viewed by navigating to Extensibility > Logging > Change Log.
-
-A serialized representation of the instance being modified is included in JSON format. This is similar to how objects are conveyed within the REST API.
-
-When a request is made, a UUID is generated and attached to any change records resulting from that request. For example, editing three objects in bulk will create a separate change record for each  (three in total), and each of those objects will be associated with the same UUID. This makes it easy to identify all the change records resulting from a particular request.
-
-Change records are exposed in the API via the read-only endpoint `/api/extras/object-changes/`. They may also be exported via the web UI in CSV format.
-
-Change records can also be accessed via the read-only GraphQL endpoint `/api/graphql/`. An example query to fetch change logs by action:
-
-```graphql
-{ 
-  query: object_changes(action: "created") {
-    action
-    user_name
-    object_repr
-  }
-}
-```

nautobot/docs/user-guide/platform-functionality/computedfield.md

@@ -1,89 +0,0 @@
-# Computed Fields
-
-+++ 1.1.0
-
-Computed fields are very similar in design and implementation to custom fields. See the overview of [Custom Fields](./customfield.md). As the name suggests, computed fields serve the need for a custom field where the value is generated using data that Nautobot stores in its database and merging it into a Jinja2 template and associated filters.
-
-As an example, within your automation system, you may want to be able to have an automatically generated field on the Device model that combines the name of the device and the location name in uppercase. To do that, you would define a Jinja2 template for this field that looks like such:
-
-```jinja2
-{{ obj.name }}_{{ obj.location.name | upper }}
-```
-
-!!! important
-    Every time an object with this computed field is loaded, the template gets re-rendered with the currently available data. These rendered values are not stored in the database; only the Jinja2 template is stored.
-
-+/- 2.0.0
-    Computed field model's `label` attribute will be used exclusively for display purposes in the UI.
-
-    Computed field model's `slug` attribute was renamed to `key` (unique for all Computed Field instances), which contains a GraphQL-safe string to be used in the API and GraphQL.
-
-    These 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.
-
-## Creating Computed Fields
-
-Computed fields can be created through the Nautobot UI under **Extensibility > Computed Fields**.
-
-Each computed field must have a key and a label.
-
-- Key must be a simple, database-friendly string, e.g. `device_with_location`
-- Label is used as the human-friendly display name for this field in the UI, for example, `Device With Location`.
-
-!!! tip
-    Because computed field data can be included in the REST API and in GraphQL, we strongly recommend that when defining a computed field, you provide a key that contains underscores rather than dashes (`my_field_key`, not `my-field-key`), as some features may not work optimally if dashes are included in the key.
-
-Similar to custom fields, the weight value is used to order computed fields within a form. A description can also be provided, and will appear beneath the field in a form.
-
-Computed fields must define a template from which to render their values. The template field must contain a valid Jinja2 template string.
-
-A computed field must be assigned to an object type, or model, in Nautobot. Once created, a computed field will automatically appear as part of this model's display. See notes about viewing computed fields via the REST API below.
-
-When creating a computed field, if "Move to Advanced tab" is checked, this computed field won't appear on the object's main detail tab in the UI, but will appear in the "Advanced" tab. This is useful when the requirement is to hide this field from the main detail tab when, for instance, it is only required for machine-to-machine communication and not user consumption.
-
-## Computed Field Template Context
-
-Computed field templates can utilize the context of the object the field is being rendered on. This context is available for use in templates via the `obj` keyword. As an example, for a computed field being rendered on a Device object, the name of the location that this Device belongs to can be accessed like this:
-
-```jinja2
-{{ obj.location.name }}
-```
-
-!!! note
-    To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for the custom field with a key of `color` on `obj`.
-
-## Computed Field Template Filters
-
-Computed field templates can also utilize built-in Jinja2 filters or custom ones that have been registered via plugins. These filters can be used by providing the name of the filter function. As an example:
-
-```jinja2
-{{ obj.location.name | leet_speak }}
-```
-
-See the documentation on [built-in filters](./template-filters.md) or [registering custom Jinja2 filters](../../development/apps/api/platform-features/jinja2-filters.md) in plugins.
-
-## Computed Fields and the REST API
-
-When retrieving an object via the REST API, computed field data is not included by default in order to prevent potentially computationally expensive rendering operations that degrade the user experience. In order to retrieve computed field data, you must use the `include` query parameter.
-
-Take a look at an example URL that includes computed field data:
-
-```no-highlight
-http://localhost:8080/api/dcim/locations?include=computed_fields
-```
-
-When explicitly requested as such, computed field data will be included in the `computed_fields` attribute. For example, below is the partial output of a location with one computed field defined:
-
-```json
-{
-    "id": 123,
-    "url": "http://localhost:8080/api/dcim/locations/123/",
-    "name": "Raleigh 42",
-    ...
-    "computed_fields": {
-        "location_name_uppercase": "RALEIGH"
-    },
-    ...
-```
-
-!!! note
-    The `key` value of each computed field is used as the key name for items in the `computed_fields` attribute.