cisco.dnac.site_intent module – Resource module for Site operations

Note

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

New in cisco.dnac 6.6.0

Synopsis

  • Manage operation create, update and delete of the resource Sites.

  • Creates site with area/building/floor with specified hierarchy.

  • Updates site with area/building/floor with specified hierarchy.

  • Deletes site with area/building/floor with specified hierarchy.

Requirements

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

  • dnacentersdk == 2.4.5

  • python >= 3.9

Parameters

Parameter

Comments

config

list / elements=dictionary / required

It represents a list of details for creating/managing/deleting sites, including areas, buildings, and floors.

site

dictionary

Contains details about the site being managed including areas, buildings and floors.

area

dictionary

Configuration details for creating or managing an area within a site.

name

string

Name of the area to be created or managed (e.g., “Area1”).

parent_name

string

The full name of the parent under which the area will be created/managed/deleted (e.g., “Global/USA”).

building

dictionary

Configuration details required for creating or managing a building within a site.

address

string

Physical address of the building that is to be created or managed.

latitude

float

Geographical latitude coordinate of the building. For example, use 37.338 for a location in San Jose, California. Valid values range from -90.0 to +90.0 degrees.

longitude

float

Geographical longitude coordinate of the building. For example, use -121.832 for a location in San Jose, California. Valid values range from -180.0 to +180.0 degrees.

name

string

Name of the building (e.g., “Building1”).

parent_name

string

Hierarchical parent path of the building, indicating its location within the site (e.g., “Global/USA/San Francisco”).

floor

dictionary

Configuration details required for creating or managing a floor within a site.

floor_number

integer

Floor number within the building site (e.g., 5). This value can only be specified during the creation of the floor and cannot be modified afterward.

height

float

Height of the floor in feet (e.g., 15.23).

length

float

Length of the floor in feet (e.g., 100.11).

name

string

Name of the floor (e.g., “Floor-1”).

parent_name

string

Hierarchical parent path of the floor, indicating its location within the site (e.g., “Global/USA/San Francisco/BGL_18”).

rf_model

string

The RF (Radio Frequency) model type for the floor, which is essential for simulating and optimizing wireless network coverage. Select from the following allowed values, which describe different environmental signal propagation characteristics. Type of floor (allowed values are ‘Cubes And Walled Offices’, ‘Drywall Office Only’, ‘Indoor High Ceiling’, ‘Outdoor Open Space’). Cubes And Walled Offices - This RF model typically represents indoor areas with cubicles or walled offices, where radio signals may experience attenuation due to walls and obstacles. Drywall Office Only - This RF model indicates an environment with drywall partitions, commonly found in office spaces, which may have moderate signal attenuation. Indoor High Ceiling - This RF model is suitable for indoor spaces with high ceilings, such as auditoriums or atriums, where signal propagation may differ due to the height of the ceiling. Outdoor Open Space - This RF model is used for outdoor areas with open spaces, where signal propagation is less obstructed and may follow different patterns compared to indoor environments.

width

float

Width of the floor in feet (e.g., 100.22).

site_type

string

Type of site to create/update/delete (eg area, building, floor).

config_verify

boolean

Set to True to verify the Cisco Catalyst Center config 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

Flag for Cisco DNA Center SDK to enable debugging.

Choices:

  • false ← (default)

  • true

dnac_host

string / required

The Cisco DNA Center hostname.

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 Cisco DNA Center password to authenticate.

dnac_port

string

The Cisco DNA Center port.

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 Cisco DNA Center username to authenticate.

Default: "admin"

dnac_verify

boolean

Flag to enable or disable SSL certificate verification.

Choices:

  • false

  • true ← (default)

dnac_version

string

Informs the SDK which version of Cisco DNA Center to use.

Default: "2.2.3.3"

state

string

The state of Catalyst Center after module completion.

Choices:

  • "merged" ← (default)

  • "deleted"

validate_response_schema

boolean

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

Choices:

  • false

  • true ← (default)

Notes

Note

  • SDK Method used are sites.Sites.create_site, sites.Sites.update_site, sites.Sites.delete_site

  • Paths used are post /dna/intent/api/v1/site, put dna/intent/api/v1/site/{siteId}, delete dna/intent/api/v1/site/{siteId}

  • Does not support check_mode

  • The plugin runs on the control node and does not use any ansible connection plugins, but instead the embedded connection manager from Cisco DNAC SDK

  • The parameters starting with dnac_ are used by the Cisco DNAC Python SDK to establish the connection

Examples

- name: Create a new area site
  cisco.dnac.site_intent:
    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_level: "{{dnac_log_level}}"
    dnac_log: "{{dnac_log}}"
    state: merged
    config:
    - site:
        area:
          name: Test
          parent_name: Global/India
      site_type: area

- name: Create a new building site
  cisco.dnac.site_intent:
    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_level: "{{dnac_log_level}}"
    dnac_log: "{{dnac_log}}"
    state: merged
    config:
    - site:
        building:
          name: Building_1
          parent_name: Global/India
          address: Bengaluru, Karnataka, India
          latitude: 24.12
          longitude: 23.45
      site_type: building

- name: Create a Floor site under the building
  cisco.dnac.site_intent:
    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_level: "{{dnac_log_level}}"
    dnac_log: "{{dnac_log}}"
    state: merged
    config:
    - site:
        floor:
          name: Floor_1
          parent_name: Global/India/Building_1
          length: 75.76
          width: 35.54
          height: 30.12
          rf_model: Cubes And Walled Offices
          floor_number: 2
      site_type: floor

- name: Updating the Floor details under the building
  cisco.dnac.site_intent:
    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_level: "{{dnac_log_level}}"
    dnac_log: "{{dnac_log}}"
    state: merged
    config:
    - site:
        floor:
          name: Floor_1
          parent_name: Global/India/Building_1
          length: 75.76
          width: 35.54
          height: 30.12
      site_type: floor

- name: Deleting any site you need site name and parent name
  cisco.dnac.site_intent:
    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_level: "{{dnac_log_level}}"
    dnac_log: "{{dnac_log}}"
    state: deleted
    config:
    - site:
        floor:
          name: Floor_1
          parent_name: Global/India/Building_1
      site_type: floor

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 API execution details as returned by the Cisco Catalyst Center Python SDK

Returned: always

Sample: "{\n  \"response\":\n    {\n         \"bapiExecutionId\": String,\n         \"bapiKey\": String,\n         \"bapiName\": String,\n         \"endTime\": String,\n         \"endTimeEpoch\": 0,\n         \"runtimeInstanceId\": String,\n         \"siteId\": String,\n         \"startTime\": String,\n         \"startTimeEpoch\": 0,\n         \"status\": String,\n         \"timeDuration\": 0\n\n    },\n  \"msg\": \"string\"\n}\n"

response_2

dictionary

A dictionary with existing site details.

Returned: always

Sample: "{\n  \"response\":\n  {\n        \"site\": {},\n        \"siteId\": String,\n        \"type\": String\n  },\n  \"msg\": String\n}\n"

response_3

dictionary

A dictionary with API execution details as returned by the Cisco Catalyst Center Python SDK

Returned: always

Sample: "{\n  \"response\":\n    {\n         \"bapiError\": String,\n         \"bapiExecutionId\": String,\n         \"bapiKey\": String,\n         \"bapiName\": String,\n         \"endTime\": String,\n         \"endTimeEpoch\": 0,\n         \"runtimeInstanceId\": String,\n         \"startTime\": String,\n         \"startTimeEpoch\": 0,\n         \"status\": String,\n         \"timeDuration\": 0\n\n    },\n  \"msg\": \"string\"\n}\n"

response_4

list / elements=string

A list with the response returned by the Cisco Catalyst Center Python

Returned: always

Sample: ["{\n   \"response\": []", "\n   \"msg\": String\n}\n"]

Authors

  • Madhan Sankaranarayanan (@madhansansel) Rishita Chowdhary (@rishitachowdhary) Abhishek Maheshwari (@abhishekmaheshwari)