sapiopycommons 2024.3.18a156__py3-none-any.whl → 2025.1.17a402__py3-none-any.whl

sapiopycommons/general/audit_log.py

@@ -0,0 +1,185 @@
+from enum import Enum
+
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReportCriteria
+
+from sapiopycommons.customreport.column_builder import ColumnBuilder
+from sapiopycommons.customreport.term_builder import TermBuilder
+from sapiopycommons.datatype.pseudo_data_types import AuditLogPseudoDef
+from sapiopycommons.general.aliases import RecordIdentifier, AliasUtil, UserIdentifier, FieldIdentifier, FieldValue
+from sapiopycommons.general.custom_report_util import CustomReportUtil
+
+
+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[AuditLogPseudoDef.EVENT_TYPE__FIELD_NAME.field_name]))
+        self.__date = report_row[AuditLogPseudoDef.TIME_STAMP__FIELD_NAME.field_name]
+        self.__data_type_name = report_row[AuditLogPseudoDef.DATA_TYPE_NAME__FIELD_NAME.field_name]
+        self.__record_id = report_row[AuditLogPseudoDef.RECORD_ID__FIELD_NAME.field_name]
+        self.__description = report_row[AuditLogPseudoDef.DESCRIPTION__FIELD_NAME.field_name]
+        self.__users_login_name = report_row[AuditLogPseudoDef.USER_NAME__FIELD_NAME.field_name]
+        self.__comment = report_row[AuditLogPseudoDef.USER_COMMENT__FIELD_NAME.field_name]
+        self.__data_record_name = report_row[AuditLogPseudoDef.RECORD_NAME__FIELD_NAME.field_name]
+        self.__data_field_name = report_row[AuditLogPseudoDef.DATA_FIELD_NAME__FIELD_NAME.field_name]
+        self.__original_value = report_row[AuditLogPseudoDef.ORIGINAL_VALUE__FIELD_NAME.field_name]
+        self.__new_value = report_row[AuditLogPseudoDef.NEW_VALUE__FIELD_NAME.field_name]
+
+
+class AuditLogUtil:
+    user: SapioUser
+
+    def __init__(self, context: UserIdentifier):
+        self.user = AliasUtil.to_sapio_user(context)
+
+    @staticmethod
+    def report_columns() -> list[ReportColumn]:
+        return [
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.EVENT_TYPE__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.TIME_STAMP__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.DATA_TYPE_NAME__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.RECORD_ID__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.DESCRIPTION__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.USER_NAME__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.USER_COMMENT__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.RECORD_NAME__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.DATA_FIELD_NAME__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.ORIGINAL_VALUE__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.NEW_VALUE__FIELD_NAME)
+        ]
+
+    @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)
+        tb = TermBuilder(AuditLogPseudoDef.DATA_TYPE_NAME)
+        root_term = tb.is_term(AuditLogPseudoDef.RECORD_ID__FIELD_NAME, record_ids)
+
+        # If the user passed in any specific fields, then we should limit the query to those fields.
+        if fields is not None and fields:
+            fields: list[str] = AliasUtil.to_data_field_names(fields)
+            field_term = tb.is_term(AuditLogPseudoDef.DATA_FIELD_NAME__FIELD_NAME, fields)
+            root_term = TermBuilder.and_terms(root_term, field_term)
+
+        return CustomReportCriteria(AuditLogUtil.report_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.
+        """
+        # First, we must build our report criteria for running the Custom Report.
+        criteria = AuditLogUtil.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,40 +1,281 @@
 from collections.abc import Iterable
-from typing import Any
 
 from sapiopylib.rest.DataMgmtService import DataMgmtServer
-from sapiopylib.rest.pojo.CustomReport import ReportColumn
-from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+from sapiopylib.rest.User import SapioUser
+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,
+    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.
-        :param context: The current webhook context.
+
+        System reports are also known as predefined searches in the system and must be defined in the data designer for
+        a specific data type. That is, saved searches created by users cannot be run using this function.
+
+        :param context: The current webhook context or a user object to send requests from.
         :param report_name: The name of the system report 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.
         :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,
+            which may be unlimited.
+        :param page_number: The page number to start the search from, If None, starts on the first page. Note that the
+            number of the first page is 0.
+        :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_system_report(context, report_name, 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 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. Note that the number of the
+            first page is 0.
         :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_custom_report(context, report_criteria, 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)
+
+    @staticmethod
+    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,
+            which may be unlimited.
+        :param page_number: The page number to start the search from, If None, starts on the first page. Note that the
+            number of the first page is 0.
+        :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.
+
+        System reports are also known as predefined searches in the system and must be defined in the data designer for
+        a specific data type. That is, saved searches created by users cannot be run using this function.
+
+        Using this, you can add to the root term of the search to then run a new search, or provide it to client
+        callbacks or directives that take CustomReports.
+
+        :param context: The current webhook context or a user object to send requests from.
+        :param report_name: The name of the system report to run.
+        :return: The CustomReport object for the given system report name.
+        """
+        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, 0)
 
-        ret: list[dict[str, Any]] = []
+    @staticmethod
+    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)
+
+        # If a page size was provided but no page number was provided, then set the page number to 0,
+        # as both parameters are necessary in order to get paged results.
+        if page_size is not None and page_number is None:
+            page_number = 0
+
+        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 + 1
+            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)
+
+        # If a page size was provided but no page number was provided, then set the page number to 0,
+        # as both parameters are necessary in order to get paged results.
+        if page_size is not None and page_number is None:
+            page_number = 0
+
+        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[FieldValue]] = []
+        cur_page: int = 1
+        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 + 1
+            has_next_page = result.has_next_page
+            rows.extend(result.result_table)
+            cur_page += 1
+        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)
+
+        # If a page size was provided but no page number was provided, then set the page number to 0,
+        # as both parameters are necessary in order to get paged results.
+        if page_size is not None and page_number is None:
+            page_number = 0
+
+        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 + 1
+            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)
+
+        if filters:
+            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, Any] = {}
+            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
@@ -42,23 +283,3 @@ class CustomReportUtil:
             if filter_row is False:
                 ret.append(row_data)
         return ret
-
-    @staticmethod
-    def __exhaust_system_report(context: SapioWebhookContext, report_name: str, page_limit: int | None = None) \
-            -> tuple[list[ReportColumn], list[list[Any]]]:
-        report_man = DataMgmtServer.get_custom_report_manager(context.user)
-
-        report = None
-        page_size: int | None = None
-        page_number: int | None = None
-        has_next_page: bool = True
-        rows: list[list[Any]] = []
-        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)
-            cur_page += 1
-        return report.column_list, rows

sapiopycommons/general/directive_util.py

@@ -0,0 +1,86 @@
+from typing import Iterable, cast
+
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.CustomReport import CustomReportCriteria, CustomReport
+from sapiopylib.rest.pojo.webhook.WebhookDirective import HomePageDirective, FormDirective, TableDirective, \
+    CustomReportDirective, ElnExperimentDirective, ExperimentEntryDirective
+
+from sapiopycommons.general.aliases import SapioRecord, AliasUtil, ExperimentIdentifier, ExperimentEntryIdentifier, \
+    UserIdentifier
+from sapiopycommons.general.custom_report_util import CustomReportUtil
+
+
+# FR-47392: Create a DirectiveUtil class to simplify the creation of directives.
+class DirectiveUtil:
+    """
+    DirectiveUtil is a class for creating webhook directives. The utility functions reduce the provided variables
+    down to the exact type that the directives require, removing the need for the caller to handle the conversion.
+    """
+    user: SapioUser
+
+    def __init__(self, context: UserIdentifier):
+        """
+        :param context: The current webhook context or a user object to send requests from.
+        """
+        self.user = AliasUtil.to_sapio_user(context)
+
+    @staticmethod
+    def homepage() -> HomePageDirective:
+        """
+        :return: A directive that sends the user back to their home page.
+        """
+        return HomePageDirective()
+
+    @staticmethod
+    def record_form(record: SapioRecord) -> FormDirective:
+        """
+        :param record: A record in the system.
+        :return: A directive that sends the user to a specific data record form.
+        """
+        return FormDirective(AliasUtil.to_data_record(record))
+
+    @staticmethod
+    def record_table(records: Iterable[SapioRecord]) -> TableDirective:
+        """
+        :param records: A list of records in the system.
+        :return: A directive that sends the user to a table of data records.
+        """
+        return TableDirective(AliasUtil.to_data_records(records))
+
+    @staticmethod
+    def record_adaptive(records: Iterable[SapioRecord]) -> TableDirective | FormDirective:
+        """
+        :param records: A list of records in the system.
+        :return: A directive that sends the user to a table of data records if there are multiple records,
+            or a directive that sends the user to a specific data record form if there is only one record.
+        """
+        records: list[SapioRecord] = list(records)
+        if len(records) == 1:
+            return DirectiveUtil.record_form(records[0])
+        return DirectiveUtil.record_table(records)
+
+    def custom_report(self, report: CustomReport | CustomReportCriteria | str) -> CustomReportDirective:
+        """
+        :param report: A custom report, the criteria for a custom report, or the name of a system report.
+        :return: A directive that sends the user to the results of the provided custom report.
+        """
+        if isinstance(report, str):
+            report: CustomReport = CustomReportUtil.get_system_report_criteria(self.user, report)
+        return CustomReportDirective(cast(CustomReport, report))
+
+    @staticmethod
+    def eln_experiment(experiment: ExperimentIdentifier) -> ElnExperimentDirective:
+        """
+        :param experiment: An identifier for an experiment.
+        :return: A directive that sends the user to the ELN experiment.
+        """
+        return ElnExperimentDirective(AliasUtil.to_notebook_id(experiment))
+
+    @staticmethod
+    def eln_entry(experiment: ExperimentIdentifier, entry: ExperimentEntryIdentifier) -> ExperimentEntryDirective:
+        """
+        :param experiment: An identifier for an experiment.
+        :param entry: An identifier for an entry in the experiment.
+        :return: A directive that sends the user to the provided experiment entry within its ELN experiment.
+        """
+        return ExperimentEntryDirective(AliasUtil.to_notebook_id(experiment), AliasUtil.to_entry_id(entry))