cisco.dnac.fabric_devices_info_workflow_manager module – Comprehensive fabric device information gathering module for Cisco Catalyst Center with advanced filtering and output capabilities.
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.fabric_devices_info_workflow_manager.
New in cisco.dnac 6.32.0
Synopsis
Retrieves comprehensive fabric device information from Cisco Catalyst Center using flexible, user-defined filtering criteria.
Supports device identification through fabric site hierarchy and optional fabric device role filtering for targeted information retrieval.
Enables selective information retrieval across six categories are fabric configuration details, Layer 2/3 handoff configurations, device onboarding status, connected neighbor devices, health metrics, and active issues.
Implements robust data collection with configurable retry mechanisms, timeout handling, and polling intervals for reliable operation in enterprise environments.
Provides flexible file output capabilities using the
output_file_infoparameter with support for JSON and YAML formats, configurable file modes (overwrite or append), and optional timestamp inclusion.When
output_file_infois specified, results are written to the designated file. otherwise, results are returned in the standard Ansible module output.Returns structured data for each requested information category, or an empty result set when no devices match the specified filter criteria after exhausting all retry attempts.
Operates as a read-only facts/info module ensuring safe execution in check mode without modifying device configurations.
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 fabric device query parameters. |
|
Defines fabric device filtering criteria to retrieve information from Software-Defined Access (SDA) fabric sites. Each device entry must include the fabric_site_hierarchy parameter to identify the fabric site. Optional device_identifier parameter provides additional filtering capabilities within the fabric site. |
|
Optional list of device identification criteria to further filter fabric devices within the specified fabric site. Provides granular control over which fabric devices have their information retrieved. If omitted, all fabric devices within the fabric site hierarchy (and optional role filter) are processed. Multiple identification methods can be combined for comprehensive device targeting. Only devices that are both fabric-enabled and match the identifier criteria will be processed. For IP-based identification, specify either ip_address (for individual IPs) OR ip_address_range (for IP ranges), not both in the same device_identifier entry. When multiple identification parameters (ip_address, hostname, serial_number) 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 fabric devices. Each hostname must match exactly as configured in Cisco Catalyst Center device inventory. Only devices with matching hostnames that are also fabric-enabled 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 fabric devices within specified fabric site. Each IP address must correspond to a managed device in the Cisco Catalyst Center inventory. Only devices with matching IP addresses that are also fabric-enabled will have their information retrieved. IP addresses must be valid IPv4 addresses in dotted decimal notation. Cannot be used together with ip_address_range parameter - choose one identification method per device_identifier entry. Mutually exclusive with ip_address_range - specify either ip_address OR ip_address_range, not both. |
|
IP address range specification for bulk device identification within specified fabric sites. Format “start_ip-end_ip” (e.g., “192.168.1.1-192.168.1.50”) for contiguous IP ranges. Range is automatically expanded into individual IP addresses for processing. Only fabric-enabled devices within the specified range will have their information retrieved. Useful for targeting entire subnets or network segments within fabric deployments. Cannot be used together with ip_address parameter - choose one identification method per device_identifier entry. Mutually exclusive with ip_address - specify either ip_address_range OR ip_address, not both. |
|
List of device serial numbers to identify specific fabric devices. Each serial number must match exactly as recorded in Cisco Catalyst Center device inventory. Only devices with matching serial numbers that are also fabric-enabled will have their information retrieved. Serial numbers are case-sensitive and must match the format used by the device manufacturer. |
|
Optional filter to restrict fabric device information retrieval to specific fabric roles. When specified, only fabric devices with the matching role will have their information retrieved. If omitted, all fabric devices within the specified fabric site hierarchy are included. Role-based filtering improves performance for large fabric deployments by reducing the scope of devices processed. Choices:
|
|
Hierarchical path of the fabric site to query for fabric device information. Must be an existing site configured as a Software-Defined Access (SDA) fabric site in Cisco Catalyst Center. Site path must follow the full hierarchical structure (e.g., “Global/Region/Building/Floor”). All fabric devices within this site hierarchy will be included unless further filtered by other parameters. Site hierarchy paths must match exactly as configured in Cisco Catalyst Center’s site management structure. |
|
Time in seconds to wait between retry attempts for device information retrieval operations. Applied as a delay between failed attempts during device lookup and fabric 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: |
|
Controls file output generation for fabric 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 fabric 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 fabric device information was collected in automated workflows. Timestamp format follows “YYYY-MM-DD HH:MM:SS” standard format. Choices:
|
|
List of fabric device information types to retrieve for each identified fabric device. If omitted or empty, all available information categories will be retrieved by default. Selective information retrieval improves performance and reduces API load for large fabric deployments. Each information type corresponds to specific Cisco Catalyst Center APIs and data sources. Choices:
|
|
Number of retry attempts for device information retrieval operations when initial attempts fail. Applied to each individual device lookup and fabric device 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: |
|
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 that only retrieves information and does not modify any device configurations or network state.
Writing to a local file is for reporting, archival, and audit purposes only and does not affect the state of any managed devices.
Module is safe to use in check mode as it performs read-only operations against Cisco Catalyst Center APIs.
Fabric device filtering automatically identifies SDA fabric-enabled devices from the specified fabric site hierarchy.
The fabric_site_hierarchy parameter is required and must reference an existing SDA fabric site in Cisco Catalyst Center.
Device identification through device_identifier parameters provides granular control over which fabric devices are processed.
Information retrieval is optimized based on device capabilities - SSID details are only retrieved for wireless controllers, handoff information is role-specific.
Retry mechanisms with configurable timeout, retry count, and polling intervals ensure reliable data collection in enterprise-scale deployments.
Requires Cisco Catalyst Center version 2.3.7.9 or later for fabric device information retrieval functionality.
File output supports both JSON and YAML formats with flexible writing modes (overwrite/append) and optional timestamp inclusion for audit trails.
Module handles mixed wired and wireless fabric environments automatically, applying appropriate API calls based on device type detection.
SDK Methods used are - devices.Devices.get_device_list - sda.Sda.get_fabric_devices - sda.Sda.get_fabric_sites - sda.Sda.get_fabric_devices_layer3_handoffs_with_sda_transit - sda.Sda.get_fabric_devices_layer3_handoffs_with_ip_transit - sda.Sda.get_fabric_devices_layer2_handoffs - devices.Devices.get_interface_info_by_id - devices.Devices.get_connected_device_detail - devices.Devices.devices - issues.Issues.issues - sda.Sda.get_provisioned_wired_device - sda.Sda.get_port_assignments - wireless.Wireless.get_ssid_details_for_specific_wireless_controller
Paths used are - GET/dna/intent/api/v1/network-device - GET/dna/intent/api/v1/sda/fabricDevices - GET/dna/intent/api/v1/sda/fabricSites - GET/dna/intent/api/v1/sda/fabricDevices/layer3Handoffs/sdaTransits - GET/dna/intent/api/v1/sda/fabricDevices/layer3Handoffs/ipTransits - GET/dna/intent/api/v1/sda/fabricDevices/layer2Handoffs - GET/dna/intent/api/v1/interface/network-device/{deviceId} - GET/dna/intent/api/v1/network-device/{deviceUuid}/interface/{interfaceUuid}/neighbor - GET/dna/intent/api/v1/device-health - GET/dna/intent/api/v1/issues - GET/dna/intent/api/v1/business/sda/provision-device - GET/dna/intent/api/v1/sda/portAssignments - GET/dna/intent/api/v1/wireless/controller/{networkDeviceId}/ssidDetails
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
# Case 1: Retrieves all information for devices that are part of the fabric, from Cisco Catalyst Center.
- name: Get Fabric device information from Cisco Catalyst Center
hosts: localhost
connection: local
vars_files:
- "credentials.yml"
tasks:
- name: Gather detailed facts for specific fabric devices
cisco.dnac.fabric_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
dnac_api_task_timeout: 1000
dnac_task_poll_interval: 1
state: gathered
config:
- fabric_devices:
- fabric_site_hierarchy: "Global/rishipat_area/Fabric-area-1" # Mandatory parameter
fabric_device_role: "CONTROL_PLANE_NODE"
device_identifier:
- ip_address: ["192.168.200.69"]
- serial_number: ["FJC272121AG"]
- hostname: ["SJ-BN-9300.cisco.local"]
timeout: 30
retries: 3
interval: 10
output_file_info:
file_path: /Users/priyadharshini/Downloads/fabric_device_info
file_format: yaml
file_mode: a
timestamp: true
# Case 2: Retrieves specific information for devices that are part of the fabric, from Cisco Catalyst Center.
- name: Get Fabric device information from Cisco Catalyst Center
hosts: localhost
connection: local
vars_files:
- "credentials.yml"
tasks:
- name: Gather detailed facts for specific fabric devices
cisco.dnac.fabric_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
dnac_api_task_timeout: 1000
dnac_task_poll_interval: 1
state: gathered
config:
- fabric_devices:
- fabric_site_hierarchy: "Global/rishipat_area/Fabric-area-1" # Mandatory parameter
fabric_device_role: "CONTROL_PLANE_NODE"
device_identifier:
- ip_address: ["192.168.200.69"]
- serial_number: ["FJC272121AG"]
- hostname: ["SJ-BN-9300.cisco.local"]
timeout: 30
retries: 3
interval: 10
requested_info:
- fabric_info
- handoff_info
- onboarding_info
- connected_devices_info
- device_health_info
- device_issues_info
output_file_info:
file_path: /Users/priyadharshini/Downloads/fabric_device_info
file_format: json
file_mode: w
timestamp: true
# Case 3: Retrieves all information for devices that are part of the fabric, from Cisco Catalyst Center.
- name: Get Fabric device information from Cisco Catalyst Center
hosts: localhost
connection: local
vars_files:
- "credentials.yml"
tasks:
- name: Gather detailed facts for specific fabric devices
cisco.dnac.fabric_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
dnac_api_task_timeout: 1000
dnac_task_poll_interval: 1
state: gathered
config:
- fabric_devices:
- fabric_site_hierarchy: "Global/rishipat_area/Fabric-area-1" # Mandatory parameter
fabric_device_role: "CONTROL_PLANE_NODE"
device_identifier:
- ip_address: ["192.168.200.69"]
- serial_number: ["FJC272121AG"]
- hostname: ["SJ-BN-9300.cisco.local"]
timeout: 30
retries: 3
interval: 10
requested_info:
- all
output_file_info:
file_path: /Users/priyadharshini/Downloads/fabric_device_info
file_format: yaml
file_mode: a
timestamp: true
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
All fabric related information for filtered fabric devices. Returned for each fabric device matching the filters. Returned: always Sample: |
|
Connected device information for filtered fabric devices. Returned for each fabric device matching the filters. Returned: always Sample: |
|
Health information for filtered fabric devices. Returned for each fabric device matching the filters. Returned: always Sample: |
|
Issue information for filtered fabric devices. Returned for each fabric device matching the filters. Returned: always Sample: |
|
Handoff information for filtered fabric devices. Returned for each fabric device matching the filters. Returned: always Sample: |
|
Fabric information for filtered fabric devices Returned for each fabric device matching the filters. Returned: always Sample: |
|
Returned when no fabric devices match the provided filters. Returned: always Sample: |
|
Onboarding information for filtered fabric devices. Returned for each fabric device matching the filters. Returned: always Sample: |