.. _ringfencing:

==================
Ringfencing
==================
Ring-fencing refers to ability to limit what items user can see in the system.

.. uml:: ringfencing.puml

Ward ringfencing
------------------
User profile can be limited to a subset of wards in the their institution.
If user profile has ``wards``, it means the user is limited to accessing data associated with those wards only.
By default, user has access to all wards in the institution.

.. note::
    User access to wards can also be limited per form by overriding user :term:`form permissions <per form permissions>`.

.. warning::
    There are exceptions to the above ringfencing rules:

    form setting:
      A form can override ringfencing and give user read-only access to observations within that form.
      This is controlled by setting :attr:`advanced ward ringfencing <megforms.models.AuditFormConfig>` form configuration to "Allow user to view data, but not edit".

      Users can also submit data to wards outside their ring-fencing if :attr:`~megforms.models.AuditFormConfig.enable_submission_for_all_wards` is enabled.
    model field:
      In forms having a model field relation to Auditor (user profile) model,
      user can view observations where they are selected as a choice,
      including multichoice model fields.

User ringfencing
-----------------
Typically :term:`users<user profile>` can see other users within their :term:`institution` or institutions (group level users).
User's visibility of other users on the system (even in the same :term:`institution`) is further ring-fenced based on what
:term:`forms<audit form>` users have access to.

Currently the two users must have access to the same forms in order to see each other's account on the system.
These rules are implemented in :meth:`megforms.models.AuditorQueryset.for_auditor`.

.. note:: users who don't have access to any forms are visible to all other users, but they themselves can only see only users who also don't have access to any forms.

.. seealso::
    Ring-fencing by :term:`audit form` was implemented in :task:`22498`.
    The ring-fencing rules may change in the future. Please see :task:`25706` for more up to date details and discussion.


Observation ringfencing
------------------------
Access for a :term:`audit form` observations can be ringfenced by adding or updating existing
:class:`~megforms.models.AuditorFormPermissions` record for required :term:`users<user profile>` and :term:`audit form`
then setting up `filters` field with required filters based on existing `CustomField`.

.. code-block:: json

    {
        "test_select": "A",
        "test_select2": ["B"],
        "test_multiselect": ["A", "B"],
        "test_auditor": "{auditor.id}"
    }

A `ObservationQueryset` can be directly ringfenced using `ObservationQueryset.for_form_auditor` and `ObservationQueryset.for_forms_auditor`
methods by providing the :term:`audit form` and :term:`auditor` arguments.

.. note:: Filters for any field can be either a single value `"A"` or multiple values ["A", "B"],
    for single choice fields filters would be "exact" and "in" for array values, for multiple choice fields filters would also be "in".


Model dropdown override
------------------------
If a user model dropdown or a team model dropdown is added to the form, users selected in this dropdown will have access to the observation.
This overrides the following:

* ward ringfencing
* observation ringfencing


Combining all of the above
---------------------------
| The list observations visible to a user is equal to all of the observations in the wards they have access to.
| If they have any observation ringfencing applied then that list is further limited based on the filters of the observation ringfencing.
| Added to this list are the observations where they're selected in a model dropdown, which overrides the previous ringfencing rules.