From ab26dc8fa1dbf5753e97843eb15f773ad9bcf117 Mon Sep 17 00:00:00 2001 From: "networkers.pl" <65722963+networkers-pl@users.noreply.github.com> Date: Tue, 9 Jun 2020 08:38:06 +0200 Subject: [PATCH] cisco_spark -> cisco_webex rename and message option fix (#457) * This is a modified copy of the cisco_spark.py file. The name change is associated with the change of the product name from Cisco Spark to Cisco Webex Teams. In addition, the current version (cisco_spark) does not work due to a name collision with MESSAGE. I had to modify the name from "message" to "webexmsg" in many places in cisco_webex. It works fine in this version. The original author has been preserved and copied from cisco_spark to cisco_webex. @drew-russell The current version of cisco_spark module does not work due to a name collision with MESSAGE. I had to modify the name from "message" to "webexmsg" in many places in cisco_webex.py file. It works fine in this version. The name change is associated with the change of the product name from Cisco Spark to Cisco Webex Teams. * cisco_spark rm * suggested change * aliases added to in def main funcitons * sanity check corrections * addess aliases type to msg_type * felixfontein requested changes on this pull request. * Return value change from msg to message. * plugins/modules/notification/cisco_webex.py validate-modules:invalid-argument-name added to tests/sanity/ignore-2.10.txt --- plugins/modules/cisco_spark.py | 2 +- plugins/modules/cisco_webex.py | 1 + plugins/modules/notification/cisco_spark.py | 187 +------------------ plugins/modules/notification/cisco_webex.py | 189 ++++++++++++++++++++ tests/sanity/ignore-2.10.txt | 6 +- 5 files changed, 193 insertions(+), 192 deletions(-) create mode 120000 plugins/modules/cisco_webex.py mode change 100644 => 120000 plugins/modules/notification/cisco_spark.py create mode 100644 plugins/modules/notification/cisco_webex.py diff --git a/plugins/modules/cisco_spark.py b/plugins/modules/cisco_spark.py index 24681a0651..6310af28cf 120000 --- a/plugins/modules/cisco_spark.py +++ b/plugins/modules/cisco_spark.py @@ -1 +1 @@ -./notification/cisco_spark.py \ No newline at end of file +notification/cisco_spark.py \ No newline at end of file diff --git a/plugins/modules/cisco_webex.py b/plugins/modules/cisco_webex.py new file mode 120000 index 0000000000..af172516ff --- /dev/null +++ b/plugins/modules/cisco_webex.py @@ -0,0 +1 @@ +notification/cisco_webex.py \ No newline at end of file diff --git a/plugins/modules/notification/cisco_spark.py b/plugins/modules/notification/cisco_spark.py deleted file mode 100644 index 1975da3a7a..0000000000 --- a/plugins/modules/notification/cisco_spark.py +++ /dev/null @@ -1,186 +0,0 @@ -#!/usr/bin/python -# -*- coding: utf-8 -*- - -# Copyright: Ansible Project -# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) - -from __future__ import absolute_import, division, print_function -__metaclass__ = type - - -DOCUMENTATION = ''' ---- -module: cisco_spark -short_description: Send a message to a Cisco Spark Room or Individual. -description: - - Send a message to a Cisco Spark Room or Individual with options to control the formatting. -author: Drew Rusell (@drew-russell) -notes: - - The C(recipient_id) type must be valid for the supplied C(recipient_id). - - Full API documentation can be found at U(https://developer.ciscospark.com/endpoint-messages-post.html). - -options: - - recipient_type: - description: - - The request parameter you would like to send the message to. - - Messages can be sent to either a room or individual (by ID or E-Mail). - required: True - choices: ['roomId', 'toPersonEmail', 'toPersonId'] - - recipient_id: - description: - - The unique identifier associated with the supplied C(recipient_type). - required: true - - message_type: - description: - - Specifies how you would like the message formatted. - required: False - default: text - choices: ['text', 'markdown'] - - personal_token: - description: - - Your personal access token required to validate the Spark API. - required: true - aliases: ['token'] - - message: - description: - - The message you would like to send. - required: True -''' - -EXAMPLES = """ -# Note: The following examples assume a variable file has been imported -# that contains the appropriate information. - -- name: Cisco Spark - Markdown Message to a Room - cisco_spark: - recipient_type: roomId - recipient_id: "{{ room_id }}" - message_type: markdown - personal_token: "{{ token }}" - message: "**Cisco Spark Ansible Module - Room Message in Markdown**" - -- name: Cisco Spark - Text Message to a Room - cisco_spark: - recipient_type: roomId - recipient_id: "{{ room_id }}" - message_type: text - personal_token: "{{ token }}" - message: "Cisco Spark Ansible Module - Room Message in Text" - -- name: Cisco Spark - Text Message by an Individuals ID - cisco_spark: - recipient_type: toPersonId - recipient_id: "{{ person_id}}" - message_type: text - personal_token: "{{ token }}" - message: "Cisco Spark Ansible Module - Text Message to Individual by ID" - -- name: Cisco Spark - Text Message by an Individuals E-Mail Address - cisco_spark: - recipient_type: toPersonEmail - recipient_id: "{{ person_email }}" - message_type: text - personal_token: "{{ token }}" - message: "Cisco Spark Ansible Module - Text Message to Individual by E-Mail" - -""" - -RETURN = """ -status_code: - description: - - The Response Code returned by the Spark API. - - Full Response Code explanations can be found at U(https://developer.ciscospark.com/endpoint-messages-post.html). - returned: always - type: int - sample: 200 - -message: - description: - - The Response Message returned by the Spark API. - - Full Response Code explanations can be found at U(https://developer.ciscospark.com/endpoint-messages-post.html). - returned: always - type: str - sample: OK (585 bytes) -""" -from ansible.module_utils.basic import AnsibleModule -from ansible.module_utils.urls import fetch_url - - -def spark_message(module): - """ When check mode is specified, establish a read only connection, that does not return any user specific - data, to validate connectivity. In regular mode, send a message to a Cisco Spark Room or Individual""" - - # Ansible Specific Variables - results = {} - ansible = module.params - - headers = { - 'Authorization': 'Bearer {0}'.format(ansible['personal_token']), - 'content-type': 'application/json' - } - - if module.check_mode: - url = "https://api.ciscospark.com/v1/people/me" - payload = None - - else: - url = "https://api.ciscospark.com/v1/messages" - - payload = { - ansible['recipient_type']: ansible['recipient_id'], - ansible['message_type']: ansible['message'] - } - - payload = module.jsonify(payload) - - response, info = fetch_url(module, url, data=payload, headers=headers) - - status_code = info['status'] - message = info['msg'] - - # Module will fail if the response is not 200 - if status_code != 200: - results['failed'] = True - results['status_code'] = status_code - results['message'] = message - else: - results['failed'] = False - results['status_code'] = status_code - - if module.check_mode: - results['message'] = 'Authentication Successful.' - else: - results['message'] = message - - return results - - -def main(): - '''Ansible main. ''' - module = AnsibleModule( - argument_spec=dict( - recipient_type=dict(required=True, choices=[ - 'roomId', 'toPersonEmail', 'toPersonId']), - recipient_id=dict(required=True, no_log=True), - message_type=dict(required=False, default=['text'], aliases=[ - 'type'], choices=['text', 'markdown']), - personal_token=dict(required=True, no_log=True, aliases=['token']), - message=dict(required=True) - - ), - - supports_check_mode=True - ) - - results = spark_message(module) - - module.exit_json(**results) - - -if __name__ == "__main__": - main() diff --git a/plugins/modules/notification/cisco_spark.py b/plugins/modules/notification/cisco_spark.py new file mode 120000 index 0000000000..6fe1011ffd --- /dev/null +++ b/plugins/modules/notification/cisco_spark.py @@ -0,0 +1 @@ +cisco_webex.py \ No newline at end of file diff --git a/plugins/modules/notification/cisco_webex.py b/plugins/modules/notification/cisco_webex.py new file mode 100644 index 0000000000..c8f3730e6c --- /dev/null +++ b/plugins/modules/notification/cisco_webex.py @@ -0,0 +1,189 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# Copyright: Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +DOCUMENTATION = ''' +--- +module: cisco_webex +short_description: Send a message to a Cisco Webex Teams Room or Individual +description: + - Send a message to a Cisco Webex Teams Room or Individual with options to control the formatting. +author: Drew Rusell (@drew-russell) +notes: + - The C(recipient_id) type must be valid for the supplied C(recipient_id). + - Full API documentation can be found at U(https://developer.webex.com/docs/api/basics). + +options: + + recipient_type: + description: + - The request parameter you would like to send the message to. + - Messages can be sent to either a room or individual (by ID or E-Mail). + required: yes + choices: ['roomId', 'toPersonEmail', 'toPersonId'] + type: str + + recipient_id: + description: + - The unique identifier associated with the supplied C(recipient_type). + required: yes + type: str + + msg_type: + description: + - Specifies how you would like the message formatted. + default: text + choices: ['text', 'markdown'] + type: str + aliases: ['message_type'] + + personal_token: + description: + - Your personal access token required to validate the Webex Teams API. + required: yes + aliases: ['token'] + type: str + + msg: + description: + - The message you would like to send. + required: yes + type: str + aliases: ['message'] +''' + +EXAMPLES = """ +# Note: The following examples assume a variable file has been imported +# that contains the appropriate information. + +- name: Cisco Webex Teams - Markdown Message to a Room + community.general.cisco_webex: + recipient_type: roomId + recipient_id: "{{ room_id }}" + msg_type: markdown + personal_token: "{{ token }}" + msg: "**Cisco Webex Teams Ansible Module - Room Message in Markdown**" + +- name: Cisco Webex Teams - Text Message to a Room + community.general.cisco_webex: + recipient_type: roomId + recipient_id: "{{ room_id }}" + msg_type: text + personal_token: "{{ token }}" + msg: "Cisco Webex Teams Ansible Module - Room Message in Text" + +- name: Cisco Webex Teams - Text Message by an Individuals ID + community.general.cisco_webex: + recipient_type: toPersonId + recipient_id: "{{ person_id}}" + msg_type: text + personal_token: "{{ token }}" + msg: "Cisco Webex Teams Ansible Module - Text Message to Individual by ID" + +- name: Cisco Webex Teams - Text Message by an Individuals E-Mail Address + community.general.cisco_webex: + recipient_type: toPersonEmail + recipient_id: "{{ person_email }}" + msg_type: text + personal_token: "{{ token }}" + msg: "Cisco Webex Teams Ansible Module - Text Message to Individual by E-Mail" + +""" + +RETURN = """ +status_code: + description: + - The Response Code returned by the Webex Teams API. + - Full Response Code explanations can be found at U(https://developer.webex.com/docs/api/basics). + returned: always + type: int + sample: 200 + +message: + description: + - The Response Message returned by the Webex Teams API. + - Full Response Code explanations can be found at U(https://developer.webex.com/docs/api/basics). + returned: always + type: str + sample: OK (585 bytes) +""" +from ansible.module_utils.basic import AnsibleModule +from ansible.module_utils.urls import fetch_url + + +def webex_msg(module): + """When check mode is specified, establish a read only connection, that does not return any user specific + data, to validate connectivity. In regular mode, send a message to a Cisco Webex Teams Room or Individual""" + + # Ansible Specific Variables + results = {} + ansible = module.params + + headers = { + 'Authorization': 'Bearer {0}'.format(ansible['personal_token']), + 'content-type': 'application/json' + } + + if module.check_mode: + url = "https://webexapis.com/v1/people/me" + payload = None + + else: + url = "https://webexapis.com/v1/messages" + + payload = { + ansible['recipient_type']: ansible['recipient_id'], + ansible['msg_type']: ansible['msg'] + } + + payload = module.jsonify(payload) + + response, info = fetch_url(module, url, data=payload, headers=headers) + + status_code = info['status'] + msg = info['msg'] + + # Module will fail if the response is not 200 + if status_code != 200: + results['failed'] = True + results['status_code'] = status_code + results['message'] = msg + else: + results['failed'] = False + results['status_code'] = status_code + + if module.check_mode: + results['message'] = 'Authentication Successful.' + else: + results['message'] = msg + + return results + + +def main(): + '''Ansible main. ''' + module = AnsibleModule( + argument_spec=dict( + recipient_type=dict(required=True, choices=['roomId', 'toPersonEmail', 'toPersonId']), + recipient_id=dict(required=True, no_log=True), + msg_type=dict(required=False, default='text', aliases=['message_type'], choices=['text', 'markdown']), + personal_token=dict(required=True, no_log=True, aliases=['token']), + msg=dict(required=True, aliases=['message']), + ), + + supports_check_mode=True + ) + + results = webex_msg(module) + + module.exit_json(**results) + + +if __name__ == "__main__": + main() diff --git a/tests/sanity/ignore-2.10.txt b/tests/sanity/ignore-2.10.txt index 54e94be3d7..9acce4a18c 100644 --- a/tests/sanity/ignore-2.10.txt +++ b/tests/sanity/ignore-2.10.txt @@ -1289,11 +1289,7 @@ plugins/modules/notification/campfire.py validate-modules:doc-missing-type plugins/modules/notification/catapult.py validate-modules:doc-missing-type plugins/modules/notification/catapult.py validate-modules:parameter-list-no-elements plugins/modules/notification/catapult.py validate-modules:parameter-type-not-in-doc -plugins/modules/notification/cisco_spark.py validate-modules:doc-default-does-not-match-spec -plugins/modules/notification/cisco_spark.py validate-modules:doc-missing-type -plugins/modules/notification/cisco_spark.py validate-modules:invalid-argument-name -plugins/modules/notification/cisco_spark.py validate-modules:nonexistent-parameter-documented -plugins/modules/notification/cisco_spark.py validate-modules:undocumented-parameter +plugins/modules/notification/cisco_webex.py validate-modules:invalid-argument-name plugins/modules/notification/flowdock.py validate-modules:doc-missing-type plugins/modules/notification/grove.py validate-modules:invalid-argument-name plugins/modules/notification/grove.py validate-modules:nonexistent-parameter-documented