Dashboard Uploads ================= Upload viewers or students for one or multiple dashboards. Fetch previous uploads to review status or download the data included. Linked From: * :doc:`root` Dashboard Upload Fields ----------------------- .. list-table:: :header-rows: 1 :widths: 30, 70 * - Field - Description * - ``id`` - The UUID identifying the upload. * - ``created`` - The timestamp of when the upload was created in ISO8601 format. * - ``href`` - The URL used to interact with the upload. * - ``user`` - The name of the user who created the upload. * - ``data_type`` - A string enum value. Can be "student" or "viewer". * - ``upload_type`` - A string enum value. Can be "api" or "web". * - ``status`` - A string enum value. Can be "uploading", "error", "success_missing" or "success". - ``uploading`` indicates that the upload is being processed. - ``error`` indicates that there was a problem processing the upload. See the ``error`` property for more info. - ``success_missing`` indicates that the upload processed successfully but some of the users included were missing. See the ``missing`` property for more info. - ``success`` indicates that the upload processed successfully. * - ``clear_existing_policy`` - A string enum value. Can be "none", "all", or "contained". - ``none`` will only append the data included in the upload. - ``all`` will replace all of the data at your current account with the data included in the upload. This only impacts the data identified by ``data_type``. - ``contained`` will only replace the data of the dashboards specified in the upload. This only impacts the data identified by ``data_type``. * - ``file_url`` - The signed URL to download the data that was uploaded. It expires after 10 minutes. * - ``error`` - This field is only included on GET requests for a single upload. It contains additional information when the ``status`` field is set to "error". The structure is: ``{"message": "No mappings found"}``. * - ``missing`` - This field is only included on GET requests for a single upload. It contains additional information when the ``status`` field is set to "success_missing". The structure is: ``{"student_id": ["123", "456"]}`` where ``student_id`` is the key specified for any values that AspirEDU does not have a record for. This could also be `"student_sis_id"`, `"viewer_id"`, `"viewer_sis_id"`. GET - List ---------- The ``GET`` method is used to fetch a paginated collection of uploads. The uploads are returned ordered by ``created`` in descending order. The ``GET`` method supports the following query string parameters: .. list-table:: :header-rows: 1 :widths: 30, 70 * - Parameter - Description * - ``cursor`` - A unique identifier to fetch the next or previous page. It is supplied in the response as a way to navigate pages. * - ``clear_existing_policy`` - Optional. Must be of the values outlined in `Dashboard Upload Fields`_ above. Can be specified multiple times to fetch uploads matching any of the values. * - ``data_type`` - Optional. Must be of the values outlined in `Dashboard Upload Fields`_ above. * - ``status`` - Optional. Must be of the values outlined in `Dashboard Upload Fields`_ above. Can be specified multiple times to fetch uploads matching any of the values. * - ``upload_type`` - Optional. Must be of the values outlined in `Dashboard Upload Fields`_ above. * - ``account`` - Filter down to the dashboard uploads from the account and all of its subaccounts. The account must be a subaccount of the account associated with your API token. Accepted Request Content-Types: ``application/json`` Available Response Content-Types: ``application/json`` Example Request ~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/upload/?status=success&status=error`` Content-Type: ``application/json`` Example Success Response ~~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/upload/?status=success&status=error`` Status: 200 OK Request Content-Type: ``application/json`` .. code-block:: json { "next": "https://apps.aspiredu.com/detective/api/v2/dashboard/upload/?cursor=UNIQUE_STRING&status=success&status=error", "previous": "https://apps.aspiredu.com/detective/api/v2/dashboard/upload/?cursor=DIFFERENT_UNIQUE_STRING&status=success&status=error", "results": [ { "id": "00000000-0000-0000-0000-000000000000", "created": "2022-01-01T01:01:00.000000-00:00", "href": "https://apps.aspiredu.com/detective/api/v2/dashboard/upload/00000000-0000-0000-0000-000000000000/", "user": "Jill Jillian", "data_type": "student", "upload_type": "api", "status": "success", "clear_existing_policy": "none", "file_url": "https://aws/s3/unique/id/students.csv" }, { "id": "11111111-1111-1111-1111-111111111111", "created": "2022-02-02T02:02:00.000000-00:00", "href": "https://apps.aspiredu.com/detective/api/v2/dashboard/upload/11111111-1111-1111-1111-111111111111/", "user": "John Jacobs", "data_type": "viewer", "upload_type": "api", "status": "error", "clear_existing_policy": "all", "file_url": "https://aws/s3/unique/id/viewers.csv" }, ] } .. _Dashboard Upload POST: POST ---- The ``POST`` method is used to create a dashboard upload. When an upload is created, the data is processed asynchronously. You can poll the URL returned in the upload's ``href`` property. When the ``status`` field is no longer ``uploading``, it has completed. Please give a few minutes between polling requests to check on the status of an upload. See the `GET - Detail`_ example responses for the variations on what will be returned when the upload has been processed. Only one upload should be attempted at a time. Append-only (``clear_existing_policy="none"``) uploads can be run concurrently, but uploads that clear existing data (``clear_existing_policy="all"`` and ``clear_existing_policy="contained"``) may conflict with other uploads. If you wish to clear the students/viewers for a dashboard, create an empty upload that contains an ID or SIS ID that is known to not exist. The system will clear the existing data, then attempt to set the new student/viewer (depending on ``data_type``) which won't exist. The upload will be marked with ``status="success_with_missing"`` and the dashboard will have no students/viewers associated with it. .. warning:: Please be aware that using a ``clear_existing_policy`` of ``all`` or ``contained`` may conflict with dashboard changes made through the Dropout Detective/Grade Guardian web application. If the integration uses a ``clear_existing_policy`` of ``all`` or ``contained``, 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. The ``POST`` method requires the following fields: .. list-table:: :header-rows: 1 :widths: 20, 20, 60 * - Parameter - Type - Notes * - ``data_type`` - String - Can be "student" or "viewer". * - ``clear_existing_policy`` - String - Can be "none", "all", or "contained". - ``none`` will only append the data included in the upload. Use this value when only adding users to the dashboards. - ``all`` will replace all of the data at your current account with the data included in the upload. This only impacts the data identified by ``data_type``. Use this value when the students or viewers depending on ``data_type`` should be entirely replaced with the data in the upload. - ``contained`` will only replace the data of the dashboards specified in the upload. This only impacts the data identified by ``data_type``. Use this value when wanting to replace or clear a specific dashboard or set of dashboards' students or viewers. * - ``file`` - File - When used, the request content-type must be ``multipart/form-data``. If using ``data``, this field doesn't need to be specified. The columns in the CSV should be in one of the following formats. The use of viewer/student is dependent on the ``data_type`` specified: - ``dashboard_name, viewer_id, viewer_is_ally`` - ``dashboard_name, viewer_sis_id, viewer_is_ally`` - ``dashboard_name, student_id`` - ``dashboard_name, student_sis_id`` * - ``data`` - Array of JSON mappings. - When used, the request content-type must be ``application/json``. If using ``file``, this field doesn't need to be specified. Each element in the array can have the following formats. The use of viewer/student is dependent on the ``data_type`` specified: - ``{"dashboard_name": str, "viewer_id": str, "viewer_is_ally": bool}`` - ``{"dashboard_name": str, "viewer_sis_id": str, "viewer_is_ally": bool}`` - ``{"dashboard_name": str, "student_id": str}`` - ``{"dashboard_name": str, "student_sis_id": str}`` The ``POST`` method supports the following query string parameters: .. list-table:: :header-rows: 1 :widths: 30, 70 * - Parameter - Description * - ``account`` - Upload the dashboards for the given account. The account must be a subaccount of the account associated with your API token. Accepted Request Content-Types: ``multipart/form-data``, ``application/json`` Available Response Content-Types: ``application/json`` Example Request ~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/upload/`` Content-Type: ``application/json`` .. code-block:: json { "data_type": "viewer", "clear_existing_policy": "none", "data": [ {"dashboard_name": "foo", "viewer_id": "123", "viewer_is_ally": true}, {"dashboard_name": "foo", "viewer_id": "456", "viewer_is_ally": false} ] } Example Uploading Response ~~~~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/upload/`` Status: 200 OK Request Content-Type: ``application/json`` .. code-block:: json { "id": "00000000-0000-0000-0000-000000000000", "created": "2022-01-01T01:01:00.000000-00:00", "href": "https://apps.aspiredu.com/detective/api/v2/dashboard/upload/00000000-0000-0000-0000-000000000000/", "user": "Jill Jillian", "data_type": "viewer", "upload_type": "api", "status": "uploading", "clear_existing_policy": "none", "file_url": "https://aws/s3/unique/id/viewers.json", "error": {}, "missing": {} } Example Error Responses ~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/upload/`` Status: 400 Bad Request Content-Type: ``application/json`` .. code-block:: json { "data_type": ["This field may not be blank."] } URL: ``/detective/api/v2/dashboard/upload/`` Status: 400 Bad Request Content-Type: ``application/json`` .. code-block:: json { "non_field_errors": [ "Must supply either a file or data." ] } GET - Detail ------------ The ``GET`` method can be used to fetch a single uploads details when the ``id`` is specified in the URL. This is useful when polling the status of a recently posted upload. Accepted Request Content-Types: ``application/json`` Available Response Content-Types: ``application/json`` Example Request ~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/upload/00000000-0000-0000-0000-000000000000`` Content-Type: ``application/json`` Example Success Response ~~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/upload/00000000-0000-0000-0000-000000000000`` Status: 200 OK Request Content-Type: ``application/json`` .. code-block:: json { "id": "00000000-0000-0000-0000-000000000000", "created": "2022-01-01T01:01:00.000000-00:00", "href": "https://apps.aspiredu.com/detective/api/v2/dashboard/upload/00000000-0000-0000-0000-000000000000/", "user": "Jill Jillian", "data_type": "viewer", "upload_type": "api", "status": "success", "clear_existing_policy": "none", "file_url": "https://aws/s3/unique/id/viewers.json", "error": {}, "missing": {} } Example Success with Missing Response ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/upload/00000000-0000-0000-0000-000000000000`` Status: 200 OK Request Content-Type: ``application/json`` .. code-block:: json { "id": "00000000-0000-0000-0000-000000000000", "created": "2022-01-01T01:01:00.000000-00:00", "href": "https://apps.aspiredu.com/detective/api/v2/dashboard/upload/00000000-0000-0000-0000-000000000000/", "user": "Jill Jillian", "data_type": "viewer", "upload_type": "api", "status": "success_missing", "clear_existing_policy": "none", "file_url": "https://aws/s3/unique/id/viewers.json", "error": {}, "missing": {"viewer_id": ["456"]} } Example Error Responses ~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/upload/00000000-0000-0000-0000-000000000000/`` Status: 200 OK Request Content-Type: ``application/json`` .. code-block:: json { "id": "00000000-0000-0000-0000-000000000000", "created": "2022-01-01T01:01:00.000000-00:00", "href": "https://apps.aspiredu.com/detective/api/v2/dashboard/upload/00000000-0000-0000-0000-000000000000/", "user": "Jill Jillian", "data_type": "viewer", "upload_type": "api", "status": "error", "clear_existing_policy": "none", "file_url": "https://aws/s3/unique/id/viewers.json", "error": {"message": "Internal error."}, "missing": {} } URL: ``/detective/api/v2/dashboard/upload/00000000-0000-0000-0000-000000000000/`` Status: 404 Not Found Content-Type: ``application/json`` .. code-block:: json { "detail": "Not found." }