cisco.dnac.rma_playbook_config_generator module -- Generate YAML playbooks for RMA device replacement workflows from existing configurations.

Note

This module is part of the cisco.dnac collection (version 6.49.0).

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.rma_playbook_config_generator.

New in cisco.dnac 6.44.0

Synopsis

• Generates YAML playbooks compatible with the rma_workflow_manager module by extracting existing RMA device replacement configurations from Cisco Catalyst Center.

• Reduces manual effort by programmatically retrieving faulty and replacement device details, serial numbers, hostnames, and IP addresses from active device replacement workflows.

• Supports filtering by faulty device serial number, replacement device serial number, and replacement status to generate targeted playbooks.

• Enables complete infrastructure discovery with auto-generation mode when generate_all_configurations is enabled.

• Resolves device serial numbers to hostnames and management IP addresses using both device inventory and PnP (Plug and Play) APIs for replacement devices that have not been fully onboarded.

• Requires Cisco Catalyst Center version 2.3.5.3 or higher for RMA device replacement API support.

Requirements

The below requirements are needed on the host that executes this module.

• dnacentersdk >= 2.9.3

• python >= 3.9

• Cisco Catalyst Center >= 2.3.5.3

Parameters

Parameter	Comments
config list / elements=dictionary / required	A list of configuration filters for generating YAML playbooks compatible with the rma_workflow_manager module. Each configuration entry can include file path specification, component filters, and auto-discovery settings. Multiple configuration entries can be provided to generate separate playbooks with different filter criteria.
component_specific_filters dictionary	Component-level filters to selectively include specific RMA configurations in the generated playbook. Allows fine-grained control over which device replacement workflows are extracted from Cisco Catalyst Center. If generate_all_configurations is true, these filters are ignored and all configurations are retrieved.
components_list list / elements=string	List of RMA component types to include in the generated YAML playbook. Currently supports only device_replacement_workflows for RMA device replacement configurations. If omitted, all supported components are included by default. Choices: :ansible-option-choices-entry:`"device\_replacement\_workflows"`
device_replacement_workflows list / elements=dictionary	Filters for retrieving specific device replacement workflow configurations from Cisco Catalyst Center. Multiple filter entries can be specified to target different devices or statuses. When multiple filter entries are provided, they are combined into a single filter (AND logic). If no filters are provided, all device replacement workflows are retrieved.
faulty_device_serial_number string	Serial number of the faulty device to filter device replacement workflows. Must be an 11-character alphanumeric string matching the device serial number in Cisco Catalyst Center. Example: FJC2327U0S2
replacement_device_serial_number string	Serial number of the replacement device to filter device replacement workflows. Must be an 11-character alphanumeric string matching the device serial number in Cisco Catalyst Center. Example: FCW2225C020
replacement_status string	Status to filter device replacement workflows by their current replacement state. Valid values: READY-FOR-REPLACEMENT, REPLACEMENT-IN-PROGRESS, REPLACEMENT-SCHEDULED, REPLACED, ERROR, MARKED-FOR-REPLACEMENT
file_path string	Path where the YAML configuration file will be saved. If not provided, the file will be saved in the current working directory with a default file name rma_playbook_config_<YYYY-MM-DD_HH-MM-SS>.yml. For example, rma_playbook_config_2025-04-22_21-43-26.yml. Ensure the directory path exists and has write permissions.
generate_all_configurations boolean	Enables automatic discovery and generation of YAML configurations for all RMA device replacement workflows. When true, retrieves all device replacement workflows from Cisco Catalyst Center without requiring specific filters. Overrides any provided component_specific_filters to ensure complete configuration retrieval. Ideal for complete brownfield infrastructure migration and comprehensive documentation of all RMA workflows. Choices: :ansible-option-choices-entry-default:`false` ← (default) :ansible-option-choices-entry:`true`
global_filters dictionary	Global-level filters that apply across all components. Currently not used by this module but reserved for future extensibility.
dnac_api_task_timeout integer	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: :ansible-option-default:`1200`
dnac_debug boolean	Indicates whether debugging is enabled in the Cisco Catalyst Center SDK. Choices: :ansible-option-choices-entry-default:`false` ← (default) :ansible-option-choices-entry:`true`
dnac_host string / required	The hostname of the Cisco Catalyst Center.
dnac_log boolean	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: :ansible-option-choices-entry-default:`false` ← (default) :ansible-option-choices-entry:`true`
dnac_log_append boolean	Determines the mode of the file. Set to True for 'append' mode. Set to False for 'write' mode. Choices: :ansible-option-choices-entry:`false` :ansible-option-choices-entry-default:`true` ← (default)
dnac_log_file_path string	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: :ansible-option-default:`"dnac.log"`
dnac_log_level string	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: :ansible-option-default:`"WARNING"`
dnac_password string	The password for authentication at the Cisco Catalyst Center.
dnac_port string	Specifies the port number associated with the Cisco Catalyst Center. Default: :ansible-option-default:`"443"`
dnac_task_poll_interval integer	Specifies the interval in seconds between successive calls to the API to retrieve task details. Default: :ansible-option-default:`2`
dnac_username aliases: user string	The username for authentication at the Cisco Catalyst Center. Default: :ansible-option-default:`"admin"`
dnac_verify boolean	Flag to enable or disable SSL certificate verification. Choices: :ansible-option-choices-entry:`false` :ansible-option-choices-entry-default:`true` ← (default)
dnac_version string	Specifies the version of the Cisco Catalyst Center that the SDK should use. Default: :ansible-option-default:`"2.2.3.3"`
state string	The desired state for the module operation. Only gathered state is supported to generate YAML playbooks from existing RMA configurations. Choices: :ansible-option-choices-entry-default:`"gathered"` ← (default)
validate_response_schema boolean	Flag for Cisco Catalyst Center SDK to enable the validation of request bodies against a JSON schema. Choices: :ansible-option-choices-entry:`false` :ansible-option-choices-entry-default:`true` ← (default)

Notes

Note

• Requires minimum Cisco Catalyst Center version 2.3.5.3 for RMA device replacement API support.

• Module will fail with an error if connected to an unsupported version.

• Generated playbooks are compatible with the rma_workflow_manager module for device replacement operations.

• Device serial numbers are resolved to hostnames and management IP addresses via the device inventory API.

• For replacement devices not yet in inventory, the module falls back to the PnP (Plug and Play) API for device resolution.

• PnP devices may not have management IP addresses assigned, resulting in None for the IP address field.

• The module operates in check mode but does not make any changes to Cisco Catalyst Center.

• Use dnac_log and dnac_log_level parameters for detailed operation logging and troubleshooting.

• SDK Methods used are - device_replacement.return_replacement_devices_with_details - devices.get_device_list

• Paths used are - GET /dna/intent/api/v1/device-replacement - GET /dna/intent/api/v1/network-device

• Cisco Catalyst Center version 2.3.5.3 or higher is required for RMA functionality

• Does not support check_mode

• The 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

See Also

See also

cisco.dnac.rma_workflow_manager

Manage RMA (Return Material Authorization) workflows in Cisco Catalyst Center.

Examples

- name: Generate YAML Configuration for all RMA device replacement workflows
  cisco.dnac.rma_playbook_config_generator:
    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: "{{dnac_log_level}}"
    state: gathered
    config:
      - file_path: "/tmp/rma_workflows_config.yaml"
        generate_all_configurations: true

- name: Generate YAML Configuration for specific device replacement workflows
  cisco.dnac.rma_playbook_config_generator:
    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: "{{dnac_log_level}}"
    state: gathered
    config:
      - file_path: "/tmp/rma_specific_workflows.yaml"
        component_specific_filters:
          components_list: ["device_replacement_workflows"]
          device_replacement_workflows:
            - faulty_device_serial_number: "FJC2327U0S2"
            - replacement_status: "READY-FOR-REPLACEMENT"

- name: Generate YAML Configuration for device replacement workflows by replacement device
  cisco.dnac.rma_playbook_config_generator:
    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: "{{dnac_log_level}}"
    state: gathered
    config:
      - file_path: "/tmp/rma_replacement_device_workflows.yaml"
        component_specific_filters:
          components_list: ["device_replacement_workflows"]
          device_replacement_workflows:
            - replacement_device_serial_number: "FCW2225C020"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
response_1 dictionary	A dictionary with the response returned by the Cisco Catalyst Center Returned: always Sample: :ansible-rv-sample-value:`{"msg": "YAML configuration file generated successfully for module 'rma\_workflow\_manager'", "response": {"components\_processed": 1, "components\_skipped": 0, "configurations\_count": 1, "file\_path": "/Users/priyadharshini/Downloads/rma\_info", "message": "YAML configuration file generated successfully for module 'rma\_workflow\_manager'", "status": "success"}, "status": "success"}`
response_2 dictionary	A dict with the response returned by the Cisco Catalyst Center Returned: always Sample: :ansible-rv-sample-value:`"{\\n msg = (\\n \\"No device replacement workflows found to process for module \\"\\n \\"'rma\_workflow\_manager'. Verify that RMA workflows are configured in \\"\\n \\"Catalyst Center or check user permissions.\\"\\n ),\\n \\"response\\": {\\n \\"components\_processed\\": 0,\\n \\"components\_skipped\\": 1,\\n \\"configurations\_count\\": 0,\\n \\"message\\": (\\n \\"No device replacement workflows found to process for module \\"\\n \\"'rma\_workflow\_manager'. Verify that RMA workflows are configured in \\"\\n \\"Catalyst Center or check user permissions.\\"\\n ),\\n \\"status\\": \\"success\\"\\n },\\n \\"status\\": \\"success\\"\\n}\\n"`

Authors

• Priyadharshini B (@pbalaku2)

• Madhan Sankaranarayanan (@madhansansel)

Collection links

Issue Tracker Repository (Sources)