pyPreservica 0.9.9__py3-none-any.whl → 3.3.4__py3-none-any.whl

pyPreservica/webHooksAPI.py

@@ -0,0 +1,211 @@
+"""
+pyPreservica WebHooksAPI module definition
+
+A client library for the Preservica Repository web services Webhook API
+https://us.preservica.com/api/webhook/documentation.html
+
+author:     James Carr
+licence:    Apache License 2.0
+
+"""
+from http.server import BaseHTTPRequestHandler
+from typing import Generator
+from urllib.parse import urlparse, parse_qs
+import hmac
+from pyPreservica.common import *
+
+logger = logging.getLogger(__name__)
+
+BASE_ENDPOINT = '/api/webhook'
+
+class FlaskWebhookHandler:
+
+    def __init__(self, request, secret_key: str):
+        from flask import request
+        self.request = request
+        self.secret_key = secret_key
+
+
+    def response_ok(self):
+        return json.dumps({'success':True}), 200, {'ContentType':'application/json'}
+
+    def is_challenge(self) -> bool:
+        challenge_code = self.request.args.get('challengeCode')
+        return challenge_code is not None
+
+    def verify_challenge(self):
+        challenge_code = self.request.args.get('challengeCode')
+        if challenge_code is not None:
+            challenge_response: str = hmac.new(key=bytes(self.secret_key, 'latin-1'), msg=bytes(challenge_code, 'latin-1'),
+                                 digestmod=hashlib.sha256).hexdigest()
+            body = json.dumps({"challengeCode": f"{challenge_code}", "challengeResponse": f"{challenge_response}"})
+            return body, 200, {"application/json": 'text/plain; charset=utf-8'}
+
+        return json.dumps({'success': True}), 200, {'ContentType': 'application/json'}
+
+
+
+    def process_request(self) -> Generator:
+        preservica_signature = self.request.headers.get('Preservica-Signature')
+        if preservica_signature is not None:
+            message_body = data = self.request.data
+            verify_body = f"preservica-webhook-auth{message_body.decode('utf-8')}"
+            digest = hmac.new(key=bytes(self.secret_key, 'latin-1'), msg=bytes(verify_body, 'latin-1'),
+                              digestmod=hashlib.sha256).hexdigest()
+            if preservica_signature == digest:
+                json_body = json.loads(message_body.decode('utf-8'))
+                for event in json_body['events']:
+                    yield event
+
+
+class WebHookHandler(BaseHTTPRequestHandler):
+    """
+    A sample web hook web server which provides handshake verification
+    The shared secret key is passed in via the HTTPServer
+
+    Extend the class and implement do_WORK() method
+    The JSON document is passed into do_WORK()
+
+    """
+
+    def hmac(self, key, message):
+        return hmac.new(key=bytes(key, 'latin-1'), msg=bytes(message, 'latin-1'), digestmod=hashlib.sha256).hexdigest()
+
+    def do_POST(self):
+        result = urlparse(self.path)
+        q = parse_qs(result.query)
+        if 'challengeCode' in q:
+            code = q['challengeCode'][0]
+            signature = self.hmac(self.server.secret_key, code)
+            response = f'{{ "challengeCode": "{code}",     "challengeResponse": "{signature}" }}'
+            self.send_response(200)
+            self.send_header("Content-type", "application/json")
+            self.end_headers()
+            self.wfile.write(bytes(response.encode('utf-8')))
+            self.log_message(f"Handshake Completed. {response.encode('utf-8')}")
+        else:
+            verif_sig = self.headers.get("Preservica-Signature", None)
+            if "chunked" in self.headers.get("Transfer-Encoding", "") and (verif_sig is not None):
+                payload = ""
+                while True:
+                    line = self.rfile.readline().strip()
+                    chunk_length = int(line, 16)
+                    if chunk_length != 0:
+                        chunk = self.rfile.read(chunk_length)
+                        payload = payload + chunk.decode("utf-8")
+                    self.rfile.readline()
+                    if chunk_length == 0:
+                        verify_body = f"preservica-webhook-auth{payload}"
+                        signature = self.hmac(self.server.secret_key, verify_body)
+                        if signature == verif_sig:
+                            self.log_message("Signature Verified. Doing Work...")
+                            self.log_message(payload)
+                            self.send_response(200)
+                            self.end_headers()
+                            self.do_WORK(json.loads(payload))
+                        break
+
+
+class TriggerType(Enum):
+    """
+    Enumeration of the Web hooks Trigger Types
+    """
+    MOVED = "MOVED"
+    INDEXED = "FULL_TEXT_INDEXED"
+    SECURITY_CHANGED = "CHANGED_SECURITY_DESCRIPTOR"
+    INGEST_FAILED = "INGEST_FAILED"
+    CHANGE_ASSET_VISIBILITY  = "CHANGE_ASSET_VISIBILITY"
+
+
+class WebHooksAPI(AuthenticatedAPI):
+    """
+    Class to register new webhook endpoints
+
+    """
+
+    def subscriptions(self):
+        """
+        Return all the current active web hook subscriptions as a json document
+
+        :return: list of web hooks
+        """
+        self._check_if_user_has_manager_role()
+        headers = {HEADER_TOKEN: self.token}
+        response = self.session.get(f'{self.protocol}://{self.server}{BASE_ENDPOINT}/subscriptions', headers=headers)
+        if response.status_code == requests.codes.unauthorized:
+            self.token = self.__token__()
+            return self.subscriptions()
+        if response.status_code == requests.codes.ok:
+            json_response = str(response.content.decode('utf-8'))
+            doc = json.loads(json_response)
+            return doc
+        else:
+            exception = HTTPException("", response.status_code, response.url, "subscriptions",
+                                      response.content.decode('utf-8'))
+            logger.error(exception)
+            raise exception
+
+    def unsubscribe_all(self):
+        """
+        Unsubscribe from all webhooks.
+        :return:
+        """
+        self._check_if_user_has_manager_role()
+        subscriptions = self.subscriptions()
+        for sub in subscriptions:
+            self.unsubscribe(sub['id'])
+
+    def unsubscribe(self, subscription_id: str):
+        """
+        Unsubscribe from the provided webhook.
+
+        :param subscription_id:
+        :return:
+        """
+        self._check_if_user_has_manager_role()
+        headers = {HEADER_TOKEN: self.token}
+        response = self.session.delete(
+            f'{self.protocol}://{self.server}{BASE_ENDPOINT}/subscriptions/{subscription_id}',
+            headers=headers)
+        if response.status_code == requests.codes.unauthorized:
+            self.token = self.__token__()
+            return self.unsubscribe(subscription_id)
+        if response.status_code == requests.codes.no_content:
+            json_response = str(response.content.decode('utf-8'))
+            logger.debug(json_response)
+            return json_response
+        else:
+            exception = HTTPException(str(subscription_id), response.status_code, response.url, "unsubscribe",
+                                      response.content.decode('utf-8'))
+            logger.error(exception)
+            raise exception
+
+    def subscribe(self, url: str, triggerType: TriggerType, secret: str):
+        """
+        Subscribe to a new web hook
+
+        :param url:
+        :param triggerType:
+        :param secret:
+        :return: json_response
+        """
+        self._check_if_user_has_manager_role()
+        headers = {HEADER_TOKEN: self.token, 'Accept': 'application/json', 'Content-Type': 'application/json'}
+
+        json_payload = f'{{"url": "{url}", "triggerType": "{triggerType.value}", "secret": "{secret}",  ' \
+                       f'"includeIdentifiers": "true"}}'
+
+        response = self.session.post(f'{self.protocol}://{self.server}{BASE_ENDPOINT}/subscriptions', headers=headers,
+                                     data=json.dumps(json.loads(json_payload)))
+        if response.status_code == requests.codes.unauthorized:
+            self.token = self.__token__()
+            return self.subscribe(url, triggerType, secret)
+        if response.status_code == requests.codes.ok:
+            json_response = str(response.content.decode('utf-8'))
+            logger.debug(json_response)
+            return json_response
+        else:
+            exception = HTTPException(str(url), response.status_code, response.url, "subscribe",
+                                      response.content.decode('utf-8'))
+            logger.error(response.content.decode('utf-8'))
+            raise exception

pyPreservica/workflowAPI.py

@@ -1,6 +1,17 @@
+"""
+pyPreservica WorkflowAPI module definition
+
+A client library for the Preservica Repository web services Workflow API
+https://us.preservica.com/sdb/rest/workflow/documentation.html
+
+author:     James Carr
+licence:    Apache License 2.0
+
+"""
+
 import uuid
 import datetime
-from xml.dom import minidom
+from typing import Callable
 from xml.etree import ElementTree
 
 from pyPreservica.common import *
@@ -8,15 +19,12 @@ from pyPreservica.common import *
 logger = logging.getLogger(__name__)
 
 
-def prettify(elem):
-    """Return a pretty-printed XML string for the Element.
+class WorkflowInstance:
+    """
+        Defines a workflow Instance.
+        The workflow Instance is a context which has been executed
     """
-    rough_string = ElementTree.tostring(elem, 'utf-8')
-    re_parsed = minidom.parseString(rough_string)
-    return re_parsed.toprettyxml(indent="  ")
-
 
-class WorkflowInstance:
     def __init__(self, instance_id: int):
         self.instance_id = instance_id
         self.started = None
@@ -28,6 +36,7 @@ class WorkflowInstance:
         self.workflow_context_id = None
         self.workflow_context_name = None
         self.workflow_definition_id = None
+        self.xml_response = None
 
     def __str__(self):
         return f"Workflow Instance ID: {self.instance_id}"
@@ -37,13 +46,20 @@ class WorkflowInstance:
 
 
 class WorkflowContext:
-    def __init__(self, workflow_id, workflow_name):
+    """
+        Defines a workflow context.
+        The workflow context is the pre-defined workflow which is ready to run
+    """
+
+    def __init__(self, workflow_id, workflow_name: str):
         self.workflow_id = workflow_id
         self.workflow_name = workflow_name
 
     def __str__(self):
-        return f"Workflow ID:\t\t\t{self.workflow_id}\n" \
-               f"Workflow Name:\t\t\t{self.workflow_name}\n"
+        return f"""
+              Workflow ID:    {self.workflow_id}
+              Workflow Name:  {self.workflow_name}
+        """
 
     def __repr__(self):
         return self.__str__()
@@ -51,8 +67,11 @@ class WorkflowContext:
 
 class WorkflowAPI(AuthenticatedAPI):
     """
-              A client library for the Preservica Workflow API
-              https://preview.preservica.com/sdb/rest/workflow/documentation.html
+        A class for calling the Preservica Workflow API
+
+        This API can be used to programmatically manage the Preservica Workflows.
+
+        https://preview.preservica.com/sdb/rest/workflow/documentation.html
 
     """
 
@@ -60,22 +79,30 @@ class WorkflowAPI(AuthenticatedAPI):
                        'Failed']
     workflow_types = ['Ingest', 'Access', 'Transformation', 'DataManagement']
 
-    def __init__(self, username=None, password=None, tenant=None, server=None, use_shared_secret=False):
-        super().__init__(username, password, tenant, server, use_shared_secret)
+    def __init__(self, username: str = None, password: str = None, tenant: str = None, server: str = None,
+                 use_shared_secret: bool = False, two_fa_secret_key: str = None,
+                 protocol: str = "https", request_hook: Callable = None, credentials_path: str = 'credentials.properties'):
+
+        super().__init__(username, password, tenant, server, use_shared_secret, two_fa_secret_key,
+                         protocol, request_hook, credentials_path)
         self.base_url = "sdb/rest/workflow"
 
     def get_workflow_contexts_by_type(self, workflow_type: str):
         """
         Return a list of Workflow Contexts which have the same Workflow type
 
-        :param workflow_type: The Workflow type:
-        Ingest, Access, Transformation or DataManagement
+        :param workflow_type: The Workflow type  Ingest, Access, Transformation or DataManagement
+        :type workflow_type: str
+
+        :return: List of Workflow Contexts
+        :rtype: list
 
         """
+
         headers = {HEADER_TOKEN: self.token}
         params = {"type": workflow_type}
-        workflow_contexts = list()
-        request = requests.get(f'https://{self.server}/{self.base_url}/contexts', headers=headers, params=params)
+        workflow_contexts = []
+        request = self.session.get(f'{self.protocol}://{self.server}/{self.base_url}/contexts', headers=headers, params=params)
         if request.status_code == requests.codes.ok:
             xml_response = str(request.content.decode('utf-8'))
             entity_response = xml.etree.ElementTree.fromstring(xml_response)
@@ -95,15 +122,20 @@ class WorkflowAPI(AuthenticatedAPI):
 
     def get_workflow_contexts(self, definition: str):
         """
-        Return a list of Workflow Contexts which have the same Workflow Definition ID
+        Return a list of Workflow Contexts which have the same Workflow Definition
 
         :param definition: The Workflow Definition ID
+        :type definition: str
+
+        :return: List of Workflow Contexts
+        :rtype: list
 
         """
+
         headers = {HEADER_TOKEN: self.token}
         params = {"workflowDefinitionId": definition}
-        workflow_contexts = list()
-        request = requests.get(f'https://{self.server}/{self.base_url}/contexts', headers=headers, params=params)
+        workflow_contexts = []
+        request = self.session.get(f'{self.protocol}://{self.server}/{self.base_url}/contexts', headers=headers, params=params)
         if request.status_code == requests.codes.ok:
             xml_response = str(request.content.decode('utf-8'))
             entity_response = xml.etree.ElementTree.fromstring(xml_response)
@@ -121,17 +153,22 @@ class WorkflowAPI(AuthenticatedAPI):
             logger.error(request.content)
             raise RuntimeError(request.status_code, "get_workflow_contexts")
 
-    def start_workflow_instance(self, workflow_context, **kwargs):
+    def start_workflow_instance(self, workflow_context: WorkflowContext, **kwargs):
         """
-
         Start a workflow context
 
         Returns a Correlation Id which is used to monitor the workflow progress
 
         :param workflow_context: The workflow context to start
-        :param kwargs:           Key/Values to pass to the workflow instance
+        :type workflow_context: WorkflowContext
+
+        :param kwargs:      Key/Values to pass to the workflow instance
+
+        :return: correlation_id
+        :rtype: str
 
         """
+
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
 
         correlation_id = str(uuid.uuid4())
@@ -149,7 +186,8 @@ class WorkflowAPI(AuthenticatedAPI):
         xml.etree.ElementTree.SubElement(request_payload, "CorrelationId").text = correlation_id
 
         xml_request = xml.etree.ElementTree.tostring(request_payload, encoding='utf-8')
-        request = requests.post(f'https://{self.server}/{self.base_url}/instances', headers=headers, data=xml_request)
+        request = self.session.post(f'{self.protocol}://{self.server}/{self.base_url}/instances', headers=headers,
+                                    data=xml_request)
         if request.status_code == requests.codes.created:
             return correlation_id
         if request.status_code == requests.codes.unauthorized:
@@ -163,9 +201,11 @@ class WorkflowAPI(AuthenticatedAPI):
         """
         Terminate a workflow by its instance id
 
-        :param instance_ids: The Workflow instance:
+        :param instance_ids: The Workflow instance
+        :type instance_ids: int or a list of int
 
         """
+
         if isinstance(instance_ids, list):
             converted_list = [str(int(e)) for e in instance_ids]
             param_string = ",".join(converted_list)
@@ -174,8 +214,8 @@ class WorkflowAPI(AuthenticatedAPI):
 
         headers = {HEADER_TOKEN: self.token}
         params = {"workflowInstanceIds": param_string}
-        request = requests.post(f'https://{self.server}/{self.base_url}/instances/terminate',
-                                headers=headers, params=params)
+        request = self.session.post(f'{self.protocol}://{self.server}/{self.base_url}/instances/terminate',
+                                    headers=headers, params=params)
         if request.status_code == requests.codes.accepted:
             return
         elif request.status_code == requests.codes.unauthorized:
@@ -185,15 +225,22 @@ class WorkflowAPI(AuthenticatedAPI):
             logger.error(request.content)
             raise RuntimeError(request.status_code, "terminate_workflow_instance")
 
-    def workflow_instance(self, instance_id: int):
+    def workflow_instance(self, instance_id: int) -> WorkflowInstance:
         """
         Return a workflow instance by its Id
 
-        :param instance_id: The Workflow instance:
+        :param instance_id: The Workflow instance
+        :type instance_id: int
+
+        :return: workflow_instance
+        :rtype: WorkflowInstance
 
         """
+
         headers = {HEADER_TOKEN: self.token}
-        request = requests.get(f'https://{self.server}/{self.base_url}/instances/{str(instance_id)}', headers=headers)
+        params = {"includeErrors": "true"}
+        request = self.session.get(f'{self.protocol}://{self.server}/{self.base_url}/instances/{str(instance_id)}',
+                                   headers=headers, params=params)
         if request.status_code == requests.codes.ok:
             xml_response = str(request.content.decode('utf-8'))
             logger.debug(xml_response)
@@ -202,13 +249,13 @@ class WorkflowAPI(AuthenticatedAPI):
             assert instance_id == w_id
             workflow_instance = WorkflowInstance(int(instance_id))
             started_element = entity_response.find(f".//{{{NS_WORKFLOW}}}Started")
-            if started_element:
+            if started_element is not None:
                 if hasattr(started_element, "text"):
                     workflow_instance.started = datetime.datetime.strptime(started_element.text,
                                                                            '%Y-%m-%dT%H:%M:%S.%fZ')
 
             finished_element = entity_response.find(f".//{{{NS_WORKFLOW}}}Finished")
-            if finished_element:
+            if finished_element is not None:
                 if hasattr(finished_element, "text"):
                     workflow_instance.finished = datetime.datetime.strptime(finished_element.text,
                                                                             '%Y-%m-%dT%H:%M:%S.%fZ')
@@ -223,6 +270,8 @@ class WorkflowAPI(AuthenticatedAPI):
             workflow_instance.workflow_definition_id = entity_response.find(
                 f".//{{{NS_WORKFLOW}}}WorkflowDefinitionTextId").text
 
+            workflow_instance.xml_response = xml_response
+
             return workflow_instance
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
@@ -235,10 +284,11 @@ class WorkflowAPI(AuthenticatedAPI):
         """
         Return a list of Workflow instances
 
-        :param workflow_state: The Workflow state: Aborted, Active, Completed, Finished_Mixed_Outcome, Pending, Suspended, Unknown, or Failed
-        :param workflow_type: The Workflow type: Ingest, Access, Transformation or DataManagement
+        :param workflow_state: The Workflow state Aborted, Active, Completed, Finished_Mixed_Outcome, Pending, Suspended, Unknown, or Failed
+        :param workflow_type: The Workflow type Ingest, Access, Transformation or DataManagement
 
         """
+
         start_value = int(0)
         maximum = int(25)
         total_count = maximum
@@ -256,10 +306,12 @@ class WorkflowAPI(AuthenticatedAPI):
         """
         Return a list of Workflow instances
 
-        :param workflow_state: The Workflow state: Aborted, Active, Completed, Finished_Mixed_Outcome, Pending, Suspended, Unknown, or Failed
+        :param workflow_state: The Workflow state: Aborted, Active, Completed, Finished_Mixed_Outcome, Pending,
+        Suspended, Unknown, or Failed
         :param workflow_type: The Workflow type: Ingest, Access, Transformation or DataManagement
 
         """
+
         headers = {HEADER_TOKEN: self.token}
 
         if workflow_state not in self.workflow_states:
@@ -280,18 +332,18 @@ class WorkflowAPI(AuthenticatedAPI):
             creator = kwargs.get("creator")
             params["creator"] = creator
 
-        if "from" in kwargs:
-            from_date = kwargs.get("from")
-            params["from"] = from_date
+        if "from_date" in kwargs:
+            from_date = kwargs.get("from_date")
+            params["from"] = parse_date_to_iso(from_date)
 
-        if "to" in kwargs:
-            to_date = kwargs.get("to")
-            params["to"] = to_date
+        if "to_date" in kwargs:
+            to_date = kwargs.get("to_date")
+            params["to"] = parse_date_to_iso(to_date)
 
         params["start"] = int(start_value)
         params["max"] = int(maximum)
 
-        request = requests.get(f'https://{self.server}/{self.base_url}/instances', headers=headers, params=params)
+        request = self.session.get(f'{self.protocol}://{self.server}/{self.base_url}/instances', headers=headers, params=params)
         if request.status_code == requests.codes.ok:
             xml_response = str(request.content.decode('utf-8'))
             logger.debug(xml_response)
@@ -299,19 +351,19 @@ class WorkflowAPI(AuthenticatedAPI):
             total_count = int(entity_response.find(f".//{{{NS_WORKFLOW}}}TotalCount").text)
             count = int(entity_response.find(f".//{{{NS_WORKFLOW}}}Count").text)
             workflow_instance = entity_response.findall(f".//{{{NS_WORKFLOW}}}WorkflowInstance")
-            workflow_instances = list()
+            workflow_instances = []
             for instance in workflow_instance:
                 instance_id = instance.find(f".//{{{NS_WORKFLOW}}}Id").text
                 workflow_instance = WorkflowInstance(int(instance_id))
 
                 started_element = instance.find(f".//{{{NS_WORKFLOW}}}Started")
-                if started_element:
+                if started_element is not None:
                     if hasattr(started_element, "text"):
                         workflow_instance.started = datetime.datetime.strptime(started_element.text,
                                                                                '%Y-%m-%dT%H:%M:%S.%fZ')
 
                 finished_element = instance.find(f".//{{{NS_WORKFLOW}}}Finished")
-                if finished_element:
+                if finished_element is not None:
                     if hasattr(finished_element, "text"):
                         workflow_instance.finished = datetime.datetime.strptime(finished_element.text,
                                                                                 '%Y-%m-%dT%H:%M:%S.%fZ')