#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright (c) 2021, Cisco Systems
# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)

DOCUMENTATION = r"""
module: networks_devices_claim
short_description: Resource module for networks _devices _claim
description:
  - Manage operation create of the resource networks _devices _claim.
  - >
    Claim devices into a network. Note for recently claimed devices, it may take a
    few minutes for API requests against that device to succeed. This operation can
    be used up to ten times within a single five minute window.
version_added: '1.0.0'
extends_documentation_fragment:
  - cisco.meraki.module
author: Francisco Munoz (@fmunoz)
options:
  detailsByDevice:
    description: Optional details for claimed devices (currently only used for Catalyst
      devices).
    elements: dict
    suboptions:
      details:
        description: An array of details. Supported list of details includes "device
          mode", "username", "password", "enable password", "ap mapping type" and
          "ap network id". For onboarding into hybrid mode, the value of the device
          mode detail must be "monitored".
        elements: dict
        suboptions:
          name:
            description: Name of device detail.
            type: str
          value:
            description: Value of device detail.
            type: str
        type: list
      serial:
        description: The serial of the device these details relate to.
        type: str
    type: list
  networkId:
    description: NetworkId path parameter. Network ID.
    type: str
  serials:
    description: A list of serials of devices to claim.
    elements: str
    type: list
requirements:
  - meraki >= 2.4.9
  - python >= 3.5
seealso:
  - name: Cisco Meraki documentation for networks claimNetworkDevices
    description: Complete reference of the claimNetworkDevices API.
    link: https://developer.cisco.com/meraki/api-v1/#!claim-network-devices
notes:
  - SDK Method used are
    networks.Networks.claim_network_devices,
  - Paths used are
    post /networks/{networkId}/devices/claim,
"""

EXAMPLES = r"""
- name: Create
  cisco.meraki.networks_devices_claim:
    meraki_api_key: "{{ meraki_api_key }}"
    meraki_base_url: "{{ meraki_base_url }}"
    meraki_single_request_timeout: "{{ meraki_single_request_timeout }}"
    meraki_certificate_path: "{{ meraki_certificate_path }}"
    meraki_requests_proxy: "{{ meraki_requests_proxy }}"
    meraki_wait_on_rate_limit: "{{ meraki_wait_on_rate_limit }}"
    meraki_nginx_429_retry_wait_time: "{{ meraki_nginx_429_retry_wait_time }}"
    meraki_action_batch_retry_wait_time: "{{ meraki_action_batch_retry_wait_time }}"
    meraki_retry_4xx_error: "{{ meraki_retry_4xx_error }}"
    meraki_retry_4xx_error_wait_time: "{{ meraki_retry_4xx_error_wait_time }}"
    meraki_maximum_retries: "{{ meraki_maximum_retries }}"
    meraki_output_log: "{{ meraki_output_log }}"
    meraki_log_file_prefix: "{{ meraki_log_file_prefix }}"
    meraki_log_path: "{{ meraki_log_path }}"
    meraki_print_console: "{{ meraki_print_console }}"
    meraki_suppress_logging: "{{ meraki_suppress_logging }}"
    meraki_simulate: "{{ meraki_simulate }}"
    meraki_be_geo_id: "{{ meraki_be_geo_id }}"
    meraki_caller: "{{ meraki_caller }}"
    meraki_use_iterator_for_get_pages: "{{ meraki_use_iterator_for_get_pages }}"
    meraki_inherit_logging_config: "{{ meraki_inherit_logging_config }}"
    addAtomically: true
    detailsByDevice:
      - details:
          - name: username
            value: milesmeraki
        serial: Q234-ABCD-5678
    networkId: string
    serials:
      - Q234-ABCD-0001
      - Q234-ABCD-0002
      - Q234-ABCD-0003
"""
RETURN = r"""
meraki_response:
  description: A dictionary or list with the response returned by the Cisco Meraki Python SDK
  returned: always
  type: dict
  sample: >
    {
      "serials": [
        "string"
      ],
      "errors": [
        {
          "serial": "string",
          "errors": [
            "string"
          ]
        }
      ]
    }
"""
