cisco.dnac.rma_workflow_manager module -- Manage device replacement workflows in Cisco Catalyst Center.

Note

This module is part of the cisco.dnac collection (version 6.24.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_workflow_manager.

New in cisco.dnac 6.6.0

Synopsis 

The purpose of this workflow is to provide a streamlined and efficient process for network administrators, to initiate Return Material Authorization (RMA) requests for faulty network devices. This automation aims to simplify the RMA process, reduce manual effort, and enhance overall operational efficiency.
Implement an RMA (Return Material Authorization) workflow within Cisco Catalyst Center, enabling a seamless process for returning and replacing faulty network devices.
The RMA workflow facilitates the replacement of routers, switches, and Access Points (APs).
Allows administrators to mark devices for replacement and track the entire replacement workflow.
For routers and switches, the software image, configuration, and licenses are restored from the failed device to the replacement device, ensuring minimal disruption.
For wireless APs, the replacement device is assigned to the same site, provisioned with the primary wireless controller, RF profile, and AP group settings, and placed on the same floor map location in Cisco Catalyst Center as the failed AP.
Need to consider the following before doing RMA, - Ensure the software image version of the faulty device is imported into the image repository before initiating the replacement process. - The faulty device must be in an unreachable state to be eligible for RMA. - If the replacement device onboards Cisco Catalyst Center through Plug and Play (PnP), ensure the faulty device is assigned to a user-defined site. - The replacement device must not be in a provisioning state during the initiation of the RMA workflow. - The AP RMA feature supports only like-to-like replacements, meaning the replacement AP must have the same model number and Product ID (PID) as the faulty AP. - The replacement AP must have joined the same Cisco Wireless Controller as the faulty AP. - Cisco Mobility Express APs acting as wireless controllers are not eligible for replacement through this RMA workflow. - Ensure the software image version of the faulty AP is imported into the image repository before initiating the replacement process. - The faulty device must be assigned to a user-defined site if the replacement device onboards Cisco Catalyst Center through Plug and Play (PnP). - The replacement AP must not be in a provisioning state during the initiation of the RMA workflow.

Requirements 

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

dnacentersdk >= 2.7.2
python >= 3.10

Parameters 

Parameter	Comments
ccc_poll_interval integer	The interval, in seconds, for polling Cisco Catalyst Center. Default: :ansible-option-default:`2`
config list / elements=dictionary / required	A list of faulty and replacement device details for initiating the RMA workflow.
faulty_device_ip_address string	The IP address of the faulty device. Example: 204.192.3.40
faulty_device_name string	The name or hostname of the faulty device. Example: SJ-EN-9300.cisco.local
faulty_device_serial_number string	The serial number of the faulty device. Example: FJC2327U0S2
replacement_device_ip_address string	The IP address of the replacement device. Example: 204.1.2.5
replacement_device_name string	The name or hostname of the replacement device. Example: SJ-EN-9300.cisco.local
replacement_device_serial_number string	The serial number of the replacement device. Example: FCW2225C020
config_verify boolean	Set to True to verify the Cisco Catalyst Center configuration after applying the playbook config. Choices: :ansible-option-choices-entry-default:`false` ← (default) :ansible-option-choices-entry:`true`
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"`
resync_retry_count integer	The number of times to retry resynchronization. Default: :ansible-option-default:`1000`
resync_retry_interval integer	The interval, in seconds, between resynchronization retries. Default: :ansible-option-default:`30`
state string	The 'replaced' state is used to indicate the replacement of faulty network devices with replacement network device in the workflow. Choices: :ansible-option-choices-entry-default:`"replaced"` ← (default)
timeout_interval integer	The timeout interval, in seconds, for operations. Default: :ansible-option-default:`100`
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

SDK Method used is - devices.get_device_detail - device_replacement.mark_device_for_replacement - device_replacement.deploy_device_replacement_workflow - device_replacement.unmark_device_for_replacement
Path used is - post /dna/intent/api/v1/device-replacement/workflow - put /dna/intent/api/v1/device-replacement/ - post /dna/intent/api/v1/device-replacement/
limitations
RMA supports the replacement of similar devices only. For instance, a Cisco Catalyst 3650 switch can only be replaced with another Cisco Catalyst 3650 switch. The platform IDs of the faulty and replacement devices must match. The model number of a Cisco device can be fetched using the `show version` command.
RMA supports the replacement of all switches, routers, and Cisco SD-Access devices, except for the following, - Chassis-based Nexus 7700 Series Switches - Devices with embedded wireless controllers - Cisco Wireless Controllers
RMA supports devices with an external SCEP broker PKI certificate. The PKI certificate is created and authenticated for the replacement device during the RMA workflow. The PKI certificate of the replaced faulty device must be manually deleted from the certificate server.
The RMA workflow supports device replacement only if the following conditions are met, - Faulty and replacement devices must have the same extension cards. - The faulty device must be managed by Catalyst Center with a static IP. (RMA is not supported for devices managed by Catalyst Center with a DHCP IP.) - The number of ports in both devices must not vary due to the extension cards. - The replacement device must be connected to the same port to which the faulty device was connected.
Cisco Catalyst Center does not support legacy license deployment.
If the software image installed on the faulty device is earlier than Cisco IOS XE 16.8, the same legacy network license must be manually installed on the replacement device.
The RMA workflow deregisters the faulty device from Cisco SSM and registers the replacement device with Cisco SSM.
Cisco Catalyst Center supports PnP onboarding of the replacement device in a fabric network, except for the following, - The faulty device is connected to an uplink device using multiple interfaces. - LAN automation using an overlapping pool.
If the replacement device onboards through PnP-DHCP functionality, ensure the device receives the same IP address after every reload and that the DHCP lease timeout is longer than two hours.
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

Examples 

- name: RMA workflow for faulty device replacement using device names
  cisco.dnac.rma_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: true
    resync_retry_count: 1000
    resync_retry_interval: 30
    ccc_poll_interval: 2
    timeout_interval: 100
    state: replaced
    config:
      - faulty_device_name: "SJ-EN-9300.cisco.local"
        replacement_device_name: "SJ-EN-9300.cisco-1.local"
  register: result

- name: RMA workflow for faulty device replacement using IP addresses
  cisco.dnac.rma_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: true
    resync_retry_count: 1000
    resync_retry_interval: 30
    ccc_poll_interval: 2
    timeout_interval: 100
    state: replaced
    config:
      - faulty_device_ip_address: "204.192.3.40"
        replacement_device_ip_address: "204.1.2.5"
  register: result

- name: RMA workflow for faulty device replacement using serial numbers
  cisco.dnac.rma_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: true
    resync_retry_count: 1000
    resync_retry_interval: 30
    ccc_poll_interval: 2
    timeout_interval: 100
    state: replaced
    config:
      - faulty_device_serial_number: "FJC2327U0S2"
        replacement_device_serial_number: "FCW2225C020"
  register: result

Return Values 

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

Key	Description
response_1 dictionary	Object with API execution details as returned by the Cisco Catalyst Center Python SDK. Returned: always Sample: :ansible-rv-sample-value:`{"response": {"taskId": "string", "url": "string"}, "version": "string"}`
response_2 dictionary	Object with API execution details as returned by the Cisco Catalyst Center Python SDK. Returned: always Sample: :ansible-rv-sample-value:`{"response": {"taskId": "string", "url": "string"}, "version": "string"}`
response_3 dictionary	Object with API execution details as returned by the Cisco Catalyst Center Python SDK. Returned: always Sample: :ansible-rv-sample-value:`{"response": {"taskId": "string", "url": "string"}, "version": "string"}`
response_4 dictionary	Object with API execution details as returned by the Cisco Catalyst Center Python SDK. Returned: always Sample: :ansible-rv-sample-value:`{"response": {"taskId": "string", "url": "string"}, "version": "string"}`

Authors

Trupti A Shetty (@TruptiAShetty)
A Mohamed Rafeek (@mohamedrafeek)
Madhan Sankaranarayanan (@madhansansel)
Ajith Andrew J (@ajithandrewj)

Collection links

Issue Tracker Repository (Sources)

cisco.dnac.rma_workflow_manager module -- Manage device replacement workflows in Cisco Catalyst Center.

Synopsis

Requirements

Parameters

Notes

Examples

Return Values