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

ccc_poll_interval

integer

The interval, in seconds, for polling Cisco Catalyst Center.

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:

  • false ← (default)

  • 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: 1200

dnac_debug

boolean

Indicates whether debugging is enabled in the Cisco Catalyst Center SDK.

Choices:

  • false ← (default)

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

  • false ← (default)

  • true

dnac_log_append

boolean

Determines the mode of the file. Set to True for ‘append’ mode. Set to False for ‘write’ mode.

Choices:

  • false

  • 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: "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: "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: "443"

dnac_task_poll_interval

integer

Specifies the interval in seconds between successive calls to the API to retrieve task details.

Default: 2

dnac_username

aliases: user

string

The username for authentication at the Cisco Catalyst Center.

Default: "admin"

dnac_verify

boolean

Flag to enable or disable SSL certificate verification.

Choices:

  • false

  • true ← (default)

dnac_version

string

Specifies the version of the Cisco Catalyst Center that the SDK should use.

Default: "2.2.3.3"

resync_retry_count

integer

The number of times to retry resynchronization.

Default: 1000

resync_retry_interval

integer

The interval, in seconds, between resynchronization retries.

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:

  • "replaced" ← (default)

timeout_interval

integer

The timeout interval, in seconds, for operations.

Default: 100

validate_response_schema

boolean

Flag for Cisco Catalyst Center SDK to enable the validation of request bodies against a JSON schema.

Choices:

  • false

  • 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: {"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: {"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: {"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: {"response": {"taskId": "string", "url": "string"}, "version": "string"}

Authors

  • Trupti A Shetty (@TruptiAShetty)

  • A Mohamed Rafeek (@mohamedrafeek)

  • Madhan Sankaranarayanan (@madhansansel)

  • Ajith Andrew J (@ajithandrewj)