Dashboard Viewers
=================

Manage the mapping of dashboards to viewers.

Linked From:
  * :doc:`root`

.. hint::

   If you're looking to fetch viewers of a dashboard,
   try our v2 API, :doc:`../v2/dashboard_viewers`

PUT or PATCH
------------

The ``PUT`` method is used to upload a file of mappings
that should replace all of the mappings that already exist.
The ``PATCH`` method is used to upload a file of mappings
that should augment the mappings that already exist.

.. warning::

  Please be aware that using the ``PUT`` method may conflict
  with dashboard changes made through the Dropout Detective/Grade Guardian web application.
  It is recommended to communicate with the designated access managers of Dropout Detective
  so they know which dashboards can be edited through the web interface and which will
  be managed through the API integration.

A 200 response is returned if the upload was successfully processed.
The mappings will be saved even if there are viewers missing.
The response will contain details outlining any missing viewers.


Accepted Request Content-Types:
  ``text/csv``, ``application/json``

  Note: Be sure to include the encoding using the ``charset``
  content type parameter, so that we can properly interpret
  your upload. We highly recommend using ``utf-8`` if possible.
Available Response Content-Types:
  ``application/json``


Example Request
~~~~~~~~~~~~~~~

URL:
  ``/detective/api/dashboard/viewer/``

Content-Type:
  ``text/csv``

.. code-block:: text

    dashboard_name,viewer_id,viewer_sis_id,viewer_is_ally
    Football,2,,
    Football,,4,True
    Football,,6,False
    Badminton,8,,True

URL:
  ``/detective/api/dashboard/viewer/``

Content-Type:
  ``application/json``

.. code-block:: json

    [
      {"dashboard_name": "Football", "viewer_id": "2"},
      {"dashboard_name": "Football", "viewer_sis_id": "4", "viewer_is_ally": true},
      {"dashboard_name": "Football", "viewer_sis_id": "6", "viewer_is_ally": false},
      {"dashboard_name": "Badminton", "viewer_id": "8", "viewer_is_ally": true}
    ]

Example Success Response
~~~~~~~~~~~~~~~~~~~~~~~~

URL:
  ``/detective/api/dashboard/viewer/``
Status:
  200 OK Request
Content-Type:
  ``application/json``

.. code-block:: json

    {
      "detail": "Some viewers could not be found.",
      "missing": {
        "viewer_id": ["2", "8"],
        "viewer_sis_id": ["4", "6"]
      }
    }


Example Error Response
~~~~~~~~~~~~~~~~~~~~~~


Status:
  422 Unprocessable Entity
Content-Type:
  ``application/json``

.. code-block:: json

    {
      "detail": "No dashboard mappings were given."
    }