The Data Hub is a tool in the Learning Environment for generating and accessing data extracts. The data export framework is the API layer that the functionality of the Data Hub is built upon. These routes let you gather information about the back-end service and extract it in a useful format you can use with other tools for analysis or reporting (for example, CSV).
Attributes¶
-
DataExport.
DataSetFilter
¶ This composite contains information about a filter definition for a data set.
{ "Name": <string>, "Type": <int:EXPORTFILTERTYPE_T> }
- EXPORTFILTERTYPE_T
Data set filter types are listed in the table below:
Filter type
Description
1
DateTime
2
OrgUnit
3
Role
4
User
-
DataExport.
DataSetData
¶ This composite contains information about all of the built-in data sets available for you to use for your data export.
{ "DataSetId": <string:GUID>, "Name": <string>, "Description": <string>, "Category": <string>, "Filters": [ { <composite:DataExport.DataSetFilter> }, ... ] }
- DataSetId
The GUID for an available data set on the back-end service.
- Category
The category of the data set on the back-end service (e.g. Insights).
-
DataExport.
ExportJobFilter
¶ This composite contains information about a filter to apply to a data export.
{ "Name": <string>, "Value": <string> }
Here are the filters you can use, along with sample value formats:
Filter name
Example values
startDate, endDate ^
2016-02-24
2016-01-28T19:39:19.7687ZparentOrgUnitId
6808
roles
578
578,901userId
10283
“” - Empty string^ Filters support only UTC date-time values
-
DataExport.
CreateExportJobData
¶ This composite contains information about the built-in data set you want to use for your data export.
{ "DataSetId": <string:GUID>, "Filters": [ { <composite:DataExport.ExportJobFilter> }, ... ] }
- DataSetId
The GUID for an available data set on the back-end service.
-
DataExport.
ExportJobData
¶ This composite contains information about a data export job.
{ "ExportJobId": <string:GUID>, "DataSetId": <string:GUID>, "Name": <string>, "SubmitDate": <string:UTCDateTime>, "Status": <int:EXPORTJOBSTATUS_T>, "Category": <string> }
- ExportJobId
The GUID for a given export of a particular data set.
- DataSetId
The GUID representing a specific data set type.
- Category
The category of the data set on the back-end service (e.g. Insights).
-
DataExport.
DataSetsVersionInfo
¶ This composite contains information about the current Data Sets versions in the Organization.
{ "BdsVersion": <string> }
- BdsVersion
The current version for Brightspace Data Sets in the Organization.
- EXPORTJOBSTATUS_T
Data set export jobs will have one of several distinct statuses, depending on where they are in the export process. The table below describes the statuses:
Job status
Description
0
Queued: Export job has been received for processing.
1
Processing: Currently in process of exporting data set.
2
Complete: Export completed successfully.
3
Error: An error occurred when processing the export.
4
Deleted: File associated with the completed export was deleted from the file system.
Brightspace Data Sets¶
-
BrightspaceDataSets.
DataSetReportInfo
¶ This composite contains information about the plugins that are available for you to use with Brightspace Data Sets.
{ "PluginId": <string:GUID>, "Name": <string>, "Description": <string>, "CreatedDate": <string:UTCDateTime>|null, "DownloadLink": <string:APIURL>|null, "DownloadSize": <number>|null }
- DownloadLink
An absolute APIURL you can use to directly download this data set.
- PluginId
The GUID for the requested Brightspace Data Sets plugin. This is the ID of the server-side plugin that creates the data set and refreshes the data.
-
BrightspaceDataSets.
BrightspaceDataSetReportInfo
¶ This composite contains information about the plugins that are available for you to use with Brightspace Data Sets.
{ "PluginId": <string:GUID>, "Name": <string>, "Description": <string>, "FullDataSet": <boolean>, "CreatedDate": <string:UTCDateTime>|null, "DownloadLink": <string:APIURL>|null, "DownloadSize": <number>|null, "Version": <string>|null, "PreviousDataSets": [ { <composite:BrightspaceDataSets.BrightspaceDataSetReportInfo> }, ... ]|null, "QueuedForProcessingDate": <string:UTCDateTime>|null, "CurrentlyAvailable": <boolean> // Added with LP API v1.51 }
- CurrentlyAvailable
Indicates if download information and link for this data set are currently available or unavailable. If true, the information and download links are provided for all present extracts (if extracts are not present for a data set, the nullable information fields can still be null); otherwise, if false, the information and download links for the data set are temporarily unavailable.
- DownloadLink
An absolute APIURL you can use to directly download this data set.
- FullDataSet
A flag indicating if the plugin is a full or differential data set.
- PluginId
The GUID for the requested Brightspace Data Sets plugin. This is the ID of the server-side plugin that creates the data set and refreshes the data.
- QueuedForProcessingDate
The time at which the data set was queued for processing by the scheduled task.
-
BrightspaceDataSets.
PagedBrightspaceDataSetReportInfo
¶ This composite contains paged information about the plugins that are available for you to use with Brightspace Data Sets.
{ "NextPageUrl": <string:APIURL>|null, "PrevPageUrl": <string:APIURL>|null, "BrightspaceDataSets": [ { <composite:BrightspaceDataSets.BrightspaceDataSetReportInfo> }, ... ] }
-
BrightspaceDataSets.
BrightspaceDataSetSchemaInfo
¶ This composite contains information about the the various schema identifiers and the Brightspace Data Sets plugin identifiers which adhere to each schema.
{ "SchemaId": <string:GUID>, "PluginIds": [ <string:GUID>, ... ] }
Actions¶
-
GET
/d2l/api/lp/
(version)/dataExport/list
¶ Lists all available data sets.
- Parameters
version (D2LVERSION) – API version.
- Oauth2 Scopes
reporting:dataset:list
- Status Codes
200 OK – Action succeeded.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.26+ – Route first appears in LMS v20.20.3.
1.22-1.25 – Deprecated as of LMS v20.21.1.
1.21- – Obsolete as of LMS v20.21.1.
Return. This action retrieves a JSON array of
DataSetData
blocks.
-
GET
/d2l/api/lp/
(version)/dataExport/list/
(dataSetId)¶ Retrieve a data set.
- Parameters
version (D2LVERSION) – API version.
dataSetId (GUID) – Data set identifier.
- Oauth2 Scopes
reporting:dataset:fetch
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to view the specified data set.
404 Not Found – Invalid data set id provided.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.26+ – Route first appears in LMS v20.20.3.
1.22-1.25 – Deprecated as of LMS v20.21.1.
1.21- – Obsolete as of LMS v20.21.1.
Return. This action retrieves a
DataSetData
JSON block containing the information for the requested data set.
-
POST
/d2l/api/lp/
(version)/dataExport/create
¶ Create an export job for the requested data set.
- Parameters
version (D2LVERSION) – API version.
- JSON Parameters
CreateExportJobData (
DataExport.CreateExportJobData
) – Properties of the export job request
- Oauth2 Scopes
reporting:job:create
- Status Codes
200 OK – Action succeeded.
202 Accepted – Job request accepted, but not yet ready.
400 Bad Request – Invalid data set data provided, or could not create job for data set.
403 Forbidden – No permission to manage the specified data set.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.26+ – Route first appears in LMS v20.20.3.
1.22-1.25 – Deprecated as of LMS v20.21.1.
1.21- – Obsolete as of LMS v20.21.1.
Return. This action retrieves a
ExportJobData
JSON block containing the information for the requested export job.
-
GET
/d2l/api/lp/
(version)/dataExport/jobs
¶ Lists all available export jobs that you have previously submitted.
- Parameters
version (D2LVERSION) – API version.
- Query Parameters
page (integer) – Optional. Page number to retrieve (page size is 100 records).
- Oauth2 Scopes
reporting:job:list
- Status Codes
200 OK – Action succeeded.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.26+ – Route first appears in LMS v20.20.3.
1.22-1.25 – Deprecated as of LMS v20.21.1.
1.21- – Obsolete as of LMS v20.21.1.
Return. This action retrieves a JSON array of
ExportJobData
blocks, sorted by most recent SubmitDate. By default, only the first 100 records are retrieved. Additional records can be retrieved by specifying the optional page query string parameter.
-
GET
/d2l/api/lp/
(version)/dataExport/jobs/
(exportJobId)¶ Retrieves information about a data export job that you have previously submitted.
- Parameters
version (D2LVERSION) – API version.
exportJobId (GUID) – Export job identifier.
- Oauth2 Scopes
reporting:job:fetch
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to view the specified data set.
404 Not Found – Invalid export job id provided.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.26+ – Route first appears in LMS v20.20.3.
1.22-1.25 – Deprecated as of LMS v20.21.1.
1.21- – Obsolete as of LMS v20.21.1.
Return. This action retrieves a
ExportJobData
JSON block with the export job’s information.
-
GET
/d2l/api/lp/
(version)/dataExport/download/
(exportJobId)¶ Retrieves a ZIP file containing a CSV file with the data of the requested export job that you previously submitted.
- Parameters
version (D2LVERSION) – API version.
exportJobId (GUID) – Export job identifier.
- Oauth2 Scopes
reporting:job:download
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to view the specified data set.
404 Not Found – Invalid export job id provided, or job not available for download.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.26+ – Route first appears in LMS v20.20.3.
1.22-1.25 – Deprecated as of LMS v20.21.1.
1.21- – Obsolete as of LMS v20.21.1.
Return. This action retrieves a ZIP file containing a CSV file that contains the data of the export job that you requested.
-
GET
/d2l/api/lp/
(version)/dataExport/version
¶ Retrieves information about the Data Sets versions.
- Parameters
version (D2LVERSION) – API version.
- Status Codes
200 OK – Action succeeded.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.30+ – Route first appears in LMS v20.20.11.
Return. This action retrieves a
DataSetsVersionInfo
with information about the data sets versions.Note
You can make this call anonymously.
If you’re using ID-Key Authentication, you do not need to include the x_b and x_d query parameter values for this call. If you do provide user ID and user signature query parameter values with this call, you should ensure they are validly formed user tokens. This has the advantage of identifying the application making the call to this route.
If you’re using OAuth2, you do not need to provide an Authorization header (containing a bearer token) with your call.
Brightspace Data Sets¶
-
GET
/d2l/api/lp/
(version)/dataExport/bds/list
¶ Retrieves a list of Brightspace Data Sets plugins that you have permission to see.
- Parameters
version (D2LVERSION) – API version.
- Permissions
Caller must have Can Access Brightspace Data Sets permission.
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to access the Brightspace Data Sets.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.26+ – Route first appears in LMS v20.20.3.
1.22-1.25 – Deprecated as of LMS v20.21.1.
1.21- – Obsolete as of LMS v20.21.1.
Return. This action retrieves a
DataSetsReportinfo
JSON block with a list of plugins that you have permission to see.
-
GET
/d2l/api/lp/
(version)/dataExport/bds/download/
(pluginid)¶ Retrieves a file stream for the requested Brightspace Data Sets plugin.
- Parameters
version (D2LVERSION) – API version.
pluginId (GUID) – Plugin identifier.
- Permissions
Caller must have Can Access Brightspace Data Sets and can see the requested data set (e.g. Can see Enrollments Data Set)
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to access the Brightspace Data Sets.
403 Forbidden – Your request exceeds your quota; see
ProblemDetails
response body for more details429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.26+ – Route first appears in LMS v20.20.3.
1.22-1.25 – Deprecated as of LMS v20.21.1.
1.21- – Obsolete as of LMS v20.21.1.
Return. This action retrieves a file stream for the requested Brightspace Data Sets plugin. If your request exceeds your quota, resulting in a 403 Forbidden, the Retry-After response header contains the length of time you must wait, in seconds, before your quota is refreshed
-
GET
/d2l/api/lp/
(version)/dataExport/bds
¶ Retrieves a list of Brightspace Data Sets plugins that you have permission to see.
- Parameters
version (D2LVERSION) – API version.
- Query Parameters
pageSize (number) – Optional. Number of entries to return in each data page.
- Oauth2 Scopes
datahub:dataexports:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to access the Brightspace Data Sets.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.26+ – Route first appears in LMS v20.20.3.
1.22-1.25 – Deprecated as of LMS v20.21.1.
1.21- – Obsolete as of LMS v20.21.1.
Return. This action retrieves a paged result set containing a
PagedBrightspaceDataSetsReportInfo
JSON block with a list of plugins that you have permission to see.
-
GET
/d2l/api/lp/
(version)/dataExport/bds/
(pluginid)/
(identifier)¶ Retrieves a file stream for the requested Brightspace Data Sets plugin.
- Parameters
version (D2LVERSION) – API version.
pluginId (GUID) – Plugin identifier.
identifier (string) – Scheduled export identifier.
- Oauth2 Scopes
datahub:dataexports:download
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to access the Brightspace Data Sets.
403 Forbidden – Your request exceeds your quota; see
ProblemDetails
response body for more details.429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.26+ – Route first appears in LMS v20.20.3.
1.22-1.25 – Deprecated as of LMS v20.21.1.
1.21- – Obsolete as of LMS v20.21.1.
Return. This action retrieves a file stream for the requested Brightspace Data Sets plugin. If your request exceeds your quota, resulting in a 403 Forbidden, the Retry-After response header contains the length of time you must wait, in seconds, before your quota is refreshed
-
GET
/d2l/api/lp/
(version)/dataExport/schema/bds
¶ Retrieves a list of schema identifiers and related plugin identifiers.
- Parameters
version (D2LVERSION) – API version.
- Oauth2 Scopes
datahub:dataexports:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to access the Brightspace Data Sets.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
unstable – Route first appears in LMS 10.7.6.
Return. This action retrieves a result set containing
BrightspaceDataSetSchemaInfo
JSON blocks.