sapiopycommons 2024.8.28a313__py3-none-any.whl → 2024.8.28a315__py3-none-any.whl

sapiopycommons/general/audit_log.py

@@ -0,0 +1,196 @@
+from enum import Enum
+
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReportCriteria
+from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
+
+from sapiopycommons.customreport.term_builder import TermBuilder
+from sapiopycommons.general.aliases import RecordIdentifier, AliasUtil, UserIdentifier, FieldIdentifier, FieldValue
+from sapiopycommons.general.custom_report_util import CustomReportUtil
+
+EVENTTYPE_COLUMN = "EVENTTYPE"
+TIMESTAMP_COLUMN = "TIMESTAMP"
+DATATYPENAME_COLUMN = "DATATYPENAME"
+RECORDID_COLUMN = "RECORDID"
+DESCRIPTION_COLUMN = "DESCRIPTION"
+USERNAME_COLUMN = "USERNAME"
+USERCOMMENT_COLUMN = "USERCOMMENT"
+RECORDNAME_COLUMN = "RECORDNAME"
+DATAFIELDNAME_COLUMN = "DATAFIELDNAME"
+ORIGINALVALUE_COLUMN = "ORIGINALVALUE"
+NEWVALUE_COLUMN = "NEWVALUE"
+
+
+class EventType(Enum):
+    """An enum to represent the possible event type values with the event type column in the audit log table."""
+    ADD = 0
+    DELETE = 1
+    MODIFY = 2
+    INFO = 3
+    ERROR = 4
+    WARNING = 5
+    IMPORT = 6
+    GENERATE = 7
+    EXPORT = 8
+    ADDREF = 9
+    REMOVEREF = 10
+    ESIGNATURE = 11
+    ROLEASSIGNMENT = 12
+
+
+class AuditLogEntry:
+
+    __event_type: EventType
+    __date: int
+    __data_type_name: str
+    __record_id: int
+    __description: str
+    __users_login_name: str
+    __comment: str
+    __data_record_name: str
+    __data_field_name: str
+    __original_value: str
+    __new_value: str
+
+    @property
+    def event_type(self) -> EventType:
+        return self.__event_type
+
+    @property
+    def date(self) -> int:
+        return self.__date
+
+    @property
+    def data_type_name(self) -> str:
+        return self.__data_type_name
+
+    @property
+    def record_id(self) -> int:
+        return self.__record_id
+
+    @property
+    def description(self) -> str:
+        return self.__description
+
+    @property
+    def users_login_name(self) -> str:
+        return self.__users_login_name
+
+    @property
+    def comment(self) -> str:
+        return self.__comment
+
+    @property
+    def data_record_name(self) -> str:
+        return self.__data_record_name
+
+    @property
+    def data_field_name(self) -> str:
+        return self.__data_field_name
+
+    @property
+    def original_value(self) -> str:
+        return self.__original_value
+
+    @property
+    def new_value(self) -> str:
+        return self.__new_value
+
+    def __init__(self, report_row: dict[str, FieldValue]):
+        self.__event_type = EventType((report_row[EVENTTYPE_COLUMN]))
+        self.__date = report_row[TIMESTAMP_COLUMN]
+        self.__data_type_name = report_row[DATATYPENAME_COLUMN]
+        self.__record_id = report_row[RECORDID_COLUMN]
+        self.__description = report_row[DESCRIPTION_COLUMN]
+        self.__users_login_name = report_row[USERNAME_COLUMN]
+        self.__comment = report_row[USERCOMMENT_COLUMN]
+        self.__data_record_name = report_row[RECORDNAME_COLUMN]
+        self.__data_field_name = report_row[DATAFIELDNAME_COLUMN]
+        self.__original_value = report_row[ORIGINALVALUE_COLUMN]
+        self.__new_value = report_row[NEWVALUE_COLUMN]
+
+
+class AuditLog:
+    AUDIT_LOG_PSEUDO_DATATYPE: str = "AUDITLOG"
+    EVENT_TYPE: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, EVENTTYPE_COLUMN, FieldType.ENUM)
+    DATE: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, TIMESTAMP_COLUMN, FieldType.DATE)
+    DATA_TYPE_NAME: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, DATATYPENAME_COLUMN, FieldType.STRING)
+    RECORD_ID: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, RECORDID_COLUMN, FieldType.LONG)
+    DESCRIPTION: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, DESCRIPTION_COLUMN, FieldType.STRING)
+    USERS_LOGIN_NAME: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, USERNAME_COLUMN, FieldType.STRING)
+    COMMENT: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, USERCOMMENT_COLUMN, FieldType.STRING)
+    DATA_RECORD_NAME: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, RECORDNAME_COLUMN, FieldType.STRING)
+    DATA_FIELD_NAME: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, DATAFIELDNAME_COLUMN, FieldType.STRING)
+    ORIGINAL_VALUE: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, ORIGINALVALUE_COLUMN, FieldType.STRING)
+    NEW_VALUE: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, NEWVALUE_COLUMN, FieldType.STRING)
+
+    AUDIT_LOG_COLUMNS = [EVENT_TYPE, DATE, DATA_TYPE_NAME, RECORD_ID, DESCRIPTION, USERS_LOGIN_NAME, COMMENT,
+                         DATA_RECORD_NAME, DATA_FIELD_NAME, ORIGINAL_VALUE, NEW_VALUE]
+    user: SapioUser
+
+    def __init__(self, context: UserIdentifier):
+        self.user = AliasUtil.to_sapio_user(context)
+
+    @staticmethod
+    def create_data_record_audit_log_report(records: list[RecordIdentifier],
+                                            fields: list[FieldIdentifier] | None = None) -> CustomReportCriteria:
+        """
+        This method creates a CustomReportCriteria object for running an audit log query based on data records.
+
+        Creates a CustomReportCriteria object with a query term based on the record ids/records passed into the method.
+        Optionally, the fields parameter can be populated to limit the search to particular fields. If the fields
+        parameter is not populated, the search will include results for all field changes.
+
+        :param records: The DataRecords, RecordModels, or record ids to base the search on.
+        :param fields: The data field names to include changes for.
+        :return: The constructed CustomReportCriteria object, which can be used to run a report on the audit log.
+        """
+        # Build the raw report term querying for any entry with a matching record ID value to the record ID's
+        # passed in.
+        record_ids = AliasUtil.to_record_ids(records)
+        root_term = TermBuilder.is_term(AuditLog.AUDIT_LOG_PSEUDO_DATATYPE, RECORDID_COLUMN, record_ids)
+
+        # If the user passed in any specific fields, then we should limit the query to those fields.
+        if fields:
+            fields: list[str] = AliasUtil.to_data_field_names(fields)
+            field_term = TermBuilder.is_term(AuditLog.AUDIT_LOG_PSEUDO_DATATYPE, DATAFIELDNAME_COLUMN, fields)
+            root_term = TermBuilder.and_terms(root_term, field_term)
+
+        return CustomReportCriteria(AuditLog.AUDIT_LOG_COLUMNS, root_term)
+
+    def run_data_record_audit_log_report(self, records: list[RecordIdentifier],
+                                         fields: list[FieldIdentifier] | None = None) \
+            -> dict[RecordIdentifier, list[AuditLogEntry]]:
+        """
+        This method runs a custom report for changes made to the given data records using the audit log.
+        See "create_data_record_audit_log_report" for more details about the data record audit log report.
+
+        :param records: The DataRecords, RecordModels, or record ids to base the search on.
+        :param fields: The data field names to include changes for.
+        :return: A dictionary where the keys are the record identifiers passed in, and the values are a list of
+            AuditLogEntry objects which match the record id value of those records.
+        """
+        fields: list[str] = AliasUtil.to_data_field_names(fields)
+        # First, we must build our report criteria for running the Custom Report.
+        criteria = AuditLog.create_data_record_audit_log_report(records, fields)
+
+        # Then we must run the custom report using that criteria.
+        raw_report_data: list[dict[str, FieldValue]] = CustomReportUtil.run_custom_report(self.user, criteria)
+
+        # This section will prepare a map matching the original RecordIdentifier by record id.
+        # This is because the audit log entries will have record ids, but we want the keys in our result map
+        # to match the record identifiers that the user passed in, for convenience.
+        record_identifier_mapping: dict[int, RecordIdentifier] = dict()
+        for record in records:
+            record_id = AliasUtil.to_record_id(record)
+            record_identifier_mapping[record_id] = record
+
+        # Finally, we compile our audit data into a map where the keys are the record identifiers passed in,
+        # and the value is a list of applicable audit log entries.
+        final_audit_data: dict[RecordIdentifier, list[AuditLogEntry]] = dict()
+        for audit_entry_data in raw_report_data:
+            audit_entry: AuditLogEntry = AuditLogEntry(audit_entry_data)
+            identifier: RecordIdentifier = record_identifier_mapping.get(audit_entry.record_id)
+            final_audit_data.setdefault(identifier, []).append(audit_entry)
+
+        return final_audit_data

sapiopycommons/general/custom_report_util.py

@@ -1,19 +1,21 @@
 from collections.abc import Iterable
-from typing import Any
 
 from sapiopylib.rest.DataMgmtService import DataMgmtServer
 from sapiopylib.rest.User import SapioUser
-from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReport
-from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReport, CustomReportCriteria, RawReportTerm
+
+from sapiopycommons.general.aliases import UserIdentifier, FieldValue, AliasUtil, FieldIdentifierKey
 
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
 class CustomReportUtil:
     @staticmethod
-    def run_system_report(context: SapioWebhookContext | SapioUser,
+    def run_system_report(context: UserIdentifier,
                           report_name: str,
-                          filters: dict[str, Iterable[Any]] | None = None,
-                          page_limit: int | None = None) -> list[dict[str, Any]]:
+                          filters: dict[FieldIdentifierKey, Iterable[FieldValue]] | None = None,
+                          page_limit: int | None = None,
+                          page_size: int | None = None,
+                          page_number: int | None = None) -> list[dict[str, FieldValue]]:
         """
         Run a system report and return the results of that report as a list of dictionaries for the values of each
         column in each row.
@@ -27,29 +29,97 @@ class CustomReportUtil:
             filter on. Only those headers that both the filters and the custom report share will take effect. That is,
             any filters that have a header name that isn't in the custom report will be ignored.
         :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
+        :param page_size: The size of each page of results in the search. If None, the page size is set by the server.
+        :param page_number: The page number to start the search from, If None, starts on the first page.
         :return: The results of the report listed row by row, mapping each cell to the header it is under. The header
             values in the dicts are the data field names of the columns.
+            If two columns in the search have the same data field name but differing data type names, then the
+            dictionary key to the value in the column will be "DataTypeName.DataFieldName". For example, if you
+            had a Sample column with a data field name of Identifier and a Request column with the same data field name,
+            then the dictionary keys for these columns would be Sample.Identifier and Request.Identifier respectively.
         """
-        results = CustomReportUtil.__exhaust_system_report(context, report_name, page_limit)
+        results: tuple = CustomReportUtil.__exhaust_system_report(context, report_name, page_limit,
+                                                                  page_size, page_number)
         columns: list[ReportColumn] = results[0]
-        rows: list[list[Any]] = results[1]
+        rows: list[list[FieldValue]] = results[1]
+        return CustomReportUtil.__process_results(rows, columns, filters)
 
-        ret: list[dict[str, Any]] = []
-        for row in rows:
-            row_data: dict[str, Any] = {}
-            filter_row: bool = False
-            for value, column in zip(row, columns):
-                header: str = column.data_field_name
-                if filters is not None and header in filters and value not in filters.get(header):
-                    filter_row = True
-                    break
-                row_data.update({header: value})
-            if filter_row is False:
-                ret.append(row_data)
-        return ret
+    @staticmethod
+    def run_custom_report(context: UserIdentifier,
+                          report_criteria: CustomReportCriteria,
+                          filters: dict[FieldIdentifierKey, Iterable[FieldValue]] | None = None,
+                          page_limit: int | None = None,
+                          page_size: int | None = None,
+                          page_number: int | None = None) -> list[dict[str, FieldValue]]:
+        """
+        Run a custom report and return the results of that report as a list of dictionaries for the values of each
+        column in each row.
+
+        Custom reports are constructed by the caller, specifying the report terms and the columns that will be in the
+        results. They are like advanced or predefined searches from the system, except they are constructed from
+        within the webhook instead of from within the system.
+
+        :param context: The current webhook context or a user object to send requests from.
+        :param report_criteria: The custom report criteria to run.
+        :param filters: If provided, filter the results of the report using the given mapping of headers to values to
+            filter on. Only those headers that both the filters and the custom report share will take effect. That is,
+            any filters that have a header name that isn't in the custom report will be ignored.
+            Note that this parameter is only provided for parity with the other run report functions. If you need to
+            filter the results of a search, it would likely be more beneficial to have just added a new term to the
+            input report criteria that corresponds to the filter.
+        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
+        :param page_size: The size of each page of results in the search. If None, uses the value from the given report
+            criteria. If not None, overwrites the value from the given report criteria.
+        :param page_number: The page number to start the search from, If None, uses the value from the given report
+            criteria. If not None, overwrites the value from the given report criteria.
+        :return: The results of the report listed row by row, mapping each cell to the header it is under. The header
+            values in the dicts are the data field names of the columns.
+            If two columns in the search have the same data field name but differing data type names, then the
+            dictionary key to the value in the column will be "DataTypeName.DataFieldName". For example, if you
+            had a Sample column with a data field name of Identifier and a Request column with the same data field name,
+            then the dictionary keys for these columns would be Sample.Identifier and Request.Identifier respectively.
+        """
+        results: tuple = CustomReportUtil.__exhaust_custom_report(context, report_criteria, page_limit,
+                                                                  page_size, page_number)
+        columns: list[ReportColumn] = results[0]
+        rows: list[list[FieldValue]] = results[1]
+        return CustomReportUtil.__process_results(rows, columns, filters)
 
     @staticmethod
-    def get_system_report_criteria(context: SapioWebhookContext | SapioUser, report_name: str) -> CustomReport:
+    def run_quick_report(context: UserIdentifier,
+                         report_term: RawReportTerm,
+                         filters: dict[FieldIdentifierKey, Iterable[FieldValue]] | None = None,
+                         page_limit: int | None = None,
+                         page_size: int | None = None,
+                         page_number: int | None = None) -> list[dict[str, FieldValue]]:
+        """
+        Run a quick report and return the results of that report as a list of dictionaries for the values of each
+        column in each row.
+
+        Quick reports are helpful for cases where you need to query record field values in a more complex manner than
+        the data record manager allows, but still simpler than a full-blown custom report. The columns that are returned
+        in a quick search are every visible field from the data type that corresponds to the given report term. (Fields
+        which are not marked as visible in the data designer will be excluded.)
+
+        :param context: The current webhook context or a user object to send requests from.
+        :param report_term: The raw report term to use for the quick report.
+        :param filters: If provided, filter the results of the report using the given mapping of headers to values to
+            filter on. Only those headers that both the filters and the custom report share will take effect. That is,
+            any filters that have a header name that isn't in the custom report will be ignored.
+        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
+        :param page_size: The size of each page of results in the search. If None, the page size is set by the server.
+        :param page_number: The page number to start the search from, If None, starts on the first page.
+        :return: The results of the report listed row by row, mapping each cell to the header it is under. The header
+            values in the dicts are the data field names of the columns.
+        """
+        results: tuple = CustomReportUtil.__exhaust_quick_report(context, report_term, page_limit,
+                                                                 page_size, page_number)
+        columns: list[ReportColumn] = results[0]
+        rows: list[list[FieldValue]] = results[1]
+        return CustomReportUtil.__process_results(rows, columns, filters)
+
+    @staticmethod
+    def get_system_report_criteria(context: UserIdentifier, report_name: str) -> CustomReport:
         """
         Retrieve a custom report from the system given the name of the report. This works by querying the system report
         with a page number and size of 1 to minimize the amount of data transfer needed to retrieve the report's config.
@@ -64,27 +134,131 @@ class CustomReportUtil:
         :param report_name: The name of the system report to run.
         :return: The CustomReport object for the given system report name.
         """
-        user: SapioUser = context if isinstance(context, SapioUser) else context.user
+        user: SapioUser = AliasUtil.to_sapio_user(context)
         report_man = DataMgmtServer.get_custom_report_manager(user)
         return report_man.run_system_report_by_name(report_name, 1, 1)
 
     @staticmethod
-    def __exhaust_system_report(context: SapioWebhookContext | SapioUser, report_name: str, page_limit: int | None = None) \
-            -> tuple[list[ReportColumn], list[list[Any]]]:
-        user: SapioUser = context if isinstance(context, SapioUser) else context.user
+    def __exhaust_system_report(context: UserIdentifier,
+                                report_name: str,
+                                page_limit: int | None,
+                                page_size: int | None,
+                                page_number: int | None) \
+            -> tuple[list[ReportColumn], list[list[FieldValue]]]:
+        """
+        Given a system report, iterate over every page of the report and collect the results
+        until there are no remaining pages.
+        """
+        user: SapioUser = AliasUtil.to_sapio_user(context)
+        report_man = DataMgmtServer.get_custom_report_manager(user)
+
+        result = None
+        has_next_page: bool = True
+        rows: list[list[FieldValue]] = []
+        cur_page: int = 1
+        while has_next_page and (not page_limit or cur_page <= page_limit):
+            result = report_man.run_system_report_by_name(report_name, page_size, page_number)
+            page_size = result.page_size
+            page_number = result.page_number
+            has_next_page = result.has_next_page
+            rows.extend(result.result_table)
+            cur_page += 1
+        return result.column_list, rows
+
+    @staticmethod
+    def __exhaust_custom_report(context: UserIdentifier,
+                                report: CustomReportCriteria,
+                                page_limit: int | None,
+                                page_size: int | None,
+                                page_number: int | None) \
+            -> tuple[list[ReportColumn], list[list[FieldValue]]]:
+        """
+        Given a custom report, iterate over every page of the report and collect the results
+        until there are no remaining pages.
+        """
+        user: SapioUser = AliasUtil.to_sapio_user(context)
         report_man = DataMgmtServer.get_custom_report_manager(user)
 
-        report = None
-        page_size: int | None = None
-        page_number: int | None = None
+        result = None
+        if page_size is not None:
+            report.page_size = page_size
+        if page_number is not None:
+            report.page_number = page_number
         has_next_page: bool = True
-        rows: list[list[Any]] = []
+        rows: list[list[FieldValue]] = []
         cur_page: int = 1
-        while has_next_page and (not page_limit or cur_page < page_limit):
-            report = report_man.run_system_report_by_name(report_name, page_size, page_number)
-            page_size = report.page_size
-            page_number = report.page_number
-            has_next_page = report.has_next_page
-            rows.extend(report.result_table)
+        while has_next_page and (not page_limit or cur_page <= page_limit):
+            result = report_man.run_custom_report(report)
+            report.page_size = result.page_size
+            report.page_number = result.page_number
+            has_next_page = result.has_next_page
+            rows.extend(result.result_table)
             cur_page += 1
-        return report.column_list, rows
+        return result.column_list, rows
+
+    @staticmethod
+    def __exhaust_quick_report(context: UserIdentifier,
+                               report_term: RawReportTerm,
+                               page_limit: int | None,
+                               page_size: int | None,
+                               page_number: int | None) \
+            -> tuple[list[ReportColumn], list[list[FieldValue]]]:
+        """
+        Given a quick report, iterate over every page of the report and collect the results
+        until there are no remaining pages.
+        """
+        user: SapioUser = AliasUtil.to_sapio_user(context)
+        report_man = DataMgmtServer.get_custom_report_manager(user)
+
+        result = None
+        has_next_page: bool = True
+        rows: list[list[FieldValue]] = []
+        cur_page: int = 1
+        while has_next_page and (not page_limit or cur_page <= page_limit):
+            result = report_man.run_quick_report(report_term, page_size, page_number)
+            page_size = result.page_size
+            page_number = result.page_number
+            has_next_page = result.has_next_page
+            rows.extend(result.result_table)
+            cur_page += 1
+        return result.column_list, rows
+
+    @staticmethod
+    def __process_results(rows: list[list[FieldValue]], columns: list[ReportColumn],
+                          filters: dict[FieldIdentifierKey, Iterable[FieldValue]] | None) -> list[dict[str, FieldValue]]:
+        """
+        Given the results of a report as a list of row values and the report's columns, combine these lists to
+        result in a singular list of dictionaries for each row in the results.
+
+        If any filter criteria has been provided, also use that to filter the row.
+        """
+        # It may be the case that two columns have the same data field name but differing data type names.
+        # If this occurs, then we need to be able to differentiate these columns in the resulting dictionary.
+        prepend_dt: set[str] = set()
+        encountered_names: list[str] = []
+        for column in columns:
+            field_name: str = column.data_field_name
+            if field_name in encountered_names:
+                prepend_dt.add(field_name)
+            else:
+                encountered_names.append(field_name)
+
+        filters: dict[str, Iterable[FieldValue]] = AliasUtil.to_data_field_names_dict(filters)
+
+        ret: list[dict[str, FieldValue]] = []
+        for row in rows:
+            row_data: dict[str, FieldValue] = {}
+            filter_row: bool = False
+            for value, column in zip(row, columns):
+                header: str = column.data_field_name
+                # If two columns share the same data field name, prepend the data type name of the column to the
+                # data field name.
+                if header in prepend_dt:
+                    header = column.data_type_name + "." + header
+                if filters is not None and header in filters and value not in filters.get(header):
+                    filter_row = True
+                    break
+                row_data.update({header: value})
+            if filter_row is False:
+                ret.append(row_data)
+        return ret

sapiopycommons/general/popup_util.py

@@ -1,3 +1,5 @@
+import warnings
+
 from sapiopylib.rest.DataMgmtService import DataMgmtServer
 from sapiopylib.rest.pojo.datatype.DataType import DataTypeDefinition
 from sapiopylib.rest.pojo.datatype.FieldDefinition import VeloxStringFieldDefinition, AbstractVeloxFieldDefinition, \
@@ -51,6 +53,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if display_name is None:
             display_name = data_type
         if plural_display_name is None:
@@ -97,6 +100,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         # Get the field definitions of the data type.
         data_type: str = record.data_type_name
         type_man = DataMgmtServer.get_data_type_manager(context.user)
@@ -155,6 +159,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if max_length is None:
             max_length = len(default_value) if default_value else 100
         string_field = VeloxStringFieldDefinition(data_type, field_name, field_name, default_value=default_value,
@@ -191,6 +196,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if default_value is None:
             default_value = max(0, min_value)
         integer_field = VeloxIntegerFieldDefinition(data_type, field_name, field_name, default_value=default_value,
@@ -229,6 +235,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if default_value is None:
             default_value = min_value
         double_field = VeloxDoubleFieldDefinition(data_type, field_name, field_name, default_value=default_value,
@@ -260,6 +267,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if display_name is None:
             display_name = data_type
         if plural_display_name is None:
@@ -295,6 +303,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         data_types: set[str] = {x.data_type_name for x in records}
         if len(data_types) > 1:
             raise SapioException("Multiple data type names encountered in records list for record table popup.")
@@ -347,6 +356,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         data_types: set[str] = {x.data_type_name for x in records}
         if len(data_types) > 1:
             raise SapioException("Multiple data type names encountered in records list for record table popup.")
@@ -391,6 +401,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         callback = ListDialogRequest(title, multi_select, options,
                                      callback_context_data=request_context)
         return SapioWebhookResult(True, client_callback_request=callback)
@@ -415,6 +426,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         callback = OptionDialogRequest(title, msg, options, default_option, user_can_cancel,
                                        callback_context_data=request_context)
         return SapioWebhookResult(True, client_callback_request=callback)
@@ -437,6 +449,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.option_popup(title, msg, ["OK"], 0, user_can_cancel, request_context=request_context)
 
     @staticmethod
@@ -458,6 +471,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.option_popup(title, msg, ["Yes", "No"], 0 if default_yes else 1, user_can_cancel,
                                       request_context=request_context)
 
@@ -470,6 +484,7 @@ class PopupUtil:
 
         Deprecated for PopupUtil.text_field_popup.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.string_field_popup(title, "", field_name, msg, len(msg), False, data_type,
                                             request_context=request_context, auto_size=True)
 
@@ -481,6 +496,7 @@ class PopupUtil:
 
         Deprecated for PopupUtil.option_popup.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.option_popup(title, msg, options, 0, user_can_cancel, request_context=request_context)
 
     @staticmethod
@@ -490,4 +506,5 @@ class PopupUtil:
 
         Deprecated for PopupUtil.ok_popup.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.ok_popup(title, msg, False, request_context=request_context)

sapiopycommons/general/sapio_links.py

@@ -0,0 +1,50 @@
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+
+from sapiopycommons.general.aliases import RecordIdentifier, ExperimentIdentifier, AliasUtil, DataTypeIdentifier
+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: DataTypeIdentifier | 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 data_type_name:
+            data_type_name = AliasUtil.to_data_type_name(data_type_name)
+        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"