Dashboard Uploads

Upload viewers or students for one or multiple dashboards. Fetch previous uploads to review status or download the data included.

Linked From:

Dashboard Upload Fields

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:

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

{
  "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"
    },
  ]
}

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:

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:

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

{
  "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

{
  "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

{
  "data_type": ["This field may not be blank."]
}
URL:

/detective/api/v2/dashboard/upload/

Status:

400 Bad Request

Content-Type:

application/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

{
  "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

{
  "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

{
  "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

{
  "detail": "Not found."
}