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.

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	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.

Changed in version 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.

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.

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.

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: 2 VLANs doesn't give the same context as Configured VLANs: 2 VLANs.

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: 2 devices is far superior to the default of Devices: 2 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.

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.

Once the option is enabled you will see the relationship is now moved to the Advanced tab.

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.

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.

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.

As detailed in the extras 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.

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.

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

These cover many of the different Types of relationships available in Nautobot.