Add Attachments

changelogs/fragments/attachments.yaml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+- attachments - Add a client for attachment management. Add support for attachments in change_request, configuration_item, incident and problem modules, including their info counterparts. (https://github.com/ansible-collections/servicenow.itsm/pull/91)

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,147 @@
+# -*- 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.read(), 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 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):