NetBox to JSM Assets Integration Guide

This page explains how to use OnLink to import NetBox data into Jira Service Management Assets. It focuses on configuring the NetBox API connection, fetching sample data, mapping NetBox fields to Assets attributes, validating the import, and applying optional NetBox API filters.

Overview

OnLink can import NetBox API responses into JSM Assets object types by using mapping statements such as key:, map:, and config:. The same approach can be used for NetBox object types such as devices, users, circuits, and wireless data, provided the corresponding NetBox API endpoint and Assets object type are configured.

The high-level process is:

1. Create or confirm the target Assets schema and object type.

2. Create a NetBox API token.

3. Configure an OnLink Assets Data Source that authenticates to NetBox with a bearer token.

4. Set the API method and NetBox endpoint, then fetch sample data.

5. Map JSON fields from the NetBox response to Assets attributes.

6. Run Get Data to validate the result, then run the import when the mapping is correct.

Prerequisites

• A Jira Service Management Assets schema and object type for the data you want to import.

• OnLink installed and available from Manage your apps.

• A NetBox API token with access to the required API endpoints.

• Permission in JSM Assets to configure data sources, mappings, and imports.

• The NetBox API endpoint URL for the object type you plan to import.

Supported NetBox object types

The examples on this page use NetBox devices. The same pattern can be adapted for other NetBox data, such as users, circuits, and wireless objects, by selecting the appropriate NetBox API endpoint and mapping the returned JSON fields to the matching Assets attributes.

1. Create the NetBox API token

Create a NetBox API token before configuring OnLink. For NetBox authentication details, see the NetBox REST API authentication documentation.

Keep the token available for the OnLink data source configuration.

2. Configure the OnLink data source

1. In OnLink, add an Assets Data Source.

2. Set Authentication Type to Bearer Token.

3. Set the header name to Authorization.

4. Paste the token generated in NetBox.

Open

3. Configure the API method

Use a GET request to retrieve records from the NetBox API. For example, to fetch devices, configure the request as follows:

1. Set Method to GET.

2. Set URL to https://hostname/api/dcim/devices/.

3. Replace hostname with your NetBox instance hostname.

4. Leave the remaining configuration at the default values unless your NetBox API endpoint requires additional parameters.

Open

Open

4. Fetch sample data

Save the connection, then run it to fetch sample values from NetBox. Use the returned sample JSON to confirm that the endpoint is correct and to identify the field names needed for mapping.

When inspecting the sample response, look for the field path that contains the value you want to import. For example, a device name may appear as name, while nested values may require mapping from the nested JSON structure returned by NetBox.

Pagination notes

NetBox API responses may be paginated. If the sample response includes pagination fields such as a result count or next-page URL, confirm that the OnLink data source configuration is set up to retrieve the full dataset expected for your import.

5. Configure the Assets import and mapping

After the connection is established, create the Assets import by following the JSM Assets Data Synchronization guide.

Use the fetched API sample to identify the NetBox JSON field names and map them to the corresponding JSM Assets attributes. The key: mapping should identify the stable unique value used to match and update existing Assets objects.

Mapping guidance

• Start with one unique key: mapping so OnLink can identify whether to create or update an Assets object.

• Add map: entries for each NetBox field you want to store in Assets.

• Compare the NetBox sample JSON with the Assets object type attributes before running an import.

• If a value is nested in the JSON response, inspect the sample output carefully and use the field path supported by the OnLink mapping configuration.

6. Validate and run the import

1. Use Get Data first to preview the data returned by NetBox.

2. Confirm that the sample records contain the expected fields and values.

3. Verify that the key field maps to a unique Assets attribute.

4. Review the object type mapping and attribute names for spelling and case consistency.

5. Run the import only after the previewed data and mapping are correct.

Optional filtering

Use NetBox API query parameters to limit the records returned by the endpoint. For supported filters, refer to the NetBox API documentation for the endpoint you are using.

For example, to return only active devices, add the appropriate status filter to the devices endpoint:

Refer to this page to check on the filters supported by NetBox API

e.g if I want to filter on devices that are active.

Open