Add Attachments

plugins/doc_fragments/attachments.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2021, XLAB Steampunk <[email protected]>
+#
+# 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
+
+
+class ModuleDocFragment(object):
+    DOCUMENTATION = r"""
+options:
+  attachments:
+    version_added: 1.2.0
+    description:
+      - ServiceNow attachments.
+    type: list
+    elements: dict
+    suboptions:
+      path:
+        description:
+          - Path to the file to be uploaded.
+        required: true
+        type: str
+      name:
+        description:
+          - Name of the file to be uploaded without the file extension.
+          - If not specified, the module will use I(path)'s base name.
+        type: str
+      type:
+        description:
+          - MIME type of the file to be attached.
+          - If not specified, the module will try to guess the file's type from its extension.
+        type: str
+"""

plugins/module_utils/arguments.py

@@ -75,6 +75,22 @@
     sys_id=dict(type="str"),
     number=dict(type="str"),
     query=dict(type="list", elements="dict"),
+    attachments=dict(
+        type="list",
+        elements="dict",
+        options=dict(
+            path=dict(
+                type="str",
+                required=True,
+            ),
+            name=dict(
+                type="str",
+            ),
+            type=dict(
+                type="str",
+            ),
+        ),
+    ),
 )
 
 

plugins/module_utils/attachment.py

@@ -0,0 +1,156 @@
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2021, XLAB Steampunk <[email protected]>
+#
+# 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
+
+import collections
+import mimetypes
+import os
+
+from . import errors
+
+
+def _path(*subpaths):
+    return "/".join(("attachment",) + subpaths)
+
+
+class AttachmentClient:
+    def __init__(self, client, batch_size=10000):
+        # 10000 records is default batch size for ServiceNow Attachment REST API, so we also use it
+        # as a default.
+        self.client = client
+        self.batch_size = batch_size
+
+    def list_records(self, query=None):
+        base_query = dict(query or {}, sysparm_limit=self.batch_size)
+
+        offset = 0
+        total = 1  # Dummy value that ensures loop executes at least once
+        result = []
+
+        while offset < total:
+            response = self.client.get(
+                _path(), query=dict(base_query, sysparm_offset=offset)
+            )
+
+            result.extend(response.json["result"])
+            total = int(response.headers["X-Total-Count"])
+            offset += self.batch_size
+
+        return result
+
+    def create_record(self, query, data, mime_type, check_mode):
+        if check_mode:
+            return query
+        return self.client.request(
+            "POST",
+            _path("file"),
+            query=query,
+            headers={"Accept": "application/json", "Content-type": mime_type},
+            bytes=data,
+        ).json["result"]
+
+    def upload_record(self, table, table_sys_id, metadata, check_mode):
+        # Table and table_sys_id parameters uniquely identify the record we will attach a file to.
+        query = dict(
+            table_name=table,
+            table_sys_id=table_sys_id,
+            file_name=metadata["name"],
+            content_type=metadata["type"],
+            hash=metadata["hash"],
+        )
+        try:
+            with open(metadata["path"], "rb") as file_obj:
+                return self.create_record(
+                    query, file_obj, query["content_type"], check_mode
+                )
+        except (IOError, OSError):
+            raise errors.ServiceNowError("Cannot open {0}".format(metadata["path"]))
+
+    def upload_records(self, table, table_sys_id, metadata_dict, check_mode):
+        return [
+            self.upload_record(
+                table, table_sys_id, dict(metadata, name=name), check_mode
+            )
+            for name, metadata in metadata_dict.items()
+        ]
+
+    def delete_record(self, record, check_mode):
+        if not check_mode:
+            self.client.delete(_path(record["sys_id"]))
+
+    def delete_attached_records(self, table, table_sys_id, check_mode):
+        for record in self.list_records(
+            dict(table_name=table, table_sys_id=table_sys_id)
+        ):
+            self.delete_record(record, check_mode)
+
+    def update_records(
+        self, table, table_sys_id, metadata_dict, records, check_mode
+    ):
+        mapped_records = dict((r["file_name"], r) for r in records)
+
+        for name, metadata in metadata_dict.items():
+            record = mapped_records.get(name, {})
+            if record.get("hash") != metadata["hash"]:
+                if record:
+                    self.delete_record(record, check_mode)
+                mapped_records[name] = self.upload_record(
+                    table, table_sys_id, dict(metadata, name=name), check_mode
+                )
+
+        return list(mapped_records.values())
+
+
+def transform_metadata_list(metadata_list, hashing_method):
+    metadata_dict = dict()
+    dups = collections.defaultdict(list)
+
+    for metadata in metadata_list or []:
+        name = get_file_name(metadata)
+        dups[name].append(metadata["path"])
+        metadata_dict[name] = {
+            "path": metadata["path"],
+            "type": get_file_type(metadata),
+            "hash": hashing_method(metadata["path"]),
+        }
+
+    dup_sets = ["({0})".format(", ".join(v)) for v in dups.values() if len(v) > 1]
+    if dup_sets:
+        raise errors.ServiceNowError(
+            "Found the following duplicates: {0}".format(" ".join(dup_sets))
+        )
+    return metadata_dict
+
+
+def get_file_name(metadata):
+    if "name" in metadata and metadata["name"] is not None:
+        return metadata["name"]
+    return os.path.basename(metadata["path"])
+
+
+def get_file_type(metadata):
+    if "type" in metadata and metadata["type"] is not None:
+        return metadata["type"]
+    return mimetypes.guess_type(metadata["path"])[0]
+
+
+def build_query(table, table_sys_id, metadata):
+    return dict(
+        file_name=get_file_name(metadata),
+        content_type=get_file_type(metadata),
+        table_name=table,
+        table_sys_id=table_sys_id,
+    )
+
+
+def are_changed(records, metadata_dict):
+    mapped_records = dict((r["file_name"], r) for r in records)
+    return [
+        metadata["hash"] != mapped_records.get(name, {}).get("hash")
+        for name, metadata in metadata_dict.items()
+    ]

plugins/module_utils/client.py

@@ -17,6 +17,9 @@
 from .errors import ServiceNowError, AuthError, UnexpectedAPIResponse
 
 
+DEFAULT_HEADERS = dict(Accept="application/json")
+
+
 class Response:
     def __init__(self, status, data, headers=None):
         self.status = status
@@ -129,15 +132,23 @@ def _request(self, method, path, data=None, headers=None):
             return Response(raw_resp.getcode(), raw_resp.read(), raw_resp.info())
         return Response(raw_resp.status, raw_resp.read(), raw_resp.headers)
 
-    def request(self, method, path, query=None, data=None):
+    def request(self, method, path, query=None, data=None, headers=None, bytes=None):
+        # Make sure we only have one kind of payload
+        if data is not None and bytes is not None:
+            raise AssertionError(
+                "Cannot have JSON and binary payload in a single request."
+            )
+
         escaped_path = quote(path.rstrip("/"))
         url = "{0}/api/now/{1}".format(self.host, escaped_path)
         if query:
             url = "{0}?{1}".format(url, urlencode(query))
-        headers = dict(Accept="application/json", **self.auth_header)
+        headers = dict(headers or DEFAULT_HEADERS, **self.auth_header)
         if data is not None:
             data = json.dumps(data, separators=(",", ":"))
             headers["Content-type"] = "application/json"
+        elif bytes is not None:
+            data = bytes
         return self._request(method, url, data=data, headers=headers)
 
     def get(self, path, query=None):

plugins/modules/change_request.py

@@ -16,6 +16,7 @@
   - Manca Bizjak (@mancabizjak)
   - Miha Dolinar (@mdolin)
   - Tadej Borovsak (@tadeboro)
+  - Matej Pevec (@mysteriouswolf)
 
 short_description: Manage ServiceNow change requests
 
@@ -28,6 +29,7 @@
   - servicenow.itsm.instance
   - servicenow.itsm.sys_id
   - servicenow.itsm.number
+  - servicenow.itsm.attachments
 
 seealso:
   - module: servicenow.itsm.change_request_info
@@ -193,7 +195,16 @@
 
 from ansible.module_utils.basic import AnsibleModule
 
-from ..module_utils import arguments, client, table, errors, utils, validation
+
+from ..module_utils import (
+    arguments,
+    client,
+    table,
+    attachment,
+    errors,
+    utils,
+    validation,
+)
 from ..module_utils.change_request import PAYLOAD_FIELDS_MAPPING
 
 
@@ -215,12 +226,17 @@
 )
 
 
-def ensure_absent(module, table_client):
+def ensure_absent(module, table_client, attachment_client):
     mapper = utils.PayloadMapper(PAYLOAD_FIELDS_MAPPING, module.warn)
     query = utils.filter_dict(module.params, "sys_id", "number")
     change = table_client.get_record("change_request", query)
 
     if change:
+        attachment_client.delete_attached_records(
+            "change_request",
+            change["sys_id"],
+            module.check_mode,
+        )
         table_client.delete_record("change_request", change, module.check_mode)
         return True, None, dict(before=mapper.to_ansible(change), after=None)
 
@@ -242,10 +258,13 @@ def validate_params(params, change_request=None):
         )
 
 
-def ensure_present(module, table_client):
+def ensure_present(module, table_client, attachment_client):
     mapper = utils.PayloadMapper(PAYLOAD_FIELDS_MAPPING, module.warn)
     query = utils.filter_dict(module.params, "sys_id", "number")
     payload = build_payload(module, table_client)
+    attachments = attachment.transform_metadata_list(
+        module.params["attachments"], module.sha256
+    )
 
     if not query:
         # User did not specify existing change request, so we need to create a new one.
@@ -255,12 +274,29 @@ def ensure_present(module, table_client):
                 "change_request", mapper.to_snow(payload), module.check_mode
             )
         )
+
+        # When we execute in check mode, new["sys_id"] is not defined.
+        # In order to give users back as much info as possible, we fake the sys_id in the
+        # next call.
+        new["attachments"] = attachment_client.upload_records(
+            "change_request",
+            new.get("sys_id", "N/A"),
+            attachments,
+            module.check_mode,
+        )
         return True, new, dict(before=None, after=new)
 
     old = mapper.to_ansible(
         table_client.get_record("change_request", query, must_exist=True)
     )
-    if utils.is_superset(old, payload):
+
+    old["attachments"] = attachment_client.list_records(
+        dict(table_name="change_request", table_sys_id=old["sys_id"])
+    )
+
+    if utils.is_superset(old, payload) and not any(
+        attachment.are_changed(old["attachments"], attachments)
+    ):
         # No change in parameters we are interested in - nothing to do.
         return False, old, dict(before=old, after=old)
 
@@ -273,6 +309,14 @@ def ensure_present(module, table_client):
             module.check_mode,
         )
     )
+    new["attachments"] = attachment_client.update_records(
+        "change_request",
+        old["sys_id"],
+        attachments,
+        old["attachments"],
+        module.check_mode,
+    )
+
     return True, new, dict(before=old, after=new)
 
 
@@ -308,15 +352,15 @@ def build_payload(module, table_client):
     return payload
 
 
-def run(module, table_client):
+def run(module, table_client, attachment_client):
     if module.params["state"] == "absent":
-        return ensure_absent(module, table_client)
-    return ensure_present(module, table_client)
+        return ensure_absent(module, table_client, attachment_client)
+    return ensure_present(module, table_client, attachment_client)
 
 
 def main():
     module_args = dict(
-        arguments.get_spec("instance", "sys_id", "number"),
+        arguments.get_spec("instance", "sys_id", "number", "attachments"),
         state=dict(
             type="str",
             choices=[
@@ -434,7 +478,8 @@ def main():
     try:
         snow_client = client.Client(**module.params["instance"])
         table_client = table.TableClient(snow_client)
-        changed, record, diff = run(module, table_client)
+        attachment_client = attachment.AttachmentClient(snow_client)
+        changed, record, diff = run(module, table_client, attachment_client)
         module.exit_json(changed=changed, record=record, diff=diff)
     except errors.ServiceNowError as e:
         module.fail_json(msg=str(e))