Technical Information

Cisco Catalyst Center to NetBox Object Mapping

Object Type Mapping Table

Catalyst Center Object	NetBox Object	Key Attributes
Site (building)	Site	name, slug, physical_address, latitude, longitude, custom_fields.catalyst_id
(static)	Site	name "Default Site" (for devices with no site assignment)
Site (floor)	Location	name, slug, parent site, custom_fields.catalyst_location_id
Network Device (standalone)	Device	hostname → name, platformId → device_type, serialNumber → serial, reachabilityStatus → status, role, platform, custom_fields.catalyst_device_id, custom_fields.catalyst_serial_number
Network Device (stack member)	Device	hostname+stackMemberNumber → name, member platformId → device_type, member serialNumber → serial, custom_fields.catalyst_stack_id, custom_fields.catalyst_stack_role, custom_fields.catalyst_serial_number
Stack	VirtualChassis	hostname → name
platformId	DeviceType	model, manufacturer "Cisco"
role	DeviceRole	name (default "Network Device")
softwareType + softwareVersion	Platform	name
(static)	Manufacturer	name "Cisco"
Interface	Interface	portName → name, portType → type, adminStatus → enabled, mtu, speed, duplex, portMode → mode, description, macAddress → primary_mac_address
Interface IP	IPAddress	address (CIDR), status "active"
Interface macAddress	MACAddress	mac_address (uppercase)
(derived from interface IPs)	Prefix	prefix, status "active", scope_site

Field Mapping Details

Device Status Mapping

Catalyst Center reachabilityStatus	NetBox Status
Reachable	active
Any other value	offline

Interface Type Mapping

Uses both portType and portName (lowercase). First match wins.

Condition	NetBox Interface Type
"vlan" in portType or portName starts with "vlan"	virtual
"loopback" in portType or portName starts with "lo"	virtual
"port-channel" in portType or portName starts with "po"	lag
"tengig" in portType or portName starts with "te"	10gbase-t
"gigabit" in portType or portName starts with "gi"	1000base-t
"fast" in portType or portName starts with "fa"	100base-tx
"ethernet" in portType or "eth" in portName	1000base-t
No portType	other
Default	virtual

Interface Mode Mapping

Catalyst Center portMode	NetBox Mode
access	access
Any other value	None

Interface Duplex Mapping

Catalyst Center duplex	NetBox Duplex
full, fdx	full
half, hdx	half
auto, a-full, a-half, auto-full, auto-half	auto
Any other value	auto

Speed Parsing

Format	Result
Numeric (int/float)	Used as-is (e.g. 1000000)
String with "G"	Value × 1,000,000 (e.g. "1G" → 1000000)
String with "M"	Value × 1,000 (e.g. "100M" → 100000)
String with "K"	Value as integer (e.g. "1000K" → 1000)
Other parseable number	Integer value
Invalid / empty	None

Site and Location Logic

• Sites: Fetched from /dna/intent/api/v1/site. Only entries with additionalInfo → Location attributes type == "building" are created as NetBox sites. Filtering: scope.sites list (default ["*"] = all). Configured site names must exist as building names or validation fails.
• Locations: Sites with Location type == "floor" and parentId in the allowed site set become NetBox Locations under the parent building Site.
• Device → site: device_to_site_mapping built via /dna/intent/api/v1/membership/\{site_id\} per building site. Device instanceUuid → site ID. If device has no site, it is assigned to "Default Site".
• Device → location: device_to_floor_mapping via /dna/intent/api/v1/membership/\{floor_id\}; device assigned to floor Location when present.

Stack Device Detection and Interface Assignment

• Stack device: serialNumber contains a comma and /dna/intent/api/v1/network-device/\{id\}/stack returns stackSwitchInfo.
• Member devices: One Device per stackSwitchInfo member; name \{hostname\}-member-\{stackMemberNumber\}; master is role ACTIVE.
• Interface → member: Interface name parsed as [Type][StackMember]/[Module]/[Port] (e.g. GigabitEthernet1/0/1 → member 1). If format does not match, interface is assigned to the ACTIVE (master) member.

Device Tags

• Tags are fetched from Catalyst Center tag API (/dna/intent/api/v1/tag, paginated) and tag members (/dna/intent/api/v1/tag/\{id\}/member, memberType=networkdevice). Device instanceUuid → list of tag names. These tags are applied to the NetBox Device entity in addition to default tags.

Custom Fields

Custom Field	Object Type	Purpose
catalyst_id	Site	Catalyst Center site ID (building)
catalyst_location_id	Location	Catalyst Center location ID (floor)
catalyst_device_id	Device	Catalyst Center device ID (non-stack devices)
catalyst_serial_number	Device	Serial number from Catalyst Center (device or stack member)
catalyst_stack_id	Device	Stack device ID (stack members only)
catalyst_stack_role	Device	Role in stack: ACTIVE, STANDBY, MEMBER

Policy Configuration

• BOOTSTRAP (optional): When true, only static entities (custom fields, manufacturer) are created; no API calls.
• CCC_HOST (required when not BOOTSTRAP): Catalyst Center base URL.
• CCC_USER (required when not BOOTSTRAP): Username for API authentication.
• CCC_PWD (required when not BOOTSTRAP): Password for API authentication.
• Scope – sites (optional): List of site names (building names) to ingest; default ["*"] for all. Invalid or missing names cause validation to fail after fetching sites.

Authentication: POST to \{CCC_HOST\}/dna/system/api/v1/auth/token with username/password; token used in X-Auth-Token for subsequent requests.

Tags and Metadata

All created entities are tagged with:

• cisco
• catalyst-center
• discovered

Optional unique tag: catalyst-center-\{host\} when not in bootstrap mode.

Devices additionally receive tags from Catalyst Center tag membership (tag names applied to the device).

API and Behavior Notes

• APIs used: /dna/intent/api/v1/site, /dna/intent/api/v1/membership/\{id\}, /dna/intent/api/v1/network-device, /dna/intent/api/v1/interface (per device), /dna/intent/api/v1/network-device/\{id\}/stack, /dna/intent/api/v1/tag (paginated), /dna/intent/api/v1/tag/\{id\}/member.
• Slugify: Backend slugify: lowercase, spaces → hyphens, remove non-alphanumeric except hyphen, collapse hyphens, strip, default "default" if empty, max 50 characters.
• Prefixes: Derived from IP addresses on interfaces; single-host networks (/32, /128) are not created as prefixes.
• IP CIDR: IPv4 mask converted to prefix length; IPv6 mask parsed to prefix length (default 64 on error).
• Interface key: Interfaces stored by (instanceUuid, interface_id); for stack devices the interface entity is still looked up by root device instanceUuid and interface id, then assigned to the appropriate member device.