cisco.dnac.network_devices_info_workflow_manager module – Gather facts about network devices from Cisco Catalyst Center (facts/info module) using flexible filters.
Note
This module is part of the cisco.dnac collection (version 6.42.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install cisco.dnac.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: cisco.dnac.network_devices_info_workflow_manager.
New in cisco.dnac 6.31.0
Synopsis
Gathers detailed facts (information) about network devices managed by Cisco Catalyst Center using flexible user-defined filters.
Supports filtering by management IP, MAC address, hostname, serial number, software type, software version, role, device type, family, and site hierarchy.
Allows selection of specific device information types, such as device details, interfaces, VLANs, line cards, supervisor cards, POE, module count, connected devices, configuration, summary, polling interval, stack, and link mismatch details.
Handles query retries, timeouts, and polling intervals for robust data collection.
Supports output to a file using the
output_file_infooption. Output can be JSON or YAML, with user-defined file path, file mode (overwrite or append), and optional timestamp.If
output_file_infois provided, results are written to the file; otherwise, results are returned in the Ansible output.Returns structured results for each requested information type, or an empty list if no devices match the filters after all retries.
This module is tagged as a facts/info module and is safe to use in check mode.
Requirements
The below requirements are needed on the host that executes this module.
dnacentersdk >= 2.9.3
python >= 3.9.19
Parameters
Parameter |
Comments |
|---|---|
List of dictionaries specifying network device query parameters. Each dictionary must contain a |
|
Contains filters and configuration for retrieving network devices information. Requires at least one device identification or filtering criterion. |
|
Device family filter for device category-based filtering. Examples include “Switches and Hubs”, “Routers”, “Wireless Controller”. Choices:
|
|
Optional list of device identification criteria to further filter network devices. Provides granular control over which network devices have their information retrieved. Multiple identification methods can be combined for comprehensive device targeting. Only devices that are both network-enabled and match the identifier criteria will be processed. When multiple identification parameters (ip_address, hostname, serial_number, mac_address) are specified in the same entry, they must all refer to the same physical device for proper validation. Use separate device_identifier entries when targeting different devices with different identification methods. |
|
List of device hostnames to identify specific network devices. Each hostname must match exactly as configured in Cisco Catalyst Center device inventory. Only devices with matching hostnames will have their information retrieved. Hostnames are case-sensitive and must match the exact device hostname configuration. |
|
List of management IP addresses to identify specific network devices. Each IP address must correspond to a managed device in the Cisco Catalyst Center inventory. Only devices with matching IP addresses will have their information retrieved. IP addresses must be valid IPv4 addresses in dotted decimal notation. |
|
List of device MAC addresses to identify specific network devices. Each MAC address must correspond to a managed device in the Cisco Catalyst Center inventory. Only devices with matching MAC addresses will have their information retrieved. MAC addresses should be in standard format (e.g., “aa:bb:cc:dd:ee:ff”). |
|
List of device serial numbers to identify specific network devices. Each serial number must match exactly as recorded in Cisco Catalyst Center device inventory. Only devices with matching serial numbers will have their information retrieved. Serial numbers are case-sensitive and must match the format used by the device manufacturer. |
|
Device role filter for network function-based filtering. Common roles include ACCESS, DISTRIBUTION, CORE, WAN, WLC, DATA_CENTER. Choices:
|
|
Device type filter for specific device models. Examples include “Cisco Catalyst 9300 Switch”, “Cisco Catalyst 9400 Switch”. Choices:
|
|
Time in seconds to wait between retry attempts for device information retrieval operations. Applied as a delay between failed attempts during device lookup filtering processes. Combined with timeout and retries to determine total operation duration. If (retries * interval) exceeds timeout, retries will continue until timeout is reached. Longer intervals help reduce API load on Cisco Catalyst Center during retry operations. Should be balanced with timeout settings to avoid excessively long operation times. Default: |
|
Operating system type filter for software platform filtering. Common types include IOS-XE, IOS, IOS-XR, NX-OS, ASA, FTD. Choices:
|
|
Controls file output generation for network device information retrieval results. When provided, saves retrieved device information to the specified file along with returning the data in standard Ansible module output. Supports flexible file formatting, writing modes, and optional timestamp inclusion for audit purposes. Enables automated reporting and data archival workflows for network device monitoring operations. |
|
Output data format for the generated file. Determines file structure and extension applied to the file path. YAML format provides better human readability while JSON offers programmatic parsing advantages. Format selection affects file extension and data serialization method. Choices:
|
|
File writing mode determining how data is written to the target file. Use ‘w’ to overwrite existing file content or ‘a’ to append new data to existing content. Append mode enables incremental data collection across multiple playbook runs. Overwrite mode ensures clean data sets for each execution. Choices:
|
|
Absolute path to the output file without file extension. File extension is automatically appended based on the selected file format (.json or .yaml). Directory structure will be created automatically if it does not exist. Path must be writable by the user executing the Ansible playbook. |
|
Controls inclusion of data retrieval timestamp in the output file content. When enabled, adds the data collection timestamp as the first entry for audit trail purposes. Useful for tracking when network device information was collected in automated workflows. Timestamp format follows “YYYY-MM-DD HH:MM:SS” standard format. Choices:
|
|
List of device information types to retrieve. If set to [‘all’], retrieves all available information categories. If specific types are listed, only those will be retrieved. If omitted, defaults to all information types. Choices:
|
|
Number of retry attempts for device information retrieval operations when initial attempts fail. Applied to each individual device lookup filtering operation. Higher retry counts improve reliability in environments with intermittent connectivity or high API load. Total operation time is affected by retries combined with timeout and interval settings. Actual retry attempts may be less than specified if timeout period is reached first. Default: |
|
Site hierarchy path for filtering devices by location. |
|
Software version filter for specific software releases. Format example “16.12.05”, “17.6.1”. |
|
Maximum time in seconds to wait for device information retrieval operations to complete. Applied to each individual device lookup operation during the filtering process. If device information retrieval fails within this timeout period, the operation will retry based on the ‘retries’ parameter. Longer timeouts may be needed for environments with slower network connectivity or larger device inventories. If timeout is greater than (retries * interval), the operation will continue retrying until the timeout period ends. Total operation time is bounded by the timeout value regardless of retry configuration. Default: |
|
Set to True to verify the Cisco Catalyst Center after applying the playbook config. Choices:
|
|
Defines the timeout in seconds for API calls to retrieve task details. If the task details are not received within this period, the process will end, and a timeout notification will be logged. Default: |
|
Indicates whether debugging is enabled in the Cisco Catalyst Center SDK. Choices:
|
|
The hostname of the Cisco Catalyst Center. |
|
Flag to enable/disable playbook execution logging. When true and dnac_log_file_path is provided, - Create the log file at the execution location with the specified name. When true and dnac_log_file_path is not provided, - Create the log file at the execution location with the name ‘dnac.log’. When false, - Logging is disabled. If the log file doesn’t exist, - It is created in append or write mode based on the “dnac_log_append” flag. If the log file exists, - It is overwritten or appended based on the “dnac_log_append” flag. Choices:
|
|
Determines the mode of the file. Set to True for ‘append’ mode. Set to False for ‘write’ mode. Choices:
|
|
Governs logging. Logs are recorded if dnac_log is True. If path is not specified, - When ‘dnac_log_append’ is True, ‘dnac.log’ is generated in the current Ansible directory; logs are appended. - When ‘dnac_log_append’ is False, ‘dnac.log’ is generated; logs are overwritten. If path is specified, - When ‘dnac_log_append’ is True, the file opens in append mode. - When ‘dnac_log_append’ is False, the file opens in write (w) mode. - In shared file scenarios, without append mode, content is overwritten after each module execution. - For a shared log file, set append to False for the 1st module (to overwrite); for subsequent modules, set append to True. Default: |
|
Sets the threshold for log level. Messages with a level equal to or higher than this will be logged. Levels are listed in order of severity [CRITICAL, ERROR, WARNING, INFO, DEBUG]. CRITICAL indicates serious errors halting the program. Displays only CRITICAL messages. ERROR indicates problems preventing a function. Displays ERROR and CRITICAL messages. WARNING indicates potential future issues. Displays WARNING, ERROR, CRITICAL messages. INFO tracks normal operation. Displays INFO, WARNING, ERROR, CRITICAL messages. DEBUG provides detailed diagnostic info. Displays all log messages. Default: |
|
The password for authentication at the Cisco Catalyst Center. |
|
Specifies the port number associated with the Cisco Catalyst Center. Default: |
|
Specifies the interval in seconds between successive calls to the API to retrieve task details. Default: |
|
The username for authentication at the Cisco Catalyst Center. Default: |
|
Flag to enable or disable SSL certificate verification. Choices:
|
|
Specifies the version of the Cisco Catalyst Center that the SDK should use. Default: |
|
The desired state of the configuration after module execution. Choices:
|
|
Flag for Cisco Catalyst Center SDK to enable the validation of request bodies against a JSON schema. Choices:
|
Notes
Note
This is a facts/info module, it only retrieves information and does not modify any device or configuration.
Writing to a local file is for reporting/archival purposes only and does not affect the state of any managed device.
Safe to use in check mode.
SDK Methods used are - devices.Devices.get_device_list - devices.Devices.get_device_interface_vlans - devices.Devices.get_device_interfaces_by_specified_range - devices.Devices.get_linecard_details - devices.Devices.inventory_insight_device_link_mismatch - devices.Devices.get_stack_details_for_device - devices.Devices.get_device_config_by_id - devices.Devices.get_polling_interval_by_id - devices.Devices.get_supervisor_card_detail - devices.Devices.poe_details - devices.Devices.get_connected_device_detail - devices.Devices.get_interface_info_by_id - devices.Devices.get_module_count - devices.Devices.get_network_device_by_ip - devices.Devices.get_device_summary
Paths used are - GET/dna/intent/api/v1/network-device - GET/dna/intent/api/v1/network-device/{id}/vlan - GET/dna/intent/api/v1/interface/network-device/{deviceId}/{startIndex}/{recordsToReturn} - GET/dna/intent/api/v1/network-device/{deviceUuid}/line-card - GET/dna/intent/api/v1/network-device/insight/{siteId}/device-link - GET/dna/intent/api/v1/network-device/{deviceId}/stack - GET/dna/intent/api/v1/network-device/{networkDeviceId}/config - GET/dna/intent/api/v1/network-device/{id}/collection-schedule - GET/dna/intent/api/v1/network-device/{id}/brief - GET/dna/intent/api/v1/network-device/{deviceUuid}/supervisor-card - GET/dna/intent/api/v1/network-device/{deviceUuid}/poe - GET/dna/intent/api/v1/network-device/{deviceUuid}/interface/{interfaceUuid}/neighbor - GET/dna/intent/api/v1/interface/network-device/{deviceId} - GET/dna/intent/api/v1/network-device/module/count - GET/dna/intent/api/v1/network-device/ip-address/{ipAddress}
Does not support
check_modeThe plugin runs on the control node and does not use any ansible connection plugins instead embedded connection manager from Cisco Catalyst Center SDK
The parameters starting with dnac_ are used by the Cisco Catalyst Center Python SDK to establish the connection
Examples
# 1 Example Playbook to gather specific network device information from Cisco Catalyst Center
---
- name: Get Specific Network devices information on Cisco Catalyst Center
hosts: localhost
connection: local
vars_files:
- "credentials.yml"
tasks:
- name: Gather detailed facts for specific network devices
cisco.dnac.network_devices_info_workflow_manager:
dnac_host: "{{ dnac_host }}"
dnac_username: "{{ dnac_username }}"
dnac_password: "{{ dnac_password }}"
dnac_verify: "{{ dnac_verify }}"
dnac_port: "{{ dnac_port }}"
dnac_version: "{{ dnac_version }}"
dnac_debug: "{{ dnac_debug }}"
dnac_log: true
dnac_log_level: DEBUG
config_verify: false
dnac_api_task_timeout: 1000
dnac_task_poll_interval: 1
state: queried
config:
- network_devices:
- site_hierarchy: Global/USA/SAN JOSE
device_type: "Cisco Catalyst 9300 Switch"
device_role: "ACCESS"
device_family: "Switches and Hubs"
software_version: "17.12.1"
os_type: "IOS-XE"
device_identifier:
- ip_address: ["204.1.2.2"]
- serial_number: ["FCW2137L0SB"]
- hostname: ["SJ-BN-9300.cisco.local"]
- mac_address: ["90:88:55:90:26:00"]
timeout: 60
retries: 3
interval: 10
requested_info:
- device_info
- interface_info
- interface_vlan_info
- line_card_info
- supervisor_card_info
- poe_info
- module_count_info
- connected_device_info
- device_interfaces_by_range_info
- device_config_info
- device_summary_info
- device_polling_interval_info
- device_stack_info
- device_link_mismatch_info
output_file_info:
file_path: /Users/priyadharshini/Downloads/info
file_format: json
file_mode: w
timestamp: true
# 2 Example Playbook to gather all network device information from Cisco Catalyst Center
- name: Get All Network devices information on Cisco Catalyst Center
hosts: localhost
connection: local
vars_files:
- "credentials.yml"
tasks:
- name: Gather detailed facts for all network devices
cisco.dnac.network_devices_info_workflow_manager:
dnac_host: "{{ dnac_host }}"
dnac_username: "{{ dnac_username }}"
dnac_password: "{{ dnac_password }}"
dnac_verify: "{{ dnac_verify }}"
dnac_port: "{{ dnac_port }}"
dnac_version: "{{ dnac_version }}"
dnac_debug: "{{ dnac_debug }}"
dnac_log: true
dnac_log_level: DEBUG
config_verify: false
dnac_api_task_timeout: 1000
dnac_task_poll_interval: 1
state: queried
config:
- network_devices:
- site_hierarchy: Global/USA/SAN JOSE
device_type: "Cisco Catalyst 9300 Switch"
device_role: "ACCESS"
device_family: "Switches and Hubs"
software_version: "17.12.1"
os_type: "IOS-XE"
device_identifier:
- ip_address: ["204.1.2.2"]
- serial_number: ["FCW2137L0SB"]
- hostname: ["SJ-BN-9300.cisco.local"]
- mac_address: ["90:88:55:90:26:00"]
timeout: 60
retries: 3
interval: 10
requested_info:
- all
output_file_info:
file_path: /Users/priyadharshini/Downloads/info
file_format: json
file_mode: w
timestamp: true
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Details of the response containing information about a connected neighbor device. Returned: always Sample: |
|
Details of the response containing the device configuration as a string. Returned: always Sample: |
|
Device information for network devices, including family, type, software version, serial number, and more. Returned for each device matching the query. Returned: always Sample: |
|
Details of the response containing VLAN information for device interfaces. Returned: always Sample: |
|
Details of the response containing device interface information retrieved by a specified range. Returned: always Sample: |
|
Details of the response containing a summary of the device. Returned: always Sample: |
|
Details of the response containing interface information for a device. Returned: always Sample: |
|
Details of the response containing device link mismatch information from Inventory Insight API. Returned: always Sample: |
|
Details of the response containing linecard information for the device. Returned: always Sample: |
|
Details of the response containing the count of modules. Returned: always Sample: |
|
Details of the response containing network device information retrieved by IP address. Returned: always Sample: |
|
Details of the response containing Power over Ethernet (POE) statistics. Returned: always Sample: |
|
Details of the response containing the polling interval value. Returned: always Sample: |
|
Details of the response containing stack information for the device. Returned: always Sample: |
|
Details of the response containing supervisor card information for the device. Returned: always Sample: |