Dashboard Students
==================

Manage the mapping of dashboards to students.

Linked From:
  * :doc:`root`

.. hint::

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

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 students missing.
The response will contain details outlining any missing students.


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/student/``

Content-Type:
  ``text/csv``

.. code-block:: text

    dashboard_name,student_id,student_sis_id
    Football,2,
    Football,,4
    Football,,6
    Badminton,8,

URL:
  ``/detective/api/dashboard/student/``

Content-Type:
  ``application/json``

.. code-block:: json

    [
      {"dashboard_name": "Football", "student_id": "2"},
      {"dashboard_name": "Football", "student_sis_id": "4"},
      {"dashboard_name": "Football", "student_sis_id": "6"},
      {"dashboard_name": "Badminton", "student_id": "8"}
    ]

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

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

.. code-block:: json

    {
      "detail": "Some students could not be found.",
      "missing": {
        "student_id": ["2", "8"],
        "student_sis_id": ["4", "6"]
      }
    }


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


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

.. code-block:: json

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