Technical Information

HPE Mist to NetBox Object Mapping

This document provides a comprehensive mapping of HPE Mist object types to their corresponding NetBox object types, based on the integration implementation.

Object Type Mapping Table

HPE Mist Object	NetBox Object Type	Key Fields Mapped	Mapping Details
Site	Site	name → name
name → slug
timezone → time_zone
id → custom_fields.mist_id	Maps Mist sites (from listOrgSites) to NetBox sites with timezone and Mist site ID preserved. Site filtering via policy scope sites (default ["*"] = all).
Site (Unassigned)	Site	Static name / slug	Creates "Unassigned Mist Inventory" site for devices with invalid or missing site_id (UUID 00000000-0000-0000-0000-000000000000).
Device (Inventory, standalone)	Device	name or serial or "Unnamed" → name
serial → serial
connected + site_id → status
type → role
model → device_type
version → platform
mac → custom_fields.mist_mac
derived → custom_fields.mist_device_status	Standalone (non–Virtual Chassis) inventory devices. Device type, role, and platform created from type, model, and version.
Device (Inventory, VC member)	Device	vc_name + fpc_idx → name
module_stat[].serial → serial
connected + site_id → status
type → role
module_stat[].model → device_type
module_stat[].version → platform
module_stat[].mac → custom_fields.mist_mac
vc_mac → custom_fields.mist_vc_mac
module_stat[].vc_role → custom_fields.mist_vc_role
derived → custom_fields.mist_device_status
virtual_chassis + vc_position	Virtual Chassis member devices; one Device per member. Master identified by vc_role='master' or lowest fpc_idx.
Virtual Chassis (switch stack)	VirtualChassis	name → name
Key: vc_mac	Created for switches with type=="switch" and vc_mac starting with 0200. One VirtualChassis per unique vc_mac.
Device Type	DeviceType	model → model
model → slug
type → custom_fields.mist_type	Created per model; for VC members, model comes from module_stat[].model.
Device Role	DeviceRole	type → name
type → slug	Mist device type (e.g. ap, switch, gateway) becomes NetBox device role.
Platform	Platform	version → name "Junos {version}" or "Junos"
slug slugified	One platform per unique firmware version (e.g. "Junos 21.4R3-S8.5"); falls back to "Junos" when no version is present. Linked to manufacturer.
Manufacturer	Manufacturer	Static → name "Juniper", slug "juniper"	Single manufacturer for all Mist devices.
VLAN Group	VLANGroup	"{site.name} VLANs" → name
slugified → slug
site → scope_site	One VLAN group per site that has an org-level network template containing at least one valid VLAN. Source: listOrgNetworkTemplates.
VLAN	VLAN	network_name → name
vlan_id → vid
Static "active" → status
vlan_group → group	VLANs from the site's network template networks dict. VIDs validated as integers in range 1–4094; duplicates per site skipped.
Wireless LAN	WirelessLAN	ssid → ssid
enabled → status
auth.type → auth_type
auth → auth_cipher
id → custom_fields.mist_wlan_id
ap_ids → custom_fields.mist_ap_ids
apply_to → custom_fields.mist_ap_scope
wxtag_ids → custom_fields.mist_wxtag_ids (when apply_to=wxtags)	WLANs from listSiteWlansDerived; one entity per unique (wlan_id, site_id, ssid). Includes WLANs with no serving devices. After device–WLAN matching, mist_ap_mac_addresses_serving_this holds JSON array of AP MACs.
Interface	Interface	From device stats: if_stat / ip_stat.ips
key → name
up → enabled
port_id → custom_fields.mist_interface_port_id
Heuristic from name → type	Built from getSiteDeviceStats(..., fields="ports"). For Virtual Chassis, interface assigned to member by FPC in name (e.g. ge-1/0/44 → fpc 1).
IP Address	IPAddress	From device stats interface IPs
address → address
Interface → assigned_object_interface
status "active"	Created from device stats for all devices with a valid site assignment. Management IP (matching device ip) set as device primary_ip4 or primary_ip6.
MAC Address	MACAddress	From device stats ports (port_id → port_mac / mac for vme)
Or freestanding from inventory mac	Interface MACs from stats; device MACs created as freestanding when not attached to an interface. Internal ports cbp0, pip0, jsrv, bme0 skipped.
VRF	VRF	name → "mist-site-{site.name}"	Per-site VRFs created automatically when the same IP address appears in more than one site. Ensures IP uniqueness across sites.

Field Mapping Details

Device Status Mapping

Mist Connection Status	NetBox Status
Missing or invalid site_id (unassigned)	inventory
true (connected)	active
false (disconnected)	offline

Wireless LAN Status Mapping

Mist WLAN Status	NetBox Status
true (enabled)	active
false (disabled)	disabled

Authentication Type Mapping

Mist Auth Type	NetBox Auth Type
open	open
psk	wpa-personal
psk-tkip	wpa-personal
psk-wpa2-tkip	wpa-personal
eap	wpa-enterprise
eap192	wpa-enterprise
wep	wep
Any other value	Unknown

Authentication Cipher Mapping

Mist Auth Type	Mist Pairwise Ciphers	NetBox Auth Cipher
eap192	Any	aes
psk-tkip | psk-wpa2-tkip	Any	tkip
wep	Any	auto
open	Any	None
psk | eap	Contains "tkip"	tkip
psk | eap	Contains "ccmp" or "wpa3"	aes
psk | eap	No recognized cipher	None
Unknown auth_type	—	Integration raises

Cipher uses Mist auth.pairwise list (e.g. wpa2-ccmp, wpa2-tkip, wpa3).

Interface Type Heuristics

Interface Name Pattern	NetBox Type
ge-*	1000base-t
vme* or VLAN*	virtual
Other	other

Site Assignment Logic

1. Allowed sites: From policy scope sites (list of site names). ["*"] or empty means all sites.
2. Valid site: Device site_id present in allowed site IDs → assign to that NetBox site.
3. Unassigned fallback: Missing or invalid site_id (e.g. 00000000-0000-0000-0000-000000000000) or site not in allowed list → assign to "Unassigned Mist Inventory" site.
4. Inventory filtering: Only devices in allowed sites (or unassigned) are ingested; same for devices/search when building device–WLAN mapping.

WLAN Scope and Custom Fields

WLANs are always scoped to a site (scope_site). Mist scope is stored in custom fields:

Mist apply_to	Custom Field Usage
site	Standard site scope
wxtags	mist_wxtag_ids (JSON array)
aps	mist_ap_ids (JSON array)
None	Site scope

Virtual Chassis Detection

• Condition: type == "switch" and vc_mac starts with 0200 (Juniper VC MAC prefix).
• VirtualChassis: One per unique vc_mac; name from device name.
• Member devices: Built from getSiteDeviceStats module_stat; member name \{vc_name\}-member-\{fpc_idx\}; master by vc_role='master' or lowest fpc_idx.

Device–WLAN Matching

• Source: devices/search (type=ap, duration=1h) gives per-device wlans[] (id, ssid).
• Uniqueness: WLANs keyed by (wlan_id, site_id, ssid); only WLANs present in listSiteWlansDerived for that site are used.
• Device custom field: mist_wlans_served (object, multiple) references the WirelessLAN entities the device serves.
• WLAN custom field: mist_ap_mac_addresses_serving_this (JSON array of AP MAC addresses) populated after matching.

Custom Fields

Custom Field	Object Type	Purpose
mist_id	Site	Mist site ID
mist_type	Device Type	Mist device type (ap, switch, etc.)
mist_mac	Device	Mist device MAC
mist_vc_mac	Device	Virtual Chassis MAC (VC members only)
mist_vc_role	Device	VC role: master, backup, or empty (VC members only)
mist_wlan_id	Wireless LAN	Mist WLAN ID
mist_ap_ids	Wireless LAN	JSON array of AP IDs
mist_ap_scope	Wireless LAN	apply_to (site, wxtags, aps)
mist_wxtag_ids	Wireless LAN	JSON array of WxTag IDs when apply_to=wxtags
mist_ap_mac_addresses_serving_this	Wireless LAN	JSON array of AP MAC addresses serving this WLAN
mist_wlans_served	Device	JSON array of WLANs served by this device, each with ssid and wlan_id
mist_interface_port_id	Interface	Mist port ID for the interface
mist_device_status	Device	Original Mist status: connected, disconnected, or unassigned

Policy Configuration

• BOOTSTRAP (optional): When true, only static entities (custom fields, manufacturer) are created; no Mist API calls.

• MIST_APITOKEN (required when not BOOTSTRAP): Mist API token.

• MIST_ORG_ID (required when not BOOTSTRAP): Mist organization ID.

• MIST_ENVIRONMENT (optional): Mist cloud environment. Defaults to "Global 01" (api.mist.com). Each Mist organization is hosted in a specific cloud environment — if not specified, Global 01 is used. See Mist API Environments to identify which environment your organization uses.

  Environment	API Host
  Global 01	api.mist.com
  Global 02	api.gc1.mist.com
  Global 03	api.ac2.mist.com
  Global 04	api.gc2.mist.com
  Global 05	api.gc4.mist.com
  EMEA 01	api.eu.mist.com
  EMEA 02	api.gc3.mist.com
  EMEA 03	api.ac6.mist.com
  EMEA 04	api.gc6.mist.com
  APAC 01	api.ac5.mist.com
  APAC 03	api.gc7.mist.com

• Scope – sites (optional): List of site names to include; default ["*"] for all sites. Invalid or missing names cause validation to fail after fetching sites.

Tags and Metadata

All created entities are tagged with:

• juniper
• mist
• discovered

Optional unique tag: mist-\{org_id\} when not in bootstrap mode.

API and Behavior Notes

• APIs used: listOrgSites, getOrgInventory, listOrgNetworkTemplates, getSiteDeviceStats (with fields="ports"), searchOrgDevices (type=ap), listSiteWlansDerived.
• Rate limiting: Custom retry (e.g. MistCustomRetry) for 429, 5xx with Retry-After support.
• Device naming: Standalone: name or serial or "Unnamed". VC members: \{vc_name\}-member-\{fpc_idx\}.
• WLAN uniqueness: Deduplicated by (wlan_id, site_id, ssid). WLANs with no serving devices are still created from site-derived WLANs.
• Interfaces: Only devices with a valid site_id (and in allowed sites) have stats fetched; unassigned devices do not get interfaces or IPs from this integration.