CloudEnterprise
Technical Information
Cisco Meraki to NetBox Object Mapping
This document provides a comprehensive mapping of Cisco Meraki object types to their corresponding NetBox object types, based on the integration implementation.
Object Type Mapping Table
| Cisco Meraki Object | NetBox Object Type | Key Fields Mapped | Mapping Details |
|---|---|---|---|
| Network | Site | Resolved name → name | |
name → slug | |||
Floor plan center → latitude, longitude | |||
First network tags → tags | |||
All networks → custom_fields.meraki_networks (JSON) | |||
First network configTemplateId → group (SiteGroup) | Networks grouped by resolved site name (see Network-to-Site Resolution). Site-level fields from first network in group; all network metadata in meraki_networks. Coordinates from first network's first floor plan center (default Meraki coords filtered out). | ||
| Configuration Template | SiteGroup | name → name | |
name → slug | |||
Full template API → custom_fields.meraki_template_metadata (JSON) | One SiteGroup per Meraki config template. Sites bound to a template link to this group. | ||
| Device (standalone or stack member) | Device | name or serial → name | |
model → device_type | |||
serial → serial | |||
productType → role | |||
firmware + model prefix → platform | |||
Status API → status | |||
tags → tags | |||
Network configTemplateId → custom_fields.meraki_template_id | custom_fields: meraki_serial; stack members also meraki_stack_id, meraki_stack_name. Only productTypes wireless, switch, appliance are supported. Device filtered by allowed networks. | ||
| Switch Stack | VirtualChassis | name or id → name | |
Key: stack id | One VirtualChassis per stack from getNetworkSwitchStacks. Master = member with role active; non-master get vc_position. | ||
| Device Type | DeviceType | model → model | |
| Manufacturer: Cisco | One device type per model. | ||
| Device Role | DeviceRole | productType → name | wireless → "Wireless AP", switch → "Switch", appliance → "Firewall". |
| Platform | Platform | model prefix (MR/MS/MX) + firmware → name | e.g. "Meraki MR 1.2.3". One platform per unique name; linked to manufacturer. |
| Manufacturer | Manufacturer | Static → name "Cisco" | Single manufacturer for all devices. |
| Wireless LAN | WirelessLAN | name → ssid | |
enabled → status | |||
authMode → auth_type | |||
encryptionMode → auth_cipher | |||
scope_site | |||
defaultVlanId (Bridge mode) → vlan | |||
RADIUS keys → custom_fields.meraki_radius_config (JSON) | Only enabled SSIDs with non-empty name. Key: (network_id, ssid_name). VLAN link when ipAssignmentMode is Bridge mode. | ||
| VLAN | VLAN | id → vid | |
name → name | |||
status "active" | |||
group = VLANGroup | Appliance networks only. Key: (network_id, vlan_id). SSID default VLAN name may be updated. | ||
| VLAN Group | VLANGroup | network.name → name "… VLANs" | |
slug | |||
scope_site (resolved site) | |||
description | One per network. Key: network_id. | ||
| Interface | Interface | Varies by device type (see Interface section) | Key: (device_serial, interface_name). Includes radios (MR), switch ports (MS), appliance physical/VLAN/Single LAN (MX), management interfaces, and LAGs. |
| IP Address | IPAddress | Appliance VLAN: applianceIp + subnet/CIDR | |
| Single LAN: applianceIp | |||
Management: staticIp + staticSubnetMask | |||
IPv6: staticApplianceIp6 + prefix | VLAN gateway IPs on VLAN interfaces; Single LAN IP on LAN interface; static management IPs on management interfaces. status "active". | ||
| MAC Address | MACAddress | Device mac → mac_address (uppercase) | |
| Assigned to first management interface (alphabetically) | One MAC per device with management interface config; attached to first management interface by name. | ||
| Prefix | Prefix | Derived from IP address networks | From interface IPs; /32 and /128 skipped. status "active", scope_site from device site. |
Field Mapping Details
Device Status Mapping
| Meraki status (getOrganizationDevicesStatuses) | NetBox Status |
|---|---|
online | active |
alerting | active |
offline | offline |
dormant | inventory |
| Any other / no status | active |
Wireless LAN Status Mapping
| Meraki SSID enabled | NetBox Status |
|---|---|
true | active |
false | disabled (SSIDs with enabled=false are skipped) |
Device Role Mapping
| Meraki productType | NetBox Device Role |
|---|---|
wireless | Wireless AP |
switch | Switch |
appliance | Firewall |
Authentication Type Mapping
| Meraki authMode | NetBox Auth Type |
|---|---|
open | open |
psk | wpa-personal |
8021x-meraki | wpa-enterprise |
8021x-radius | wpa-enterprise |
ipsk-with-radius | wpa-enterprise |
| Any other value | open |
Authentication Cipher Mapping
| Meraki encryptionMode | NetBox Auth Cipher |
|---|---|
wep | wep |
wpa | tkip |
wpa-eap | tkip |
wpa2 | aes |
wpa2-eap | aes |
open | auto |
| Any other value | auto |
VLAN Status Mapping
| Meraki VLAN | NetBox Status |
|---|---|
| All VLANs from API | active |
Network-to-Site Resolution
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.
Interface Types by Device Role
| 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). |
LAG Interfaces
- 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.
Site Groups (Templates)
- Built from getOrganizationConfigTemplates. Site is linked to SiteGroup when its first network has configTemplateId. meraki_template_metadata stores full template API response.
Custom Fields
| 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) |
Policy Configuration
- 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.
Tags and Metadata
All created entities are tagged with:
ciscomerakidiscovered
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.
API and Behavior Notes
- 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.