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.18.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.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 |
|---|---|
The interval, in seconds, for polling Cisco Catalyst Center. Default: |
|
A list of faulty and replacement device details for initiating the RMA workflow. |
|
The IP address of the faulty device. Example: 204.192.3.40 |
|
The name or hostname of the faulty device. Example: SJ-EN-9300.cisco.local |
|
The serial number of the faulty device. Example: FJC2327U0S2 |
|
The IP address of the replacement device. Example: 204.1.2.5 |
|
The name or hostname of the replacement device. Example: SJ-EN-9300.cisco.local |
|
The serial number of the replacement device. Example: FCW2225C020 |
|
Set to True to verify the Cisco Catalyst Center configuration 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 number of times to retry resynchronization. Default: |
|
The interval, in seconds, between resynchronization retries. Default: |
|
The desired state of the device replacement workflow. Choices:
|
|
The timeout interval, in seconds, for operations. Default: |
|
Flag for Cisco Catalyst Center SDK to enable the validation of request bodies against a JSON schema. Choices:
|
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_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
- 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 |
|---|---|
Object with API execution details as returned by the Cisco Catalyst Center Python SDK. Returned: always Sample: |
|
Object with API execution details as returned by the Cisco Catalyst Center Python SDK. Returned: always Sample: |
|
Object with API execution details as returned by the Cisco Catalyst Center Python SDK. Returned: always Sample: |
|
Object with API execution details as returned by the Cisco Catalyst Center Python SDK. Returned: always Sample: |