Technical Information

Cisco Catalyst Center to NetBox Object Mapping

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

Object Type Mapping Table

Cisco Catalyst Center Object	NetBox Object Type	Key Fields Mapped	Mapping Details
Site (building)	Site	name → name
name → slug
Location attributes → physical_address, latitude, longitude
id → custom_fields.catalyst_id	Only sites with type building (in additionalInfo → Location attributes) are created as NetBox sites. Address and GPS from Location namespace. Site filtering via policy scope sites (default ["*"]).
Site (default)	Site	Static name "Default Site", slug "default-site"	Used for devices not assigned to any building site in Catalyst Center.
Location (floor)	Location	name → name
name → slug
parentId → site
id → custom_fields.catalyst_location_id	Floor-type sites (Location type floor) with parent in allowed building sites. One Location per floor; parent site is the building.
Network Device (standalone)	Device	hostname → name
platformId → device_type.model
serialNumber → serial
reachabilityStatus → status
role → role
softwareType + softwareVersion → platform
Site/floor from mappings
managementIpAddress → primary_ip4 / primary_ip6 (via IP entity)	custom_fields: catalyst_device_id (device id), catalyst_serial_number. Device tags from Catalyst Center tag API. Serial truncated to 50 chars.
Network Device (stack member)	Device	hostname + stackMemberNumber → name
platformId (member) → device_type
serialNumber (member) → serial
softwareImage (member) → platform version
role (member) → catalyst_stack_role
reachabilityStatus → status	Key: device_id-member_serialNumber. custom_fields: catalyst_stack_id, catalyst_stack_role (ACTIVE/STANDBY/MEMBER), catalyst_serial_number. Master = role ACTIVE; vc_position 1 for master, 2+ for others.
Virtual Chassis (switch stack)	VirtualChassis	hostname → name
Key: device_id	Created when device has comma in serialNumber and stack API returns stackSwitchInfo. One VirtualChassis per stack device.
Device Type	DeviceType	platformId → model
model → slug (backend slugify)
Manufacturer: Cisco	One device type per platform ID (standalone and stack members).
Device Role	DeviceRole	role → name	From device role; default "Network Device".
Platform	Platform	softwareType + softwareVersion → name
Stack member: softwareImage used for version	One platform per unique name; linked to manufacturer.
Manufacturer	Manufacturer	Static → name "Cisco"	Single manufacturer for all devices.
Interface	Interface	portName → name
portType / portName → type (heuristics)
adminStatus → enabled
mtu → mtu
speed → speed
duplex → duplex
portMode → mode
description → description
macAddress → primary_mac_address (uppercase)	Key: (instanceUuid, interface_id). For stack devices, interface assigned to member by name (e.g. GigabitEthernet1/0/1 → member 1) or to ACTIVE master if format doesn't match. MTU only if > 0.
IP Address	IPAddress	ipv4Address + ipv4Mask or addresses[].address → address (CIDR)
Interface → assigned_object_interface
status "active"	From interface IPv4 and/or addresses list. Management IP matched to set device primary_ip4 or primary_ip6. IPv6 supported (mask → prefix length).
MAC Address	MACAddress	macAddress → mac_address (uppercase)
Interface → assigned_object_interface	One MAC entity per interface that has a MAC.
Prefix	Prefix	Derived from IP address networks	Network of each interface IP; /32 and /128 skipped. status "active", scope_site from interface's device 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.