cisco.catalystcenter.pnp_workflow_manager module -- Resource module for Site and PnP related functions

Note

This module is part of the cisco.catalystcenter collection (version 2.9.1).

To install it, use: ansible-galaxy collection install cisco.catalystcenter. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: cisco.catalystcenter.pnp_workflow_manager.

New in cisco.catalystcenter 6.28.0

Synopsis 

Manage operations add device, claim device and unclaim device of Onboarding Configuration(PnP) resource
API to add device to pnp inventory and claim it to a site.
API to delete device from the pnp inventory.
API to reset the device from errored state.

Requirements 

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

catalystcentersdk >= 3.1.6.0.2
python >= 3.9

Parameters 

Parameter	Comments
catalystcenter_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`
catalystcenter_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`
catalystcenter_host string / required	The hostname of the Cisco Catalyst Center.
catalystcenter_log boolean	Flag to enable/disable playbook execution logging. When true and catalystcenter_log_file_path is provided, - Create the log file at the execution location with the specified name. When true and catalystcenter_log_file_path is not provided, - Create the log file at the execution location with the name 'catalystcenter.log'. When false, - Logging is disabled. If the log file doesn't exist, - It is created in append or write mode based on the "catalystcenter_log_append" flag. If the log file exists, - It is overwritten or appended based on the "catalystcenter_log_append" flag. Choices: :ansible-option-choices-entry-default:`false` ← (default) :ansible-option-choices-entry:`true`
catalystcenter_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)
catalystcenter_log_file_path string	Governs logging. Logs are recorded if catalystcenter_log is True. If path is not specified, - When 'catalystcenter_log_append' is True, 'catalystcenter.log' is generated in the current Ansible directory; logs are appended. - When 'catalystcenter_log_append' is False, 'catalystcenter.log' is generated; logs are overwritten. If path is specified, - When 'catalystcenter_log_append' is True, the file opens in append mode. - When 'catalystcenter_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:`"catalystcenter.log"`
catalystcenter_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"`
catalystcenter_password string	The password for authentication at the Cisco Catalyst Center.
catalystcenter_port string	Specifies the port number associated with the Cisco Catalyst Center. Default: :ansible-option-default:`"443"`
catalystcenter_task_poll_interval integer	Specifies the interval in seconds between successive calls to the API to retrieve task details. Default: :ansible-option-default:`2`
catalystcenter_username string	The username for authentication at the Cisco Catalyst Center. Default: :ansible-option-default:`"admin"`
catalystcenter_verify boolean	Flag to enable or disable SSL certificate verification. Choices: :ansible-option-choices-entry:`false` :ansible-option-choices-entry-default:`true` ← (default)
catalystcenter_version string	Specifies the version of the Cisco Catalyst Center that the SDK should use. Default: :ansible-option-default:`"2.3.7.6"`
config list / elements=dictionary / required	List of details of device being managed.
cabling_scheme string	Describes the physical cabling topology of the Catalyst stack. Catalyst Center uses this together with 'top_of_stack_serial_number' to validate that the requested stack renumbering is valid for the physical topology. The accepted values are "1A" and "1B". Applicable only when 'pnp_type' is 'StackSwitch'. Choices: :ansible-option-choices-entry:`"1A"` :ansible-option-choices-entry:`"1B"`
device_info list / elements=dictionary / required	Provides the device-specific information required for adding devices to the PnP database that are not already present. 2. For adding a single device, the list should contain exactly one set of device information. If a site name is also provided, the device can be claimed immediately after being added. 3. For bulk import, the list must contain information for more than one device. Bulk import is intended solely for adding devices; claiming must be performed with separate tasks or configurations.
authorize boolean	Set the authorization flag for PnP devices to enable provisioning after claiming. When set to true, devices in "Pending Authorization" state will be automatically authorized. This flag moves devices from "Pending Authorization" to "Authorized" state, allowing them to proceed with the provisioning workflow. Authorization is performed after successful device import (bulk operations) or device addition (single device operations). If not specified, devices will remain in their current authorization state and may require manual authorization. This parameter only applies to devices that support the authorization workflow in their PnP process. Authorization is skipped for devices that are not in "Pending Authorization" state. Supported from Cisco Catalyst Center release version 2.3.7.9 onwards. Choices: :ansible-option-choices-entry-default:`false` ← (default) :ansible-option-choices-entry:`true`
hostname string	Defines the desired hostname for the PnP device after it has been claimed. The hostname can only be assigned or changed during the claim process, not during bulk or single device additions.
is_stack_device boolean	Set to true if the device is a stack device. Only applies when `pnp_type` is `Default` or `StackSwitch`; ignored for `AccessPoint` and `CatalystWLC`. When `pnp_type` is `Default` or `StackSwitch` and this field is omitted, the module sends `stack=false` to Catalyst Center. Sent to Catalyst Center as `stack`. Choices: :ansible-option-choices-entry-default:`false` ← (default) :ansible-option-choices-entry:`true`
is_sudi_required boolean	SUDI authentication requirement flag. Sent to Catalyst Center as `sudiRequired`. Choices: :ansible-option-choices-entry:`false` :ansible-option-choices-entry:`true`
pid string / required	Pnp Device's pid.
serial_number string / required	Pnp Device's serial_number.
state string	Represents the onboarding state of the PnP device. Possible values are 'Unclaimed', 'Claimed', or 'Provisioned'.
user_sudi_serial_nos list / elements=string	List of Secure Unique Device Identifier (SUDI) serial numbers to perform SUDI authorization. Required if `is_sudi_required` is true. For stack devices, include all stack member SUDI serial numbers. Sent to Catalyst Center as `userSudiSerialNos`.
gateway string	Gateway IP address of the Wireless Controller for connectivity.
golden_image boolean	Specifies whether the configured image is tagged as a golden image. Choices: :ansible-option-choices-entry:`false` :ansible-option-choices-entry:`true`
image_name string	Name of the image to be configured on the device.
ip_interface_name string	Specifies the interface name utilized for Plug and Play (PnP) by the Wireless Controller. Ensure this interface is pre-configured on the controller before device claiming.
license_level string	License level applied when claiming a Catalyst switch / stack switch. Refer to your Catalyst Center version's API schema (Platform > Developer Toolkit) for the authoritative list of accepted values. Optional. Most commonly used together with 'pnp_type' set to 'Default' (switches/routers) or 'StackSwitch'.
pnp_type string	Specifies the device type for the Plug and Play (PnP) device. Options include 'Default', 'CatalystWLC', 'AccessPoint', or 'StackSwitch'. 'Default' is applicable to switches and routers. 'CatalystWLC' should be selected for 9800 series wireless controllers. 'AccessPoint' is used when claiming an access point. 'StackSwitch' should be chosen for a group of switches that operate as a single switch, typically used in the access layer. Choices: :ansible-option-choices-entry-default:`"Default"` ← (default) :ansible-option-choices-entry:`"CatalystWLC"` :ansible-option-choices-entry:`"AccessPoint"` :ansible-option-choices-entry:`"StackSwitch"`
project_name string	Name of the project under which the template is present. Default: :ansible-option-default:`"Onboarding Configuration"`
rf_profile string	Radio Frequecy (RF) profile of the AP being claimed. RF Profiles allow you to tune groups of APs that share a common coverage zone together. They selectively change how Radio Resource Management will operate the APs within that coverage zone. HIGH RF profile allows you to use more power and allows to join AP with the client in an easier fashion. TYPICAL RF profile is a blend of moderate power and moderate visibility to the client. LOW RF profile allows you to consume lesser power and has least visibility to the client. Choices: :ansible-option-choices-entry:`"HIGH"` :ansible-option-choices-entry:`"LOW"` :ansible-option-choices-entry:`"TYPICAL"`
site_name string / required	Name of the site to which the device will be claimed. This field is optional when only adding devices without claiming them to a site.
static_ip string	Management IP address of the Wireless Controller.
subnet_mask string	Subnet mask of the management IP address of the Wireless Controller.
template_name string	Name of the template to be configured on the device. Supported for EWLC from Cisco Catalyst Center release version 2.3.7.x onwards.
template_params dictionary	Parameter values for the parameterised templates. Each varibale has a value that needs to be passed as key-value pair in the dictionary. We can pass values as variable_name:variable_value. Supported for EWLC from Cisco Catalyst Center release version 2.3.7.x onwards.
top_of_stack_serial_number string	Serial number of the switch that should be designated as the top-of-stack (Member 1 / Active) when claiming a Catalyst stack via PnP. During Day-0 provisioning Catalyst Center uses this value to renumber the physical stack members so that the switch with this serial number becomes stack Member 1. This is what is commonly referred to as "stack renumbering" in the PnP flow. The value must match one of the 'serial_number' entries supplied under 'device_info'. Applicable only when 'pnp_type' is 'StackSwitch'.
vlan_id string	VLAN ID allocated for claiming the Wireless Controller.
config_verify boolean	Set to True to verify the Cisco Catalyst Center config after applying the playbook config. Choices: :ansible-option-choices-entry-default:`false` ← (default) :ansible-option-choices-entry:`true`
state string	The state of Cisco Catalyst Center after module completion. Choices: :ansible-option-choices-entry-default:`"merged"` ← (default) :ansible-option-choices-entry:`"deleted"`
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 are device_onboarding_pnp.DeviceOnboardingPnp.add_device, device_onboarding_pnp.DeviceOnboardingPnp.get_device_list, device_onboarding_pnp.DeviceOnboardingPnp.claim_a_device_to_a_site, device_onboarding_pnp.DeviceOnboardingPnp.delete_device_by_id_from_pnp, device_onboarding_pnp.DeviceOnboardingPnp.get_device_count, device_onboarding_pnp.DeviceOnboardingPnp.get_device_by_id, device_onboarding_pnp.DeviceOnboardingPnp.update_device, sites.Sites.get_site, software_image_management_swim.SoftwareImageManagementSwim.get_software_image_details, configuration_templates.ConfigurationTemplates.gets_the_templates_available
Paths used are post /dna/intent/api/v1/onboarding/pnp-device post /dna/intent/api/v1/onboarding/pnp-device/site-claim post /dna/intent/api/v1/onboarding/pnp-device/{id} get /dna/intent/api/v1/onboarding/pnp-device/count get /dna/intent/api/v1/onboarding/pnp-device put /onboarding/pnp-device/${id} get /dna/intent/api/v1/site get /dna/intent/api/v1/image/importation get /dna/intent/api/v1/template-programmer/template post /api/v1/onboarding/pnp-device/authorize
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

Examples 

---
- name: Import multiple switches in bulk only
  cisco.catalystcenter.pnp_workflow_manager:
    catalystcenter_host: "{{catalystcenter_host}}"
    catalystcenter_username: "{{catalystcenter_username}}"
    catalystcenter_password: "{{catalystcenter_password}}"
    catalystcenter_verify: "{{catalystcenter_verify}}"
    catalystcenter_port: "{{catalystcenter_port}}"
    catalystcenter_version: "{{catalystcenter_version}}"
    catalystcenter_debug: "{{catalystcenter_debug}}"
    catalystcenter_log_level: "{{catalystcenter_log_level}}"
    catalystcenter_log: true
    state: merged
    config_verify: true
    config:
      - device_info:
          - serial_number: QD2425L8M7
            state: Unclaimed
            pid: c9300-24P
            is_sudi_required: false
          - serial_number: QTC2320E0H9
            state: Unclaimed
            pid: c9300-24P
            hostname: Test-123
          - serial_number: ETC2320E0HB
            state: Unclaimed
            pid: c9300-24P
- name: Add a new EWLC and claim it
  cisco.catalystcenter.pnp_workflow_manager:
    catalystcenter_host: "{{catalystcenter_host}}"
    catalystcenter_username: "{{catalystcenter_username}}"
    catalystcenter_password: "{{catalystcenter_password}}"
    catalystcenter_verify: "{{catalystcenter_verify}}"
    catalystcenter_port: "{{catalystcenter_port}}"
    catalystcenter_version: "{{catalystcenter_version}}"
    catalystcenter_debug: "{{catalystcenter_debug}}"
    catalystcenter_log_level: "{{catalystcenter_log_level}}"
    catalystcenter_log: true
    state: merged
    config_verify: true
    config:
      - device_info:
          - serial_number: FOX2639PAY7
            hostname: New_WLC
            state: Unclaimed
            pid: C9800-CL-K9
            authorize: true
        site_name: Global/USA/San Francisco/BGL_18
        template_name: Ansible_PNP_WLC
        template_params:
          hostname: IAC-EWLC-Claimed
        project_name: Onboarding Configuration
        image_name: C9800-40-universalk9_wlc.17.12.01.SPA.bin
        golden_image: true
        pnp_type: CatalystWLC
        static_ip: 204.192.101.10
        subnet_mask: 255.255.255.0
        gateway: 204.192.101.1
        vlan_id: 1101
        ip_interface_name: TenGigabitEthernet0/0/0
- name: Claim a pre-added switch, apply a template,
    and perform an image upgrade for a specific site
  cisco.catalystcenter.pnp_workflow_manager:
    catalystcenter_host: "{{catalystcenter_host}}"
    catalystcenter_username: "{{catalystcenter_username}}"
    catalystcenter_password: "{{catalystcenter_password}}"
    catalystcenter_verify: "{{catalystcenter_verify}}"
    catalystcenter_port: "{{catalystcenter_port}}"
    catalystcenter_version: "{{catalystcenter_version}}"
    catalystcenter_debug: "{{catalystcenter_debug}}"
    catalystcenter_log_level: "{{catalystcenter_log_level}}"
    catalystcenter_log: true
    state: merged
    config_verify: true
    config:
      - device_info:
          - serial_number: FJC271924EQ
            hostname: Switch
            state: Unclaimed
            pid: C9300-48UXM
            is_sudi_required: true
            user_sudi_serial_nos:
              - FJC271924EQ
            is_stack_device: true
        site_name: Global/USA/San Francisco/BGL_18
        template_name: "Ansible_PNP_Switch"
        image_name: cat9k_iosxe_npe.17.03.07.SPA.bin
        project_name: Onboarding Configuration
        license_level: network-advantage
        top_of_stack_serial_number: FJC271924EQ
        cabling_scheme: 1B
        template_params:
          hostname: SJC-Switch-1
          interface: TwoGigabitEthernet1/0/2
- name: Remove multiple devices from the PnP dashboard
    safely (ignores non-existent devices)
  cisco.catalystcenter.pnp_workflow_manager:
    catalystcenter_host: "{{catalystcenter_host}}"
    catalystcenter_username: "{{catalystcenter_username}}"
    catalystcenter_password: "{{catalystcenter_password}}"
    catalystcenter_verify: "{{catalystcenter_verify}}"
    catalystcenter_port: "{{catalystcenter_port}}"
    catalystcenter_version: "{{catalystcenter_version}}"
    catalystcenter_debug: "{{catalystcenter_debug}}"
    catalystcenter_log_level: "{{catalystcenter_log_level}}"
    catalystcenter_log: true
    state: deleted
    config_verify: true
    config:
      - device_info:
          - serial_number: QD2425L8M7
          - serial_number: FTC2320E0HA
          - serial_number: FKC2310E0HB

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 Python SDK Returned: always Sample: :ansible-rv-sample-value:`"{\\n \\"response\\":\\n {\\n \\"response\\": String,\\n \\"version\\": String\\n },\\n \\"msg\\": String\\n}\\n"`
response_2 list / elements=string	A list with the response returned by the Cisco Catalyst Center Python SDK Returned: always Sample: :ansible-rv-sample-value:`["{\\n \\"response\\": []", "\\n \\"msg\\": String\\n}\\n"]`
response_3 dictionary	A string with the response returned by the Cisco Catalyst Center Python SDK Returned: always Sample: :ansible-rv-sample-value:`"{\\n \\"response\\": String,\\n \\"msg\\": String\\n}\\n"`

Authors

Abinash Mishra (@abimishr)
Madhan Sankaranarayanan (@madhansansel)
Rishita Chowdhary (@rishitachowdhary)
A Mohamed Rafeek (@mabdulk2)

Collection links

Issue Tracker Repository (Sources)

cisco.catalystcenter.pnp_workflow_manager module -- Resource module for Site and PnP related functions

Synopsis

Requirements

Parameters

Notes

Examples

Return Values