Initial conversion of tower_notification

awx_collection/plugins/modules/tower_notification.py

@@ -26,168 +26,188 @@ options:
     name:
       description:
         - The name of the notification.
+      type: str
       required: True
+    new_name:
+      description:
+        - Setting this option will change the existing name (looked up via the name field.
       type: str
     description:
       description:
         - The description of the notification.
-      required: False
       type: str
     organization:
       description:
         - The organization the notification belongs to.
-      required: False
       type: str
     notification_type:
       description:
         - The type of notification to be sent.
       required: True
-      choices: ["email", "slack", "twilio", "pagerduty", "hipchat", "webhook", "irc"]
+      choices:
+        - 'email'
+        - 'grafana'
+        - 'hipchat'
+        - 'irc'
+        - 'mattermost'
+        - 'pagerduty'
+        - 'rocketchat'
+        - 'slack'
+        - 'twilio'
+        - 'webhook'
       type: str
     notification_configuration:
       description:
         - The notification configuration file. Note providing this field would disable all notification-configuration-related fields.
-      required: False
+      type: dict
-      type: str
+    messages:
+      description:
+        - Optional custom messages for notification template.
+      type: dict
+      default:
+        started:
+        success:
+        error:
+        workflow_approval:
     username:
       description:
         - The mail server username. Required if I(notification_type=email).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     sender:
       description:
         - The sender email address. Required if I(notification_type=email).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     recipients:
       description:
         - The recipients email addresses. Required if I(notification_type=email).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: list
       elements: str
     use_tls:
       description:
         - The TLS trigger. Required if I(notification_type=email).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: bool
     host:
       description:
         - The mail server host. Required if I(notification_type=email).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     use_ssl:
       description:
         - The SSL trigger. Required if I(notification_type=email) or if I(notification_type=irc).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: bool
     password:
       description:
         - The mail server password. Required if I(notification_type=email) or if I(notification_type=irc).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     port:
       description:
         - The mail server port. Required if I(notification_type=email) or if I(notification_type=irc).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: int
     channels:
       description:
         - The destination Slack channels. Required if I(notification_type=slack).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: list
       elements: str
     token:
       description:
         - The access token. Required if I(notification_type=slack), if I(notification_type=pagerduty) or if I(notification_type=hipchat).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     account_token:
       description:
         - The Twillio account token. Required if I(notification_type=twillio).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     from_number:
       description:
         - The source phone number. Required if I(notification_type=twillio).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     to_numbers:
       description:
         - The destination phone numbers. Required if I(notification_type=twillio).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: list
       elements: str
     account_sid:
       description:
         - The Twillio account SID. Required if I(notification_type=twillio).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     subdomain:
       description:
         - The PagerDuty subdomain. Required if I(notification_type=pagerduty).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     service_key:
       description:
         - The PagerDuty service/integration API key. Required if I(notification_type=pagerduty).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     client_name:
       description:
         - The PagerDuty client identifier. Required if I(notification_type=pagerduty).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     message_from:
       description:
         - The label to be shown with the notification. Required if I(notification_type=hipchat).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     api_url:
       description:
         - The HipChat API URL. Required if I(notification_type=hipchat).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     color:
       description:
         - The notification color. Required if I(notification_type=hipchat).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       choices: ["yellow", "green", "red", "purple", "gray", "random"]
       type: str
     rooms:
       description:
         - HipChat rooms to send the notification to. Required if I(notification_type=hipchat).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: list
       elements: str
     notify:
       description:
         - The notify channel trigger. Required if I(notification_type=hipchat).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: bool
     url:
       description:
         - The target URL. Required if I(notification_type=webhook).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     headers:
       description:
         - The HTTP headers as JSON string. Required if I(notification_type=webhook).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: dict
     server:
       description:
         - The IRC server address. Required if I(notification_type=irc).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     nickname:
       description:
         - The IRC nickname. Required if I(notification_type=irc).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: str
     targets:
       description:
         - The destination channels or users. Required if I(notification_type=irc).
-      required: False
+        - This parameter has been deprecated, please use 'notification_configuration' instead.
       type: list
       elements: str
     state:
@@ -196,10 +216,11 @@ options:
       default: "present"
       choices: ["present", "absent"]
       type: str
-
+    tower_oauthtoken:
-requirements:
+      description:
-- ansible-tower-cli >= 3.0.2
+        - The Tower OAuth token to use.
-
+      version_added: "3.7"
+      type: str
 extends_documentation_fragment: awx.awx.auth
 '''
 
@@ -304,125 +325,121 @@ EXAMPLES = '''
 RETURN = ''' # '''
 
 
-from ..module_utils.ansible_tower import TowerModule, tower_auth_config, tower_check_mode
+from ..module_utils.tower_api import TowerModule
 
-try:
+OLD_INPUT_NAMES = (
-    import tower_cli
+    'username', 'sender', 'recipients', 'use_tls',
-    import tower_cli.utils.exceptions as exc
+    'host', 'use_ssl', 'password', 'port',
-
+    'channels', 'token', 'account_token', 'from_number',
-    from tower_cli.conf import settings
+    'to_numbers', 'account_sid', 'subdomain', 'service_key',
-except ImportError:
+    'client_name', 'message_from', 'api_url', 'color',
-    pass
+    'rooms', 'notify', 'url', 'headers', 'server',
+    'nickname', 'targets',
+)
 
 
 def main():
+    # Any additional arguments that are not fields of the item can be added here
     argument_spec = dict(
         name=dict(required=True),
-        description=dict(required=False),
+        new_name=dict(),
-        organization=dict(required=False),
+        description=dict(),
-        notification_type=dict(required=True, choices=['email', 'slack', 'twilio', 'pagerduty', 'hipchat', 'webhook', 'irc']),
+        organization=dict(),
-        notification_configuration=dict(required=False),
+        notification_type=dict(required=True, choices=[
-        username=dict(required=False),
+            'email', 'grafana', 'hipchat', 'irc', 'mattermost',
-        sender=dict(required=False),
+            'pagerduty', 'rocketchat', 'slack', 'twilio', 'webhook'
-        recipients=dict(required=False, type='list', elements='str'),
+        ]),
-        use_tls=dict(required=False, type='bool'),
+        notification_configuration=dict(type='dict'),
-        host=dict(required=False),
+        messages=dict(type='dict', default={'started': None, 'success': None, 'error': None, 'workflow_approval': None}),
-        use_ssl=dict(required=False, type='bool'),
+        username=dict(),
-        password=dict(required=False, no_log=True),
+        sender=dict(),
-        port=dict(required=False, type='int'),
+        recipients=dict(type='list', elements='str'),
-        channels=dict(required=False, type='list', elements='str'),
+        use_tls=dict(type='bool'),
-        token=dict(required=False, no_log=True),
+        host=dict(),
-        account_token=dict(required=False, no_log=True),
+        use_ssl=dict(type='bool'),
-        from_number=dict(required=False),
+        password=dict(no_log=True),
-        to_numbers=dict(required=False, type='list', elements='str'),
+        port=dict(type='int'),
-        account_sid=dict(required=False),
+        channels=dict(type='list', elements='str'),
-        subdomain=dict(required=False),
+        token=dict(no_log=True),
-        service_key=dict(required=False, no_log=True),
+        account_token=dict(no_log=True),
-        client_name=dict(required=False),
+        from_number=dict(),
-        message_from=dict(required=False),
+        to_numbers=dict(type='list', elements='str'),
-        api_url=dict(required=False),
+        account_sid=dict(),
-        color=dict(required=False, choices=['yellow', 'green', 'red', 'purple', 'gray', 'random']),
+        subdomain=dict(),
-        rooms=dict(required=False, type='list', elements='str'),
+        service_key=dict(no_log=True),
-        notify=dict(required=False, type='bool'),
+        client_name=dict(),
-        url=dict(required=False),
+        message_from=dict(),
-        headers=dict(required=False, type='dict', default={}),
+        api_url=dict(),
-        server=dict(required=False),
+        color=dict(choices=['yellow', 'green', 'red', 'purple', 'gray', 'random']),
-        nickname=dict(required=False),
+        rooms=dict(type='list', elements='str'),
-        targets=dict(required=False, type='list', elements='str'),
+        notify=dict(type='bool'),
+        url=dict(),
+        headers=dict(type='dict', default={}),
+        server=dict(),
+        nickname=dict(),
+        targets=dict(type='list', elements='str'),
         state=dict(choices=['present', 'absent'], default='present'),
     )
 
+    # Create a module for ourselves
     module = TowerModule(argument_spec=argument_spec, supports_check_mode=True)
 
+    # Extract our parameters
     name = module.params.get('name')
+    new_name = module.params.get("new_name")
     description = module.params.get('description')
     organization = module.params.get('organization')
     notification_type = module.params.get('notification_type')
     notification_configuration = module.params.get('notification_configuration')
-    username = module.params.get('username')
+    messages = module.params.get('messages')
-    sender = module.params.get('sender')
-    recipients = module.params.get('recipients')
-    use_tls = module.params.get('use_tls')
-    host = module.params.get('host')
-    use_ssl = module.params.get('use_ssl')
-    password = module.params.get('password')
-    port = module.params.get('port')
-    channels = module.params.get('channels')
-    token = module.params.get('token')
-    account_token = module.params.get('account_token')
-    from_number = module.params.get('from_number')
-    to_numbers = module.params.get('to_numbers')
-    account_sid = module.params.get('account_sid')
-    subdomain = module.params.get('subdomain')
-    service_key = module.params.get('service_key')
-    client_name = module.params.get('client_name')
-    message_from = module.params.get('message_from')
-    api_url = module.params.get('api_url')
-    color = module.params.get('color')
-    rooms = module.params.get('rooms')
-    notify = module.params.get('notify')
-    url = module.params.get('url')
-    headers = module.params.get('headers')
-    server = module.params.get('server')
-    nickname = module.params.get('nickname')
-    targets = module.params.get('targets')
     state = module.params.get('state')
 
-    json_output = {'notification': name, 'state': state}
+    # Attempt to look up the related items the user specified (these will fail the module if not found)
+    organization_id = None
+    if organization:
+        organization_id = module.resolve_name_to_id('organizations', organization)
 
-    tower_auth = tower_auth_config(module)
+    # Attempt to look up an existing item based on the provided data
-    with settings.runtime_values(**tower_auth):
+    existing_item = module.get_one('notification_templates', **{
-        tower_check_mode(module)
+        'data': {
-        notification_template = tower_cli.get_resource('notification_template')
+            'name': name,
+            'organization': organization_id,
+        }
+    })
 
-        try:
+    # Create notification_configuration from legacy inputs
-            org_res = tower_cli.get_resource('organization')
+    final_notification_configuration = {}
-            org = org_res.get(name=organization)
+    for legacy_input in OLD_INPUT_NAMES:
+        if module.params.get(legacy_input) is not None:
+            module.deprecate(msg='{0} parameter has been depricated, please use notification_configuration instead.'.format(legacy_input), version="3.6")
+            final_notification_configuration[legacy_input] = module.params.get(legacy_input)
+    # Give anything in notification_configuration prescedence over the individual inputs
+    if notification_configuration is not None:
+        final_notification_configuration.update(notification_configuration)
 
-            if state == 'present':
+    # Create the data that gets sent for create and update
-                result = notification_template.modify(name=name, description=description, organization=org['id'],
+    new_fields = {'notification_configuration': final_notification_configuration}
-                                                      notification_type=notification_type,
+    new_fields['name'] = new_name if new_name else name
-                                                      notification_configuration=notification_configuration,
+    if description is not None:
-                                                      username=username, sender=sender, recipients=recipients,
+        new_fields['description'] = description
-                                                      use_tls=use_tls, host=host, use_ssl=use_ssl, password=password,
+    if organization is not None:
-                                                      port=port, channels=channels, token=token,
+        new_fields['organization'] = organization_id
-                                                      account_token=account_token, from_number=from_number,
+    if notification_type is not None:
-                                                      to_numbers=to_numbers, account_sid=account_sid,
+        new_fields['notification_type'] = notification_type
-                                                      subdomain=subdomain, service_key=service_key,
+    if messages is not None:
-                                                      client_name=client_name, message_from=message_from,
+        new_fields['messages'] = messages
-                                                      api_url=api_url, color=color, rooms=rooms, notify=notify,
-                                                      url=url, headers=headers, server=server, nickname=nickname,
-                                                      targets=targets, create_on_missing=True)
-                json_output['id'] = result['id']
-            elif state == 'absent':
-                result = notification_template.delete(name=name)
-        except (exc.NotFound) as excinfo:
-            module.fail_json(msg='Failed to update notification template, organization not found: {0}'.format(excinfo), changed=False)
-        except (exc.ConnectionError, exc.BadRequest, exc.AuthError) as excinfo:
-            module.fail_json(msg='Failed to update notification template: {0}'.format(excinfo), changed=False)
 
-    json_output['changed'] = result['changed']
+    if state == 'absent':
-    module.exit_json(**json_output)
+        # If the state was absent we can let the module delete it if needed, the module will handle exiting from this
+        module.delete_if_needed(existing_item)
+    elif state == 'present':
+        # If the state was present and we can let the module build or update the existing item, this will return on its own
+        module.create_or_update_if_needed(
+            existing_item, new_fields,
+            endpoint='notification_templates', item_type='notification_template',
+            associations={
+            }
+        )
 
 
 if __name__ == '__main__':

awx_collection/tests/integration/targets/tower_notification/tasks/main.yml

@@ -9,6 +9,63 @@
     hipchat_not: "AWX-Collection-tests-tower_notification-hipchat-not-{{ lookup('password', '/dev/null chars=ascii_letters length=16') }}"
     irc_not: "AWX-Collection-tests-tower_notification-irc-not-{{ lookup('password', '/dev/null chars=ascii_letters length=16') }}"
 
+- name: Test deprication warnings
+  tower_notification:
+    name: "{{ slack_not }}"
+    organization: Default
+    notification_type: slack
+    username: maw
+    sender: maw
+    recipients:
+      - everyone
+    use_tls: True
+    host: all
+    use_ssl: False
+    password: password
+    port: 12
+    channels:
+      - general
+    token: chunkecheese
+    account_token: asdf1234
+    from_number: "1 (888) 733-4281"
+    to_numbers:
+      - 867-5309
+    account_sid: vicious
+    subdomain: 'redhat.com'
+    service_key: skeleton
+    client_name: Bill
+    message_from: me
+    api_url: https://tower.example.com/api/v2
+    color: green
+    rooms:
+      - The Study
+      - Kitchen
+      - Ballroom
+      - Conservatory
+      - Billiard Room
+      - Library
+      - Hall
+      - Lounge
+      - Dining Room
+      - Cellar
+    notify: True
+    url: ansible.com
+    headers:
+      X-Custom-Header: value123
+    server: littimer.somewhere.com
+    nickname: chalk
+    targets:
+      - zombie
+    state: absent
+  register: result
+  ignore_errors: True
+
+- assert:
+    that:
+      - "'deprecations' in result"
+      # The 27 can be count from the size of the OLD_INPUT_NAMES list in the module
+      - result['deprecations'] | length() == 27
+
 - name: Create Slack notification
   tower_notification:
     name: "{{ slack_not }}"
@@ -51,6 +108,22 @@
     that:
       - result is changed
 
+- name: Recreate with notification_configuration
+  tower_notification:
+    name: "{{ webhook_not }}"
+    organization: Default
+    notification_type: webhook
+    notification_configuration:
+      url: http://www.example.com/hook
+      headers:
+        X-Custom-Header: value123
+    state: present
+  register: result
+
+- assert:
+    that:
+      - result is not changed
+
 - name: Delete webhook notification
   tower_notification:
     name: "{{ webhook_not }}"