cisco.dnac.user_role_playbook_config_generator module -- Generate YAML playbook for user and role management.

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

New in cisco.dnac 6.44.0

Synopsis

• Generates YAML configurations compatible with the user_role_workflow_manager module from existing Catalyst Center user and role configurations.

• Automates brownfield discovery by extracting current user accounts and custom role definitions into playbook format.

• Reduces manual effort in creating Ansible playbooks for user and role management operations.

• Supports selective extraction using filters for usernames, emails, and role names.

• Generated YAML can be directly used with user_role_workflow_manager for configuration management and disaster recovery scenarios.

Requirements

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

• dnacentersdk >= 2.7.2

• python >= 3.9

Parameters

Parameter	Comments
config dictionary	A dictionary of filters for generating YAML playbook compatible with the user_role_workflow_manager module. If config is omitted, module internally sets generate_all_configurations=true and retrieves all supported components. If config is provided, component_specific_filters is mandatory. Under config, only component_specific_filters is allowed.
component_specific_filters dictionary	Filters to specify which components to include in the YAML configuration file and criteria for filtering data. Mandatory when config is provided. If components_list is specified, only those components are included in the output file. If component filter blocks (for example user_details or role_details) are provided, corresponding components are auto-added into components_list. If no component filter blocks are provided, components_list must be provided and non-empty. Each component can have specific filters to select subset of configurations based on attributes.
components_list list / elements=string	List of component names to include in the YAML output. Supported components are user_details and role_details. If component filter blocks are not specified, this option is mandatory and must be non-empty. If component filter blocks are specified, missing components are auto-added. Order in the list does not affect output structure. Invalid component names will cause module to fail with error message listing allowed components. Choices: :ansible-option-choices-entry:`"user\_details"` :ansible-option-choices-entry:`"role\_details"`
role_details list / elements=dictionary	List of filter parameter dictionaries to select specific roles for inclusion in YAML output. Multiple filter parameter sets use OR logic (any match includes the role). If not specified, all custom roles are included (system roles are always excluded). System roles (SUPER-ADMIN, NETWORK-ADMIN, OBSERVER) and roles with type 'default' or 'system' are automatically excluded.
role_name list / elements=string	List of role names to filter roles by exact name match. Matching is case-sensitive for role names. Only custom roles matching these names will be included in output. System and default roles are excluded regardless of filter. Example ['Custom-Admin-Role', 'Network-Operator-Role'] includes only these custom roles.
user_details list / elements=dictionary	List of filter parameter dictionaries to select specific users for inclusion in YAML output. Multiple filter parameter sets use OR logic (any match includes the user). Within a single filter parameter set, all criteria must match (AND logic). If not specified, all users are included (subject to components_list setting). All filter values are case-insensitive.
email list / elements=string	List of email addresses to filter users by exact email match. Matching is case-insensitive. Users with email addresses in this list will be included in output. Example ['user1@example.com', 'user2@example.com'] filters by email.
role_name list / elements=string	List of role names to filter users by assigned role. Matching is case-insensitive. Users having any of the specified roles will be included in output. Role names should match exactly as defined in Catalyst Center. Example ['SUPER-ADMIN-ROLE', 'Custom-Admin-Role'] includes users with these roles.
username list / elements=string	List of usernames to filter users by exact username match. Matching is case-insensitive. Users with usernames in this list will be included in output. Example ['testuser1', 'testuser2'] includes only these two users.
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"`
file_mode string	File write mode for the generated YAML configuration file. The overwrite option replaces existing file content with new content. The append option adds new content to the end of existing file. Relevant only when file_path is provided. Defaults to overwrite if not specified. Choices: :ansible-option-choices-entry-default:`"overwrite"` ← (default) :ansible-option-choices-entry:`"append"`
file_path string	Absolute or relative path where the YAML configuration file will be saved. If not provided, the file is saved in the current working directory with auto-generated filename. Default filename pattern is user_role_playbook_config_<YYYY-MM-DD_HH-MM-SS>.yml.
state string	The desired state for the module operation. Only gathered state is supported for extracting existing configurations from Catalyst Center. The gathered state retrieves user and role data via API and transforms it into YAML playbook format. 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

• Minimum supported Catalyst Center version is 2.3.5.3 which introduced user and role retrieval APIs.

• System roles (SUPER-ADMIN, NETWORK-ADMIN, OBSERVER) are automatically excluded from role_details output.

• Roles with type 'default' or 'system' are automatically excluded from output.

• Generated YAML file structure matches the input format expected by user_role_workflow_manager module.

• Role permissions are transformed from API resourceTypes format to hierarchical permission structure with 9 categories.

• User role assignments are transformed from role IDs to role names for readability.

• All filter values are expected as lists of strings, even for single values.

• Check mode is supported but does not generate files (dry-run).

• SDK Methods used are - user_and_roles.UserandRoles.get_users_api - user_and_roles.UserandRoles.get_roles_api

• Paths used are - GET /dna/system/api/v1/user - GET /dna/system/api/v1/role

• 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.user_role_workflow_manager

Module to manage users and roles using generated YAML.

Examples

- name: Generate YAML Configuration with File Path specified
  cisco.dnac.user_role_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
    file_path: "/tmp/catc_user_role_config.yaml"

- name: Generate YAML Configuration with specific user components only
  cisco.dnac.user_role_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
    file_path: "/tmp/catc_user_role_config.yaml"
    file_mode: "overwrite"
    config:
      component_specific_filters:
        components_list: ["user_details"]

- name: Generate YAML Configuration with specific role components only
  cisco.dnac.user_role_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
    file_path: "/tmp/catc_user_role_config.yaml"
    config:
      component_specific_filters:
        components_list: ["role_details"]

- name: Generate YAML Configuration for users with username filter
  cisco.dnac.user_role_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
    file_path: "/tmp/catc_user_role_config.yaml"
    config:
      component_specific_filters:
        components_list: ["user_details"]
        user_details:
          - username: ["testuser1", "testuser2"]

- name: Generate YAML Configuration for roles with role name filter
  cisco.dnac.user_role_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
    file_path: "/tmp/catc_user_role_config.yaml"
    config:
      component_specific_filters:
        components_list: ["role_details"]
        role_details:
          - role_name: ["Custom-Admin-Role", "Network-Operator-Role"]

- name: Generate YAML Configuration for all components with no filters
  cisco.dnac.user_role_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
    file_path: "/tmp/catc_user_role_config.yaml"
    config:
      component_specific_filters:
        components_list: ["user_details", "role_details"]

- name: Generate YAML for users with specific email addresses
  cisco.dnac.user_role_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
    file_path: "/tmp/catc_users_by_email.yaml"
    config:
      component_specific_filters:
        components_list: ["user_details"]
        user_details:
          - email: ["admin@example.com", "operator@example.com"]

- name: Append YAML for users with specific role assignments to existing file
  cisco.dnac.user_role_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
    file_path: "/tmp/catc_admin_users.yaml"
    file_mode: "append"
    config:
      component_specific_filters:
        components_list: ["user_details"]
        user_details:
          - role_name: ["SUPER-ADMIN-ROLE", "Custom-Admin-Role"]

- name: Generate YAML with multiple filter criteria (OR logic)
  cisco.dnac.user_role_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
    file_path: "/tmp/catc_filtered_users.yaml"
    config:
      component_specific_filters:
        components_list: ["user_details"]
        user_details:
          - username: ["testuser1"]
          - email: ["admin@example.com"]

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 'user\_role\_workflow\_manager'", "response": {"components\_processed": 2, "components\_skipped": 0, "configurations\_count": 15, "file\_path": "user\_role\_details/user\_info", "message": "YAML configuration file generated successfully for module 'user\_role\_workflow\_manager'", "status": "success"}, "status": "success"}`
response_2 list / elements=string	A dictionary with the response returned by the Cisco Catalyst Center Returned: always Sample: :ansible-rv-sample-value:`["\\"msg\\": {\\n \\"YAML config generation Task failed for module 'user\_role\_workflow\_manager'.\\": {\\n \\"file\_path\\": \\"/Users/priyadharshini/Downloads/specific\_userrole\_details\_info\\"\\n }\\n}", " \\"response\\": {\\n \\"YAML config generation Task failed for module 'user\_role\_workflow\_manager'.\\": {\\n \\"file\_path\\": \\"/Users/priyadharshini/Downloads/specific\_userrole\_details\_info\\"\\n }\\n}\\n"]`

Authors

• Priyadharshini B (@pbalaku2)

• Madhan Sankaranarayanan (@madhansansel)

Collection links

Issue Tracker Repository (Sources)