.. _permissions: ================================ :term:`Permissions ` ================================ The system supports permissions that can be granted to users directly, or more commonly by :term:`group` membership. Django permissions ----------------------- Django provides a set of built-in permissions by default for every :term:`model`: View allows the user to view objects without making changes Add allows user to create a new instance of the model Change allows user to make modification to existing model Delete allows user to delete the model (in :term:`django admin`), or :ref:`unpublish ` in :term:`dashboard`. .. seealso:: `Django default permissions `_ Custom permissions ----------------------- The project implements the following permissions in addition to those provided by django: .. list-table:: :header-rows: 1 - * Name * Code * Notes - * Can view admin dashboard * ``dashboard_widgets.view_admin_dashboard`` * - * Change document owner * ``megdocs.change_document_owner`` * Enables user to edit the "owner" field of the document - * Approve document version * ``megdocs.approve_version`` * - * Approve all document versions in institution * ``megdocs.approve_institution_versions`` * - * Allow user to export documents * ``megdocs.can_export_document`` * - * Allow user to export documents report * ``megdocs.can_export_document_report`` * - * Can edit archived document * ``megdocs.can_edit_archived_document`` * Allows user to edit documents that have been archived - * can view all forms if none selected * ``megforms.view_institution_forms`` * | Gives user access to all :term:`forms
` within their :term:`institution`, | except when they have :term:`per form permissions`, in which case user can only access | forms they were explicitly granted access to | (subject to change by :task:`26793`) - * Change auditor passwords * ``megforms.change_auditor_password`` * Whether user is allowed to change another user's password - * Change group membership * ``megforms.change_group_membership`` * - * Change auditor permissions * ``megforms.change_user_permissions`` * - * Can receive instant report emails * ``megforms.receive_instant_report_emails`` * Allows user to receive report e-mails addressed to lead auditors - * Change submission date in client app * ``megforms.change_submission_date`` * | Allows user to edit start/end dates of audit | before submission (depends on form settings) - * View credits assigned to an audit form * ``megforms.view_form_credits`` * - * Change credits assigned to an audit form * ``megforms.change_form_credits`` * - * View all form content via the API, including the pks of unpublished observations. * ``megforms.view_api_content`` * - * Can send push message * ``push_messages.send_pushmessage`` * allows user to send :term:`push messages ` | to user devices - * Can edit disabled QIP issue fields * ``qip.change_disabled_issue_fields`` * - * can view all issues * ``qip.view_institution_issues`` * Allows the :term:`issue handler` to view all :term:`issues` | within :term:`institution`, not just issues assigned to them. - * Can export issues * ``qip.export_data`` * - * Can edit read only custom issue field * ``qip.edit_readonly_customissuefield`` * - * Can change all fields, even if they're read only. * ``audit_builder.change_all_fields_customobservation`` * - * Can change confidential fields. * ``audit_builder.change_confidential_fields_customobservation`` * - * Can change a locked observation. * ``audit_builder.change_locked_customobservation`` * - * Can change approvers while observation is pending review. * ``audit_builder.change_approvers_while_pending_customobservation`` * - * Can export :term:`observations ` * ``audit_builder.export_data`` * - * Can revoke another user's :class:`~approvals.models.ObservationApproval` * ``approvals.can_revoke_other_observation_approval`` * - * Can import QIP issues * ``qip_importer.can_import_issues`` * - * Can export institutional data * ``megforms.can_export_institutional_data`` * | Allows the user to export users, wards and departments. - * Can use document AI chat * ``megforms.can_use_document_ai_chat`` * | Allows the user to use AI chat when viewing a published document version Per-form permissions ---------------------- :term:`Auditors ` can have additional permissions or ward access for certain :term:`forms `. This is implemented in :class:`~megforms.models.AuditorFormPermissions`. Permission cache ---------------------- Due to complex nature of permissions (permission group membership, form permissions) and ward access, permissions are compiled into :class:`~accounts.models.AuditorPermissionCache` :term:`model`. .. seealso:: The cache model was implemented in :task:`27900`, and is being used since task :task:`27956`. A separate instance of the model exists for each :term:`auditor` and :term:`form` combination. It aggregates total list of permissions and :term:`wards ` the user can access, including permissions and wards they inherit global access from. .. note:: Besides permissions per form, the permission cache model also contains an additional instance where form is blank. This reflects the permissions the user has globally. .. note:: **Global users**: Permissions resulting from :term:`global access ` are not represented by :class:`~accounts.models.AuditorPermissionCache`, as caching all permissions for all forms would result in a lot of computing and storage resources. Superusers are assumed to have access to everything. This usually means that user has access to the form with all its wards and permissions, but will not show up for other non-global users. Troubleshooting User Permissions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ User Permissions: The :url:`permission cache admin` page allows you to troubleshoot permissions. Although permission cache is updated automatically whenever user account changes or when user logs in, it is possible to update it manually: Using django admin Go to :url:`user profile admin ` and invoke "update form permissions" action for the selected users Using command-line tool Run :command:`./manage.py update_user_perms` to update for all users and all forms. The tool accepts various parameters that allows you to narrow down the scope of the update, or only create missing permissions:: $ ./manage.py update_perm_cache --help usage: manage.py update_perm_cache [-h] [--institution_id INSTITUTION_ID] [--user_id USER_ID] [--auditor_id AUDITOR_ID] [--create] Troubleshooting Folder Permissions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :url:`folder permission cache admin` page allows you to troubleshoot folder permissions. Although permission cache is updated automatically whenever folder structure or user permissions changes or when user logs in, it is possible to update it manually: Using django admin Go to :url:`user profile admin ` and invoke "update folder permissions" action for the selected users Using command-line tool Run :command:`./manage.py update_folder_perm_cache` to update for all users and all folders. The tool accepts various parameters that allows you to narrow down the scope of the update, or only create missing permissions:: $ ./manage.py update_folder_perm_cache --help usage: manage.py update_folder_perm_cache [-h] [--institution_id INSTITUTION_ID] [--user_id USER_ID] [--auditor_id AUDITOR_ID]