> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cisco Catalyst Center

> Connect Serval to your Cisco Catalyst Center appliance so workflows can read network device inventory and sites, and sync both into Serval as assets.

## About Cisco Catalyst Center

Cisco Catalyst Center (formerly Cisco DNA Center) manages campus and branch networks: switches, routers, wireless controllers, and access points, and the site hierarchy they're placed in. This integration connects Serval to your own Catalyst Center appliance so workflows can read its network device inventory and sites, and sync both into Serval as assets. It connects to the appliance you run, not to a Cisco-hosted service.

> [!NOTE]
>
> Most Catalyst Center appliances sit on a private network. For one that isn't reachable from the internet, enable **Run on self-hosted workers** for the connection and use an up-to-date worker and proxy. Every request, including the token exchange, then runs from your network. The worker must be able to reach the appliance and trust its TLS certificate. A self-hosted Serval deployment that is configured to allow internal targets can reach the appliance without a worker.

**Authentication:** Username and password for a Catalyst Center user. Serval stores them encrypted and exchanges them for a short-lived `X-Auth-Token` before each API request, so workflows never handle the credentials. Serval sends them only to the appliance hostname saved on the connection. On a connection that runs on self-hosted workers, the username and password also travel with each API request, from your worker to your appliance.

**Data sync:** No background sync starts when you connect. Data access is on demand through workflows, plus two installable ingestion workflows that sync network devices and sites into Serval as assets.

## What the Cisco Catalyst Center integration enables

| Capability | Description |
| - | - |
| Assurance API access | Workflows use the "Cisco Catalyst Center API request" action to read the device inventory from the Assurance API (`/dna/data/api/v1/...`). The action is typed from Cisco's published Assurance specification. |
| Intent API access | The "Cisco Catalyst Center Intent API request" action calls the Intent API (`/dna/intent/api/...`), which covers what Assurance doesn't, such as sites. Cisco publishes no OpenAPI specification for it, so its responses aren't typed. |
| Asset ingestion | Installable workflows sync network devices and sites into Serval as external assets, each keyed by its Catalyst Center ID. Both install with no approval required. |
| Connection health checks | Three built-in checks confirm the credentials work and the account can read devices and sites. |

## Get your credentials

Serval needs the hostname of your appliance and a Catalyst Center user it can sign in as. Only a user with **SUPER-ADMIN-ROLE** can create users in Catalyst Center.

**1. Create a dedicated user**

In Catalyst Center, go to **System** then **Users & Roles** then **User Management** and add a user for Serval, for example `svc-serval`. A dedicated user keeps the connection working when staff change.

**2. Give it a read-only role**

Assign the built-in **OBSERVER-ROLE**, which can view the inventory and sites but can't configure Catalyst Center or the devices it manages. If you use a custom role instead, it needs read access to Assurance (device inventory) and to the network hierarchy (sites).

**3. Note your appliance hostname**

Use the hostname or IPv4 address you use to reach the Catalyst Center web interface, for example `catalyst.example.com`. IPv6 addresses aren't supported.

> [!NOTE]
>
> The prebuilt workflows only read, but the Intent API request action can also send `POST`, `PUT`, `PATCH`, and `DELETE` requests, including to system APIs under `/dna/system/api/`. The user's role is what limits what a workflow can change, so keep it read-only unless you build workflows that need to write.

## Connect in Serval

**1. Open the Cisco Catalyst Center connect form**

Add a new Cisco Catalyst Center connection from your Serval integrations page.

**2. Enter the Catalyst Center URL**

Enter the hostname or IPv4 address of your appliance, optionally with a port, for example `catalyst.example.com` or `catalyst.example.com:8443`. Serval removes any `https://` prefix and path you paste, and always connects over HTTPS.

**3. Enter the Username and Password**

Enter the user you created and its password. The password is stored encrypted and shown masked after saving.

**4. Save, then check the health checks**

Saving doesn't test the credentials. The health checks run automatically after you connect: confirm they pass before you install the ingestion workflows.

> [!TIP]
>
> A connection stays tied to the appliance it was created for: saving a URL with a different host or port on an existing connection fails, and adding or removing an explicit `:443` counts as a different port. To connect another appliance, add a new connection.

## Verifying the connection

The connection ships three health checks that make live calls to your appliance:

* **Validate API connection:** exchanges the credentials for a token and counts the network devices that reported in over the last 14 days. Ingestion uses the same 14-day window, so a sync should pick up the same devices.
* **List network devices:** reads one device from the Assurance inventory.
* **List sites:** reads one site from the Intent API.

**Validate API connection** reads the Assurance API's device count, so when it passes, the credentials and the network path work. **List network devices** confirms the user can also read the device inventory itself. If **List sites** fails while the others pass, the user's role is probably missing read access to the network hierarchy, or your release no longer serves the site endpoint Serval uses (see below).

## Syncing Catalyst Center inventory into Serval

Install the ingestion workflows you need and use them as asset sync sources:

| Workflow | Synced as assets | Asset key |
| - | - | - |
| Ingest Devices from Cisco Catalyst Center | Every network device that reported in over the last 14 days, with the full Assurance record: name, device family and type, serial number, management IP address, vendor, platform and series, OS type and software version, site, and reachability state | Catalyst Center device ID, or the serial number when a device has no ID. A record with neither is skipped. |
| Ingest Sites from Cisco Catalyst Center | Every site, named by its full site hierarchy, for example `Global/USA/San Jose/Building 1` | Catalyst Center site ID |

Each device record carries its `siteId`, the Catalyst Center ID of its site, which matches the external ID of that site's asset.

## Gotchas and troubleshooting

> [accordion] Your appliance must be reachable from Serval
>
> Confirm the hostname is correct and reachable from the worker or Serval deployment serving the connection. For a private appliance, check that **Run on self-hosted workers** is enabled and that your worker and proxy are up to date.

> [accordion] The appliance needs a trusted TLS certificate
>
> Serval verifies the appliance's certificate. An appliance still serving the self-signed certificate it ships with fails to connect. Replace it with a certificate signed by a CA that your worker or Serval deployment trusts.

> [accordion] Devices that haven't reported in 14 days aren't synced
>
> The Assurance API reports over a time window rather than returning a standing inventory. Serval asks for the last 14 days, so a device that hasn't reported in for longer drops out of the sync. Its asset is deleted only if **Delete missing items** is on for that sync source; otherwise the asset stays but stops being updated.

> [accordion] Device sync needs the Assurance network devices API
>
> Device sync and the **List network devices** check read `/dna/data/api/v1/networkDevices`, and **Validate API connection** reads its `/count` endpoint. If your Catalyst Center release doesn't serve that API, they fail while site sync keeps working.

> [accordion] List network devices reports no devices
>
> The **List network devices** check reads with the Assurance API's default window, about the last 30 minutes. A message that starts "Connected, but the appliance reported no network devices" means the connection works but no device reported in that window. **Validate API connection** shows the 14-day count that ingestion uses.

> [accordion] Every request signs in again
>
> Serval requests a new token before each API call instead of caching one, so a full device sync makes about one sign-in per 300 devices. Because no token is cached, rotating the user's password or disabling the user breaks the connection on the very next request. After rotating the password, edit the connection and enter the new one.

> [accordion] Site sync uses the original site endpoint
>
> Site ingestion and the **List sites** check read `/dna/intent/api/v1/site`. Cisco superseded it with `/dna/intent/api/v1/sites` in release 2.3.7.6 but still serves it. If a release you upgrade to stops serving it, site sync and that check fail while device sync keeps working.

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Cisco Catalyst Center integration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.