Technical Information
This page describes how NetBox objects map to Jira Assets, how the schema is provisioned, and how configuration parameters affect sync behavior. For an integration overview, see the Jira Assets Integration page. For container setup and first-run steps, see Getting Started. For troubleshooting, see FAQ and Troubleshooting.
NetBox to Jira Assets object mapping
The integration syncs 28 object types from NetBox into a Jira Assets schema named NetBox. On first run, the container provisions all object types and attributes defined in the image. No manual Jira Assets schema setup is required.
Objects are matched by netbox_id (the NetBox primary key). The object display name in Jira Assets comes from the NetBox object name and is stored in the Name label attribute.
Object type mapping table
| NetBox source | Jira Assets object type | Key fields mapped |
|---|---|---|
extras.Tag | Tag | slug, color, description |
tenancy.Tenant | Tenant | tags, slug, group (text), description |
dcim.Region | Region | tags, parent (self-reference), slug, description |
dcim.Site | Site | tags, tenant, region, status, facility, physical_address |
dcim.Location | Location | tags, site, parent (self-reference), tenant, status, slug |
dcim.Rack | Rack | tags, tenant, site, location, status, role (text), serial, u_height |
dcim.DeviceType | Device Type | tags, manufacturer (text), model, slug, part_number, u_height |
dcim.Device | Device | tags, tenant, location, rack, device_type, platform (text), serial, primary_ip (text), config_context |
dcim.Interface | Interface | tags, device, type, speed, mac_address, enabled, mtu |
ipam.IPAddress | IP Address | tags, interface, status, dns_name, tenant |
virtualization.ClusterType | Cluster Type | tags, slug, description |
virtualization.ClusterGroup | Cluster Group | tags, slug, description |
virtualization.Cluster | Cluster | tags, type, group, tenant, site, status |
extras.ConfigContext | Config Context | weight, is_active, data (JSON), scoped references to Region, Site, Location, Device Type, Cluster types, and related objects |
virtualization.VirtualMachine | Virtual Machine | tags, cluster, tenant, site, status, role (text), platform (text), vcpus, memory, disk, primary_ip (text), config_context |
virtualization.VMInterface | VM Interface | tags, virtual_machine, enabled, mtu, mac_address |
virtualization.VirtualDisk | Virtual Disk | tags, virtual_machine, size |
netbox_inventory.Supplier | Supplier | slug, description |
netbox_inventory.Purchase | Purchase | supplier, status, date |
netbox_inventory.Delivery | Delivery | purchase, date |
netbox_inventory.InventoryAsset | Inventory Asset | asset_tag, serial, status, kind, device, purchase, delivery, warranty dates |
netbox_lifecycle.Vendor | Vendor | (name only) |
netbox_lifecycle.SupportSKU | Support SKU | manufacturer (text), sku, description |
netbox_lifecycle.SupportContract | Support Contract | vendor, contract_id, start, renewal, end |
netbox_lifecycle.SupportContractAssignment | Support Contract Assignment | contract, sku, device, end |
netbox_lifecycle.HardwareLifecycle | Hardware Lifecycle | tags, device_type, EOL/EOS dates, notice, documentation |
netbox_lifecycle.License | License | manufacturer (text) |
netbox_lifecycle.LicenseAssignment | License Assignment | license, vendor, device, quantity |
Sync order
Object types sync in dependency order. Tag syncs first because other types reference it. Parent types (for example Site before Rack, Device before Interface) sync before their dependents. Required reference types are included automatically when you limit sync with SYNC_ASSETS. See How the sync works in Getting Started.
Common schema attributes
Every synced object type includes these attributes:
| Jira Assets attribute | Type | Source |
|---|---|---|
Name | Label | NetBox object name |
netbox_id | Integer | NetBox id |
last_synced | Datetime | Set by the sync tool on create or update (not sourced from NetBox) |
Most object types also include tags as a multi-value reference to the Tag object type.
The last_synced attribute supports retirement workflows. A stale last_synced date usually means the object was removed from NetBox or has not changed since its last write. When GRACE_DAYS_BEFORE_STALE_DELETE is set, objects whose last_synced date exceeds the threshold are deleted after each object type syncs. See FAQ and Troubleshooting.
Reference and text fields
NetBox relationships are modeled in two ways in Jira Assets:
Reference attributes create clickable links between Jira Assets objects. Examples include Device → Rack → Site → Region, Interface → Device, and Virtual Machine → Cluster.
Text attributes store the related value as a plain string without a navigable link. Examples include Device → platform (stores the platform name), Device Type → manufacturer (stores the manufacturer name), and Tenant → group (stores the tenant group name).
This design keeps the schema manageable while surfacing the most important navigable relationships. Config Context scopes some NetBox types as references (for example Site, Region) and others as textarea aggregates when no corresponding object type exists in the schema (for example site_groups, device_roles, platforms).
Self-referential nesting
Region and Location preserve NetBox tree hierarchies through self-referential parent attributes. A child Region links to its parent Region; a child Location links to its parent Location within a Site.
Custom fields
Custom fields defined in NetBox are discovered at runtime from /api/extras/custom-fields/ and synced as attributes prefixed with cf_. A NetBox custom field named deployment_date becomes cf_deployment_date in Jira Assets.
Use SYNC_CF_INCLUDE and SYNC_CF_EXCLUDE to control which custom fields are written. See Filter custom fields in Getting Started for wildcard syntax and examples.
NetBox custom field type mapping
| NetBox custom field type | Jira Assets attribute type |
|---|---|
text, longtext, json, multiselect, multiobject | Textarea (up to 1M characters) |
select, object | Text (255-character limit) |
integer, boolean, date, and other scalar types | Matching scalar type |
NetBox text, multiselect, and multiobject custom fields are provisioned as Jira Textarea attributes. select and object custom fields use Jira Text with a 255-character limit.
Custom field limitations
Custom fields of type object and multiobject are stored as plain text display values, not as navigable links. Jira Assets requires each reference to target a single fixed object type, while NetBox object-type custom fields can reference any model.
Schema drift
If a custom field attribute already exists in Jira with the wrong type (for example Text instead of Textarea), the compatibility check reports an error before sync. Delete the attribute in Jira Assets and re-run to recreate it with the correct type. See FAQ and Troubleshooting.
Generic foreign keys
NetBox uses Generic Foreign Keys (GFKs) for some relationships. Jira Assets does not support polymorphic references, so the integration maps each GFK to its most common target type:
| NetBox field | Constrained to | Jira Assets reference |
|---|---|---|
HardwareLifecycle.assigned_object | DeviceType, ModuleType | Device Type |
IPAddress.assigned_object | Interface, VMInterface | Interface (device interfaces only) |
VM interface IP assignments are not modeled as references to VM Interface objects in the current schema.
Jira Assets attribute types
The schema uses these Jira Assets attribute types:
| Schema type | Jira defaultTypeId | Typical use |
|---|---|---|
text | 0 | Short strings, status labels, select/object custom fields |
integer | 1 | IDs, counts, speeds |
boolean | 2 | Enabled flags, active status |
float | 3 | vCPU counts, rack U height |
date | 4 | Warranty and contract dates |
datetime | 6 | last_synced |
url | 7 | Documentation links |
textarea | 9 | Descriptions, config context JSON, long custom fields |
ipaddress | 11 | IP addresses (when used as a dedicated type) |
reference | (type 1) | Links to other object types in the schema |
Use textarea for NetBox description fields and other unbounded long-text content.
Schema compatibility check
Every sync run performs a compatibility check after schema provisioning. The tool prints which variant is active:
ℹ Compatibility check: fast (schema unchanged during provisioning)
Thorough check
Samples live NetBox objects and compares values against Jira attribute constraints.
- Automatic: Runs when provisioning created new object types or attributes on that run
- Manual:
docker run ... --check(without--no-sample)
See Validate schema compatibility in Getting Started for run examples.
Thorough checks can confirm NetBox text values that exceed Jira Text (255) limits and required Jira attributes whose NetBox source field is empty on specific objects.
Fast check
Inspects Jira Assets metadata only. No NetBox object fetch for the check.
- Automatic: Runs when provisioning made no new object types or attributes
- Manual:
docker run ... --check --no-sample
Fast checks still catch type drift, missing attributes, and object-type or label name mismatches. For text-length and required-field issues they emit warnings based on schema metadata rather than sampling NetBox values.
Errors vs warnings
- Errors block sync and cause
--checkto exit with code1 - Warnings are printed but do not block sync
Exact schema matching
Object type names, the Name label attribute, and every synced attribute must match the schema exactly in Jira Assets. A mismatch (for example site instead of Site, or label attribute name instead of Name) is reported as an error. Delete the conflicting object type or attribute in Jira Assets and re-run.
For remediation steps, see FAQ and Troubleshooting.
Configuration parameters
For a concise operator reference while deploying the container, see Configuration reference in Getting Started.
Environment variables
| Variable | Required | Description |
|---|---|---|
JIRA_URL | Yes | Jira Cloud base URL |
JIRA_USER | Yes | Jira account email |
JIRA_API_TOKEN | Yes | Jira API token |
NETBOX_URL | Yes | NetBox base URL |
NETBOX_TOKEN | Yes | NetBox API token (v1 hex or v2 nbt_...) |
NETBOX_PAGE_SIZE | No | Objects per NetBox API page when fetching data (1-1000, default 500). Smaller values mean more requests but smaller payloads per request. |
SYNC_ASSETS | No | Comma-separated list of object type names to sync (default: all types shipped in the image). Names are case-insensitive. Required reference types are included automatically. |
SYNC_CF_INCLUDE | No | Comma-separated custom fields to sync (allowlist). Names may omit the cf_ prefix. Scope to one object type with Device:cf_jiraid. Wildcards: cf_servicenow* (starts with), *servicenow (contains). Applied before exclude. |
SYNC_CF_EXCLUDE | No | Comma-separated custom fields to skip (denylist). Wildcards: cf_servicenow* (starts with), *servicenow (contains). !Device exempts an object type; !*location or !cf_servicenow_prod* exempt matching field names. Excluded fields are never sent to Jira. |
GRACE_DAYS_BEFORE_STALE_DELETE | No | Grace period in days (non-negative integer). After each object type syncs, delete Jira objects in that type whose last_synced date (UTC, day precision) is more than this many days old. 0 deletes objects not synced today. Unset = disabled. Objects still fetched from NetBox are never deleted. See FAQ and Troubleshooting. |
SYNC_ASSETS object type names
Use the exact names from the schema. Schema provisioning still creates all object types defined in the image; only the data sync step is filtered. Invalid names cause the sync to exit with a list of allowed types.
| Category | Names |
|---|---|
| Core | Tag, Tenant, Region, Site, Location, Rack, Device Type, Device, Interface, IP Address |
| Virtualization | Cluster Type, Cluster Group, Cluster, Config Context, Virtual Machine, VM Interface, Virtual Disk |
| netbox-inventory plugin | Supplier, Purchase, Delivery, Inventory Asset |
| netbox-lifecycle plugin | Vendor, Support SKU, Support Contract, Support Contract Assignment, Hardware Lifecycle, License, License Assignment |
Example:
SYNC_ASSETS=Virtual Machine,VM Interface,Virtual Disk
See Limit sync to specific object types in Getting Started.
CLI flags
| Flag | Description |
|---|---|
--quiet / -q | Disable the live progress bar. Per-type summary lines are still printed. Suitable for cron and log files. |
--verbose / -v | After sync completes (or is interrupted), print a grouped error summary: root cause, object count, sample names, and plain-language hints. No effect if there were zero errors. |
--check | Validate schema compatibility and exit without syncing. Default is the thorough check (samples NetBox values). Exit code 1 if errors are found. |
--no-sample | With --check, run the fast check (Jira metadata only). During a normal sync, compatibility is fast unless provisioning created new object types or attributes. |
--vm-tags TAGS | Comma-separated NetBox tag slugs. Only Virtual Machines with at least one matching tag are synced; VM Interfaces and Virtual Disks for other VMs are skipped. All other object types still sync in full unless SYNC_ASSETS limits them. |
See CLI flags in Getting Started.
Authentication
The integration authenticates to Jira Cloud using basic auth with the account email (JIRA_USER) and API token (JIRA_API_TOKEN). Create tokens at https://id.atlassian.com/manage-profile/security/api-tokens. Credential setup steps are in Obtain credentials in Getting Started.
NetBox authentication uses the API token in NETBOX_TOKEN. A read-only token is sufficient. v1 tokens are 40-character hex strings. v2 tokens (nbt_... format, NetBox 4.5+) use the format [key].[token] in the environment variable.
Sync behavior
On each run, the sync:
- Discovers custom fields from NetBox, applying
SYNC_CF_INCLUDE/SYNC_CF_EXCLUDEfilters when set - Provisions the Jira Assets schema (creates any missing object types and attributes)
- Runs a schema compatibility check and aborts on errors before writing objects
- Syncs each object type in dependency order
- For each object: bulk-indexes Jira objects by
netbox_id, compares attributes, creates or updates if changed, skips if unchanged - Sets
last_syncedto the current UTC time on create or update only - If
GRACE_DAYS_BEFORE_STALE_DELETEis set, deletes stale Jira objects after each object type syncs. See FAQ and Troubleshooting.
For step-by-step deployment, see How the sync works in Getting Started.
Additional behavior:
- Direction: One-way, NetBox to Jira only. Manual changes in Jira Assets are overwritten on the next sync. See Filter custom fields in Getting Started.
- Idempotency: Safe to run repeatedly or on a schedule. Will not create duplicates.
- Incremental updates: Unchanged objects are skipped. Their
last_syncedtimestamp is not updated. See Common schema attributes. - NetBox fetch: Data loads in paginated chunks (
NETBOX_PAGE_SIZE) with retries on transient connection errors. See FAQ and Troubleshooting if fetches time out. - Performance: The Jira Assets API processes approximately 2-3 objects per second. First runs take longer; subsequent runs complete faster when most objects are unchanged.
- Interrupts: Press
Ctrl+Conce to stop after the current object finishes; press again to force quit.
Known limitations
- Custom field object references: Custom fields of type
objectandmultiobjectare stored as plain text display values, not navigable links. See Custom field limitations. - Custom field text limits:
selectandobjectcustom fields map to Jira Text (255 characters).text,multiselect, andmultiobjectmap to Textarea. See NetBox custom field type mapping. - One-way sync only: Changes made directly in Jira Assets are not synced back to NetBox. See Sync behavior.
- Automatic deletion: Only when
GRACE_DAYS_BEFORE_STALE_DELETEis set. Otherwise objects removed from NetBox remain in Jira until you retire them manually or enable stale delete. See FAQ and Troubleshooting. - VM interface IP addresses: IP addresses assigned to VM interfaces are not linked as references to VM Interface objects. See Generic foreign keys.
- Jira Cloud only: The tool has been tested with Jira Cloud. Jira Data Center may require modifications. See Supported Jira versions.