Technical Information

Cisco Meraki to NetBox Object Mapping

Meraki Object	NetBox Object	Key Attributes
`Network`	`Site`	`name`, `slug`, `latitude`, `longitude`, `tags`, `custom_fields.meraki_networks` (JSON), `group` → SiteGroup
`Configuration Template`	`SiteGroup`	`name`, `slug`, `custom_fields.meraki_template_metadata` (JSON)
`Device` (wireless, switch, appliance)	`Device`	`name` (or `serial`), `serial`, `device_type`, `role`, `platform`, `status`, `tags`, `custom_fields.meraki_serial`, `custom_fields.meraki_template_id`
`Switch Stack`	`VirtualChassis`	`name` (or stack `id`)
Device `model`	`DeviceType`	`model`, manufacturer "Cisco"
`productType`	`DeviceRole`	"Wireless AP", "Switch", or "Firewall"
`firmware` + model prefix	`Platform`	`name` (e.g. "Meraki MR 1.2.3")
(static)	`Manufacturer`	`name` "Cisco"
`SSID`	`WirelessLAN`	`ssid`, `status`, `auth_type`, `auth_cipher`, `vlan`, `custom_fields.meraki_radius_config`
Appliance `VLAN`	`VLAN`	`vid`, `name`, `status` "active", `group` → VLANGroup
`Network`	`VLANGroup`	`name` "{network} VLANs", `slug`, `scope_site`
Switch port / radio / appliance port / management interface	`Interface`	`name`, `type`, `enabled`, `mode`, `custom_fields.meraki_serial`, `custom_fields.meraki_port_id`
Interface IP	`IPAddress`	`address` (CIDR), `status` "active"
Device `mac`	`MACAddress`	`mac_address` (uppercase), assigned to management interface
(derived from interface IPs)	`Prefix`	`prefix`, `status` "active", `scope_site`

Meraki status (getOrganizationDevicesStatuses)	NetBox Status
`online`	`active`
`alerting`	`active`
`offline`	`offline`
`dormant`	`inventory`
Any other / no status	`active`

Meraki SSID enabled	NetBox Status
`true`	`active`
`false`	`disabled` (SSIDs with enabled=false are skipped)

Meraki VLAN	NetBox Status
All VLANs from API	`active`

Site name for a Meraki network is resolved in order:

network_site_mapping: If scope.network_site_mapping contains the network name, use the mapped NetBox site name.
default_site: If config.defaults.site is set, use it for unmapped networks.
Network name: Otherwise use the Meraki network name (one site per network name).

Multiple networks can map to the same site; the first network (by name) supplies site-level fields and template binding.

Device Type	Interface Source	Notes
MR (Wireless AP)	getDeviceWirelessRadioSettings	Radio1 (2.4GHz), Radio2 (5GHz), Radio3 (6GHz) if present. Type `other`. No physical management port created as separate interface; management comes from getDeviceManagementInterface.
MS (Switch)	getDeviceSwitchPorts	Port{portId}. Type from linkNegotiationCapabilities (10g/5g/2.5g/1g/100M, SFP vs copper). Mode: trunk→tagged, else access. meraki_serial, meraki_port_id. Stack ports → type `other`.
MX (Appliance)	getNetworkAppliancePorts	Physical Port{number}; type from model-based mapping (MX_PORT_MAPPINGS). VLAN interfaces: VLAN{vlan_id}, type virtual. Single LAN: one "LAN" interface when vlansEnabled=false.
All	getDeviceManagementInterface	Management interfaces by name from API; type from model (MR: MR_MGMT_PORT_TYPES, MS: 1000base-t, MX: 1000base-t). enabled = (wanEnabled == "enabled"). Static IPs created for management interfaces; primary IPs set from these (inactive stack members skipped).

From getNetworkSwitchLinkAggregations. "LAG {id}" (single-device) or "Stack LAG {id}" (cross-device). Type lag. Cross-device LAGs assigned to active stack member. Member ports linked to LAG.

Built from getOrganizationConfigTemplates. Site is linked to SiteGroup when its first network has configTemplateId. meraki_template_metadata stores full template API response.

Custom Field	Object Type	Purpose
`meraki_networks`	Site	JSON array of network metadata (id, template_id, name, latitude, longitude, tags) for all networks in the site
`meraki_radius_config`	Wireless LAN	JSON object of RADIUS-related keys from SSID config
`meraki_stack_id`	Device	Meraki switch stack ID (stack members and master)
`meraki_stack_name`	Device	Meraki switch stack name
`meraki_serial`	Device, Interface	Meraki device serial number
`meraki_port_id`	Interface	Port ID for API (switch portId, appliance port number or VLAN ID)
`meraki_template_id`	Device	Config template ID inherited from network
`meraki_template_metadata`	SiteGroup	Full Meraki template API response (JSON)

BOOTSTRAP (optional): When true, only static entities (custom fields, manufacturer) are created; no API calls.
MERAKI_API_KEY (required when not BOOTSTRAP): Meraki Dashboard API key.
MERAKI_ORG_ID (required when not BOOTSTRAP): Meraki organization ID.
MERAKI_COUNTRY (optional): Base URL override. Valid: canada, china, india, united-states-fedramp.
defaults.site (optional): Default NetBox site name for unmapped networks.
Scope – networks (optional): List of network names to ingest; default ["*"]. Invalid names cause validation to fail after fetching networks.
Scope – network_site_mapping (optional): Dict mapping Meraki network names to NetBox site names. Validated against allowed networks and existing Meraki networks.

All created entities are tagged with:

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

Sites inherit tags from the first network in the group; devices inherit tags from Meraki device data.

APIs used: getOrganization, getOrganizationNetworks, getOrganizationConfigTemplates, getOrganizationDevices, getOrganizationDevicesStatuses, getNetworkFloorPlans, getNetworkApplianceVlans, getNetworkApplianceVlansSettings, getNetworkApplianceSingleLan, getNetworkAppliancePorts, getNetworkSwitchStacks, getNetworkSwitchLinkAggregations, getDeviceWirelessRadioSettings, getDeviceSwitchPorts, getDeviceManagementInterface, getNetworkWirelessSsids, getNetworkApplianceVlans (per network).
Rate limiting: Meraki SDK with wait_on_rate_limit=True, maximum_retries=4.
Device filtering: Only productType in wireless, switch, appliance; devices filtered by allowed networks (networkId in allowed list).
Primary IP: Set from management interface static IPs; first IPv4 and first IPv6 by interface name (non–link-local). Inactive stack members do not get primary IP.
Prefixes: Derived from all interface IP addresses; single-host (/32, /128) excluded.
Single LAN: When appliance network has vlansEnabled=false, Single LAN config used; one "LAN" interface and one IP created.