#644 Add contact modules (#671)

* Add modules netbox_contact_role, netbox_contact, netbox_contact_group

Author: rodvand

plugins/module_utils/netbox_tenancy.py

@@ -14,6 +14,9 @@
 
 NB_TENANTS = "tenants"
 NB_TENANT_GROUPS = "tenant_groups"
+NB_CONTACTS = "contacts"
+NB_CONTACT_GROUPS = "contact_groups"
+NB_CONTACT_ROLES = "contact_roles"
 
 
 class NetboxTenancyModule(NetboxModule):
@@ -25,8 +28,10 @@ def run(self):
         This function should have all necessary code for endpoints within the application
         to create/update/delete the endpoint objects
         Supported endpoints:
-        tenants
-        tenant groups
+        - tenants
+        - tenant groups
+        - contacts
+        - contact groups
         """
         # Used to dynamically set key when returning results
         endpoint_name = ENDPOINT_NAME_MAPPING[self.endpoint]

plugins/module_utils/netbox_utils.py

@@ -89,7 +89,7 @@
         "services",
     ],
     secrets=[],
-    tenancy=["tenants", "tenant_groups"],
+    tenancy=["tenants", "tenant_groups", "contacts", "contact_groups", "contact_roles"],
     virtualization=["cluster_groups", "cluster_types", "clusters", "virtual_machines"],
 )
 
@@ -102,6 +102,8 @@
     cluster_group="slug",
     cluster_type="slug",
     config_context="name",
+    contact_group="name",
+    contact_role="name",
     device="name",
     device_role="slug",
     device_type="slug",
@@ -113,6 +115,7 @@
     manufacturer="slug",
     nat_inside="address",
     nat_outside="address",
+    parent_contact_group="name",
     parent_location="slug",
     parent_region="slug",
     parent_site_group="slug",
@@ -162,6 +165,7 @@
     "cluster_groups": "cluster_groups",
     "cluster_type": "cluster_types",
     "config_context": "config_contexts",
+    "contact_groups": "contact_groups",
     "dcim.consoleport": "console_ports",
     "dcim.consoleserverport": "console_server_ports",
     "dcim.frontport": "front_ports",
@@ -189,6 +193,7 @@
     "nat_inside": "ip_addresses",
     "nat_outside": "ip_addresses",
     "platform": "platforms",
+    "parent_contact_group": "contact_groups",
     "parent_location": "locations",
     "parent_interface": "interfaces",
     "parent_vm_interface": "interfaces",
@@ -253,6 +258,9 @@
     "console_port_templates": "console_port_template",
     "console_server_ports": "console_server_port",
     "console_server_port_templates": "console_server_port_template",
+    "contacts": "contact",
+    "contact_groups": "contact_group",
+    "contact_roles": "contact_role",
     "device_bays": "device_bay",
     "device_bay_templates": "device_bay_template",
     "devices": "device",
@@ -327,6 +335,9 @@
     "console_port_template": set(["name", "device_type"]),
     "console_server_port": set(["name", "device"]),
     "console_server_port_template": set(["name", "device_type"]),
+    "contact": set(["name", "group"]),
+    "contact_group": set(["name"]),
+    "contact_role": set(["name"]),
     "dcim.consoleport": set(["name", "device"]),
     "dcim.consoleserverport": set(["name", "device"]),
     "dcim.frontport": set(["name", "device", "rear_port"]),
@@ -354,6 +365,7 @@
     "manufacturer": set(["slug"]),
     "master": set(["name"]),
     "nat_inside": set(["vrf", "address"]),
+    "parent_contact_group": set(["name"]),
     "parent_location": set(["slug"]),
     "parent_interface": set(["name"]),
     "parent_vm_interface": set(["name"]),
@@ -452,6 +464,8 @@
     "circuit_type": "type",
     "cluster_type": "type",
     "cluster_group": "group",
+    "contact_group": "group",
+    "parent_contact_group": "parent",
     "parent_location": "parent",
     "parent_interface": "parent",
     "parent_vm_interface": "parent",
@@ -478,6 +492,8 @@
     "circuit_types",
     "cluster_groups",
     "cluster_types",
+    "contact_groups",
+    "contact_roles",
     "device_roles",
     "device_types",
     "ipam_roles",
@@ -989,6 +1005,7 @@ def _find_ids(self, data, user_query_params):
                             "platforms",
                             "cluster_groups",
                             "clusters",
+                            "contact_groups",
                             "tenant_groups",
                             "tenants",
                             "tags",

plugins/modules/netbox_contact.py

@@ -0,0 +1,177 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2021, Martin Rødvand (@rodvand)
+# 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 = r"""
+---
+module: netbox_contact
+short_description: Creates or removes contacts from NetBox
+description:
+  - Creates or removes contacts from NetBox
+notes:
+  - Tags should be defined as a YAML list
+  - This should be ran with connection C(local) and hosts C(localhost)
+author:
+  - Martin Rødvand (@rodvand)
+requirements:
+  - pynetbox
+version_added: "3.5.0"
+extends_documentation_fragment:
+  - netbox.netbox.common
+options:
+  data:
+    type: dict
+    description:
+      - Defines the contact configuration
+    suboptions:
+      name:
+        description:
+          - Name of the contact to be created
+        required: true
+        type: str
+      title:
+        description:
+          - The title of the contact
+        required: false
+        type: str
+      phone:
+        description:
+          - The phone number of the contact
+        required: false
+        type: str
+      email:
+        description:
+          - The email of the contact
+        required: false
+        type: str
+      address:
+        description:
+          - The address of the contact
+        required: false
+        type: str
+      comments:
+        description:
+          - Comments on the contact
+        required: false
+        type: str
+      contact_group:
+        description:
+          - Group assignment for the contact
+        required: false
+        type: raw
+      tags:
+        description:
+          - Any tags that the contact may need to be associated with
+        required: false
+        type: list
+        elements: raw
+      custom_fields:
+        description:
+          - must exist in NetBox
+        required: false
+        type: dict
+    required: true
+"""
+
+EXAMPLES = r"""
+- name: "Test NetBox module"
+  connection: local
+  hosts: localhost
+  gather_facts: False
+  tasks:
+    - name: Create contact within NetBox with only required information
+      netbox_contact:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Contact One
+        state: present
+
+    - name: Delete contact within netbox
+      netbox_contact:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Contact One
+        state: absent
+
+    - name: Create contact with all parameters
+      netbox_contact:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: contact ABC          
+          title: Mr Contact
+          phone: 123456789
+          email: contac@contact.com          
+          tags:
+            - tagA
+            - tagB
+            - tagC
+        state: present
+"""
+
+RETURN = r"""
+contact:
+  description: Serialized object as created or already existent within NetBox
+  returned: on creation
+  type: dict
+msg:
+  description: Message indicating failure or info about what has been achieved
+  returned: always
+  type: str
+"""
+
+from ansible_collections.netbox.netbox.plugins.module_utils.netbox_utils import (
+    NetboxAnsibleModule,
+    NETBOX_ARG_SPEC,
+)
+from ansible_collections.netbox.netbox.plugins.module_utils.netbox_tenancy import (
+    NetboxTenancyModule,
+    NB_CONTACTS,
+)
+from copy import deepcopy
+
+
+def main():
+    """
+    Main entry point for module execution
+    """
+    argument_spec = deepcopy(NETBOX_ARG_SPEC)
+    argument_spec.update(
+        dict(
+            data=dict(
+                type="dict",
+                required=True,
+                options=dict(
+                    name=dict(required=True, type="str"),
+                    title=dict(required=False, type="str"),
+                    phone=dict(required=False, type="str"),
+                    email=dict(required=False, type="str"),
+                    address=dict(required=False, type="str"),
+                    comments=dict(required=False, type="str"),
+                    contact_group=dict(required=False, type="raw"),
+                    tags=dict(required=False, type="list", elements="raw"),
+                    custom_fields=dict(required=False, type="dict"),
+                ),
+            ),
+        )
+    )
+
+    required_if = [("state", "present", ["name"]), ("state", "absent", ["name"])]
+
+    module = NetboxAnsibleModule(
+        argument_spec=argument_spec, supports_check_mode=True, required_if=required_if
+    )
+
+    netbox_contact = NetboxTenancyModule(module, NB_CONTACTS)
+    netbox_contact.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()