.. _levels:

==============================
Group & Institution levels
==============================

Some :term:`institutions <institution>` are a part of a :term:`institution group`.
To enable managing those institutions, and sharing content and users, the system allows some items to be :term:`group level`.

This generally means that the item belongs to the group rather than individual institution.
The group it belongs to is determined by it's :attr:`institution` field - the immediate group the institution belongs to, is the group the item belongs to.

.. uml::
    :caption: Example institution and group layout showing two groups and one standalone institution (without group)

    @startuml
    namespace Group1 {
        interface "Institution 1" {
            - form **1**
            - user **1**
            + group form **G11**
            + group user **G11**
        }
        interface "Institution 2" {
            - form **2**
            - user **2**
        }
    }
    namespace Group2 {
        interface "Institution 3" {
            - form **3**
            - user **3**
            + group form **G21**
            + group user **G21**
        }
        interface "Institution 4" {
            - form **4**
            - user **4**
        }
    }
    interface "Institution 5" {
        - form **5**
        + user **55**
        + global user **G55**
    }
    @enduml

User levels
============
A group level :term:`auditor` has access to all :term:`institutions <institution>` within their group.
Their institution relation is used to determine the account's default locale (language), timezone and password policy.

A group user's access to individual institutions within their group can be limited by setting :attr:`~megforms.models.Auditor.restricted_institutions` field.

.. seealso:: See how data within institutions and groups are ringfenced in :ref:`ringfencing`.

Global users
-------------------
The implementation team has global access to all institutions. This gives them access to all institutions in the :term:`region`.

This is a special level that works only one way - the users can see and access forms, documents, and observations,
but do not appear as users in Settings interface, or in any user dropdowns within those institutions.

A user can only be global if they are a part of the ```meg-staff`` institution and have an email address from the ``megit.com`` domain.
If somehow a user is assigned the global level and doesn't meet these criteria, they will be blocked from signing in.
For more information see :envvar:`GLOBAL_INSTITUTION_SLUG`.

Form levels
============
Group level :term:`forms <audit form>` are available in all institutions within the group.

Institution level users can access group level forms in the context of their own institution.
This means they can submit that form only to their own institution, and view :term:`observations <observation>` submitted using the form to their own institution only.
Similarly Group level users whose :attr:`~megforms.models.Auditor.restricted_institutions` excludes form's institution can also access the form.

.. note:: Institution-level users are restricted from editing group-level forms as per :task:`22838`

QIP configurations
====================
Group level :class:`~qip.models.QipConfig` objects are available to all institutions within the group.
They can be set as the config in any of the forms within those institutions, both group and institution level forms.

.. _document_folder_levels:

Document & folder levels
==========================
Both :term:`documents <document>` and :term:`folders <folder>` can be group level.

Group level documents can belong to institution-level folders,
however they will not be visible to users who don't have access to the folder, effectively making the document institution-level.

Institution level documents are inaccessible outside of their institution even if placed in a group-level folder.

.. seealso:: More details in :ref:`megdocs_ringfencing`

Team levels
============
Group level teams allow users from multiple institutions within the :term:`institution group` belong to the same team.

Institution-level teams can be joined by both institution and group-level users.

Tag Groups
===========
Group level :class:`~tag_groups.models.TagGroup` objects make the tags available to forms in all institutions within the group.

SSO identity provider level
============================
:term:`Identity providers <Identity provider>` (:term:`SAML`) for :term:`SSO` can be set-up on institution and group level.
A group level identity provider allows all users within the :term:`institution group` to authenticate against the same Active Directory (or other provider).

.. note::
    All new user accounts created via SAML will be associated with whatever :term:`institution` is set in :attr:`~external_auth.models.SamlIdentityProvider.institution`.
    To avoid this, the accounts can be pre-emptively created in the desired institution.

.. seealso:: More about SAML in :ref:`SSO` documentation

Security Policy
================
Group level :class:`~accounts.models.PasswordPolicy` objects make the security policy available to users in all institutions within the group.
You can use the `policy level` field to configure this.
Not to be confused with the `user level` field, which is used to determine the level of users that a security policy will apply to.

Report Rule
============
A report rule can be :term:`institution` or :term:`group level`.
Institution level rules can only send notifications that are relevant to locations from the institution of the report rule.
Group level rules can send notifications that are relevant to locations and forms from across the institution group.