sapiopycommons 2024.7.29a300__tar.gz → 2024.8.2a301__tar.gz

{sapiopycommons-2024.7.29a300 → sapiopycommons-2024.8.2a301}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2024.7.29a300
+Version: 2024.8.2a301
 Summary: Official Sapio Python API Utilities Package
 Project-URL: Homepage, https://github.com/sapiosciences
 Author-email: Jonathan Steck <jsteck@sapiosciences.com>, Yechen Qiao <yqiao@sapiosciences.com>

{sapiopycommons-2024.7.29a300 → sapiopycommons-2024.8.2a301}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sapiopycommons"
-version='2024.07.29a300'
+version='2024.08.02a301'
 authors = [
     { name="Jonathan Steck", email="jsteck@sapiosciences.com" },
     { name="Yechen Qiao", email="yqiao@sapiosciences.com" },

{sapiopycommons-2024.7.29a300 → sapiopycommons-2024.8.2a301}/src/sapiopycommons/general/aliases.py

@@ -58,10 +58,20 @@ class AliasUtil:
         Convert a single variable that could be either an integer, DataRecord, PyRecordModel,
         or WrappedRecordModel to just an integer (taking the record ID from the record).
 
-        :return: A record id for the input record.
+        :return: A record ID for the input record.
         """
         return record if isinstance(record, int) else record.record_id
 
+    @staticmethod
+    def to_data_type_name(record: SapioRecord) -> str:
+        """
+        Convert a single variable that could be either a Data Record, PyRecordModel, or WrappedRecordModel to the
+        data type name for that record.
+
+        :return: The data type name for the input record.
+        """
+        return record.data_type_name
+
     @staticmethod
     def to_field_map_lists(records: Iterable[SapioRecord]) -> list[FieldMap]:
         """

sapiopycommons-2024.8.2a301/src/sapiopycommons/general/sapio_links.py

@@ -0,0 +1,48 @@
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+
+from sapiopycommons.general.aliases import RecordIdentifier, ExperimentIdentifier, AliasUtil
+from sapiopycommons.general.exceptions import SapioException
+
+
+class SapioNavigationLinker:
+    """
+    Given a URL to a system's webservice API (example: https://company.exemplareln.com/webservice/api), construct
+    URLs for navigation links to various locations in the system.
+    """
+    base_url: str
+
+    def __init__(self, url: str | SapioUser | SapioWebhookContext):
+        """
+        :param url: A user or context object that is being used to send requests to a Sapio system, or a URL to a
+            system's webservice API.
+        """
+        if isinstance(url, SapioWebhookContext):
+            url = url.user.url
+        elif isinstance(url, SapioUser):
+            url = url.url
+        self.base_url = url.rstrip("/").replace('webservice/api', 'veloxClient')
+
+    def data_record(self, record_identifier: RecordIdentifier, data_type_name: str | None = None) -> str:
+        """
+        :param record_identifier: An object that can be used to identify a record in the system, be that a record ID,
+            a data record, or a record model.
+        :param data_type_name: If the provided record identifier is a record ID, then the data type name of the record
+            must be provided in this parameter. Otherwise, this parameter is ignored.
+        :return: A URL for navigating to the input record.
+        """
+        record_id: int = AliasUtil.to_record_id(record_identifier)
+        if not isinstance(record_identifier, int):
+            data_type_name = AliasUtil.to_data_type_name(record_identifier)
+        if not data_type_name:
+            raise SapioException("Unable to create a data record link without a data type name. "
+                                 "Only a record ID was provided.")
+        return self.base_url + f"/#dataType={data_type_name};recordId={record_id};view=dataRecord"
+
+    def experiment(self, experiment: ExperimentIdentifier) -> str:
+        """
+        :param experiment: An object that can be used to identify an experiment in the system, be that an experiment
+            object, experiment protocol, or a notebook ID.
+        :return: A URL for navigating to the input experiment.
+        """
+        return self.base_url + f"/#notebookExperimentId={AliasUtil.to_notebook_id(experiment)};view=eln"

{sapiopycommons-2024.7.29a300 → sapiopycommons-2024.8.2a301}/src/sapiopycommons/webhook/webhook_handlers.py

@@ -4,7 +4,9 @@ from logging import Logger
 
 from sapiopylib.rest.DataMgmtService import DataMgmtServer
 from sapiopylib.rest.DataRecordManagerService import DataRecordManager
+from sapiopylib.rest.User import SapioUser
 from sapiopylib.rest.WebhookService import AbstractWebhookHandler
+from sapiopylib.rest.pojo.Message import VeloxLogMessage, VeloxLogLevel
 from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
 from sapiopylib.rest.pojo.webhook.WebhookEnums import WebhookEndpointType
 from sapiopylib.rest.pojo.webhook.WebhookResult import SapioWebhookResult
@@ -14,6 +16,7 @@ from sapiopylib.rest.utils.recordmodel.ancestry import RecordModelAncestorManage
 
 from sapiopycommons.general.exceptions import SapioUserErrorException, SapioCriticalErrorException, \
     SapioUserCancelledException
+from sapiopycommons.general.sapio_links import SapioNavigationLinker
 
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
@@ -25,6 +28,7 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
     """
     logger: Logger
 
+    user: SapioUser
     context: SapioWebhookContext
 
     dr_man: DataRecordManager
@@ -35,11 +39,13 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
     an_man: RecordModelAncestorManager
 
     def run(self, context: SapioWebhookContext) -> SapioWebhookResult:
+        self.user = context.user
         self.context = context
-        self.logger = context.user.logger
+
+        self.logger = self.user.logger
 
         self.dr_man = context.data_record_manager
-        self.rec_man = RecordModelManager(context.user)
+        self.rec_man = RecordModelManager(self.user)
         self.inst_man = self.rec_man.instance_manager
         self.rel_man = self.rec_man.relationship_manager
         self.an_man = RecordModelAncestorManager(self.rec_man)
@@ -100,7 +106,7 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
             return result
         self.log_error(traceback.format_exc())
         if self.can_send_client_callback():
-            DataMgmtServer.get_client_callback(self.context.user).display_error(e.args[0])
+            DataMgmtServer.get_client_callback(self.user).display_error(e.args[0])
         return SapioWebhookResult(False)
 
     def handle_unexpected_exception(self, e: Exception) -> SapioWebhookResult:
@@ -114,7 +120,10 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
         result: SapioWebhookResult | None = self.handle_any_exception(e)
         if result is not None:
             return result
-        self.log_error(traceback.format_exc())
+        msg: str = traceback.format_exc()
+        self.log_error(msg)
+        # FR-47079: Also log all unexpected exception messages to the webhook execution log within the platform.
+        self.log_error_to_webhook_execution_log(msg)
         return SapioWebhookResult(False, display_text="Unexpected error occurred during webhook execution. "
                                                       "Please contact Sapio support.")
 
@@ -145,32 +154,58 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
 
     def log_info(self, msg: str) -> None:
         """
-        Write an info message to the log. Log destination is stdout. This message will be prepended with the user's
-        username and the experiment ID of the experiment they are in, if any.
+        Write an info message to the webhook server log. Log destination is stdout. This message will be prepended with
+        the user's username and the experiment ID of the experiment they are in, if any.
         """
-        exp_id = None
-        if self.context.eln_experiment is not None:
-            exp_id = self.context.eln_experiment.notebook_experiment_id
-        # CR-46333: Add the user's group to the logging message.
-        user = self.context.user
-        username = user.username
-        group_name = user.session_additional_data.current_group_name
-        self.logger.info(f"(User: {username}, Group: {group_name}, Experiment: {exp_id}):\n{msg}")
+        self.logger.info(self._format_log(msg, "log_info call"))
 
     def log_error(self, msg: str) -> None:
         """
-        Write an error message to the log. Log destination is stderr. This message will be prepended with the user's
-        username and the experiment ID of the experiment they are in, if any.
+        Write an error message to the webhook server log. Log destination is stderr. This message will be prepended with
+        the user's username and the experiment ID of the experiment they are in, if any.
+        """
+        # PR-46209: Use logger.error instead of logger.info when logging errors.
+        self.logger.error(self._format_log(msg, "log_error call"))
+
+    def log_error_to_webhook_execution_log(self, msg: str) -> None:
+        """
+        Write an error message to the platform's webhook execution log. This can be reviewed by navigating to the
+        webhook configuration where the webhook that called this function is defined and clicking the "View Log"
+        button. From there, select one of the rows for the webhook executions and click "Download Log" from the right
+        side table.
+        """
+        messenger = DataMgmtServer.get_messenger(self.user)
+        messenger.log_message(VeloxLogMessage(message=self._format_log(msg, "Error occurred during webhook execution."),
+                                              log_level=VeloxLogLevel.ERROR,
+                                              originating_class=self.__class__.__name__))
+
+    def _format_log(self, msg: str, prefix: str | None = None) -> str:
+        """
+        Given a message to log, populate it with some metadata about this particular webhook execution, including
+        the group of the user and the invocation type of the webhook call.
         """
-        exp_id = None
+        # If we're able to, provide a link to the location that the error occurred at.
+        navigator = SapioNavigationLinker(self.context)
         if self.context.eln_experiment is not None:
-            exp_id = self.context.eln_experiment.notebook_experiment_id
+            link = navigator.experiment(self.context.eln_experiment)
+        elif self.context.data_record and not self.context.data_record_list:
+            link = navigator.data_record(self.context.data_record)
+        elif self.context.base_data_record:
+            link = navigator.data_record(self.context.base_data_record)
+        else:
+            link = None
+
+        message: str = ""
+        if prefix:
+            message += prefix + "\n"
+        message += f"Webhook invocation type: {self.context.end_point_type.display_name}\n"
+        message += f"Username: {self.user.username}\n"
         # CR-46333: Add the user's group to the logging message.
-        user = self.context.user
-        username = user.username
-        group_name = user.session_additional_data.current_group_name
-        # PR-46209: Use logger.error instead of logger.info when logging errors.
-        self.logger.error(f"(User: {username}, Group: {group_name}, Experiment: {exp_id}):\n{msg}")
+        message += f"User group: {self.user.session_additional_data.current_group_name}\n"
+        if link:
+            message += f"User location: {link}\n"
+        message += msg
+        return message
 
     def is_main_toolbar(self) -> bool:
         """