Developer Platform (December 2023)

Data Hub and Data Export Framework

«  Permissions   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  IPSIS  »

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>,
    "Description": <string>,
    "DefaultValue": <string>
}
DefaultValue

Filter default value converted to a string.

EXPORTFILTERTYPE_T

Data set filter types are listed in the table below:

Filter type

Description

1

DateTime

2

OrgUnit

3

Role

4

User

5 ^

Boolean

^ Boolean export filter type added as of LMS v20.21.3

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.7687Z

parentOrgUnitId

6808

roles

578
578,901

userId

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.BrightspaceDataSetInfo

When the service sends you information about a Brightspace Data Set, it will send back a JSON structure like this:

{
   "SchemaId": <string:GUID>,
   "Full": <BrightspaceDataSets.BrightspaceDataSetPluginInfo>|null,
   "Differential": <BrightspaceDataSets.BrightspaceDataSetPluginInfo>|null,
   "ExtractsLink": <string:APIURL>
}
SchemaId

The ID for the requested Brightspace Data Sets schema.

Full

BrightspaceDataSetPluginInfo information about the plugin that generates the Full extracts for this Brightspace Data Set.

Differential

BrightspaceDataSetPluginInfo information about the plugin that generates the Differential extracts for this Brightspace Data Set.

ExtractsLink

An absolute APIURL you can use to get the list of all extracts available to download for all Brightspace Data Set plugins that you have permission to see for this schema.

BrightspaceDataSets.BrightspaceDataSetPluginInfo

When the service sends you information about a Brightspace Data Set plugin, it will send back a JSON structure like this:

{
   "PluginId": <string:GUID>,
   "Name": <string>,
   "Description": <string>,
   "ExtractsLink": <string:APIURL>
}
PluginId

The ID for the Brightspace Data Set plugin that creates the data set and refreshes the data.

Name

The name of the Brightspace Data Set plugin.

Description

The description of the Brightspace Data Set plugin.

ExtractsLink

An absolute APIURL you can use to get the list of extracts available to download for the Brightspace Data Set plugin.

BrightspaceDataSets.BrightspaceDataSetExtractInfo

When the service sends you information about a Brightspace Data Set extract, it will send back a JSON structure like this:

{
   "SchemaId": <string:GUID>,
   "PluginId": <string:GUID>,
   "BdsType": <string>,
   "CreatedDate": <string:UTCDateTime>,
   "DownloadSize": <number>,
   "DownloadLink": <string:APIURL>,
   "QueuedForProcessingDate": <string:UTCDateTime>,
   "Version": <string>
}
SchemaId

The ID for the requested Brightspace Data Sets schema.

PluginId

The ID for the Brightspace Data Set plugin that creates the data set and refreshes the data.

BdsType

The Brightspace Data Set Type of the plugin. Possible values include “Differential” and “Full”.

CreatedDate

The time at which this extract file was created.

DownloadSize

The size of the file in bytes.

DownloadLink

An absolute APIURL you can use to download this extract of the Brightspace Data Set.

QueuedForProcessingDate

The time at which the data set was queued for processing to generate this extract.

Version

The BDS Version in effect for the creation of this extract.

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>
}
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> }, ... ]
}
NextPageUrl

An absolute APIURL you can use to navigate to the next page of available plugins.

PrevPageUrl

An absolute APIURL you can use to navigate to the previous page of available plugins.

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:
Oauth2 Scopes:

reporting:dataset:list

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.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:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.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:
JSON Parameters:
Oauth2 Scopes:

reporting:job:create

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.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:
Query Parameters:

  • page (integer) – Optional. Page number to retrieve (page size is 100 records).

Oauth2 Scopes:

reporting:job:list

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.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:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.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:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.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:
Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Return. This action retrieves a DataSetsVersionInfo with information about the data sets versions.

Note

You can make this call anonymously.

If you’re using OAuth2, you do not need to provide an Authorization header (containing a bearer token) with your call.

If you’re using the legacy 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.

Brightspace Data Sets

GET /d2l/api/lp/(version)/datasets/bds

Retrieve a list of Brightspace Data Sets schemas and plugins.

Parameters:
Oauth2 Scopes:

datasets:bds:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

Return. This action returns an ObjectListPage JSON block containing a list of BrightspaceDataSetInfo blocks. You must be able to handle paginated results from this API.

GET /d2l/api/lp/(version)/datasets/bds/(schemaId)/extracts

Retrieve a list of Brightspace Data Sets extracts that are associated with the provided schema.

Parameters:

  • version (D2LVERSION) – API version.

  • schemaId (GUID) – Schema identifier.

Oauth2 Scopes:

datasets:bds:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

Return. This action returns an ObjectListPage JSON block containing a list of BrightspaceDataSetExtractInfo blocks. You must be able to handle paginated results from this API.

GET /d2l/api/lp/(version)/datasets/bds/(schemaId)/plugins/(pluginId)/extracts

Retrieve a list of Brightspace Data Sets extracts that are associated with the provided plugin and schema.

Parameters:

  • version (D2LVERSION) – API version.

  • schemaId (GUID) – Schema identifier.

  • pluginId (GUID) – Plugin identifier.

Oauth2 Scopes:

datasets:bds:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

Return. This action returns an ObjectListPage JSON block containing a list of BrightspaceDataSetExtractInfo blocks. You must be able to handle paginated results from this API.

GET /d2l/api/lp/(version)/datasets/bds/(schemaId)/plugins/(pluginId)/extracts/(extractId)

Retrieve a file stream or a redirect response to a file stream for the requested extract of the requested schema and plugin.

Parameters:

  • version (D2LVERSION) – API version.

  • schemaId (GUID) – Schema identifier.

  • pluginId (GUID) – Plugin identifier.

  • extractId (string) – Brightspace Data Set extract identifier.

Oauth2 Scopes:

datasets:bds:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

Return. This action retrieves a file stream or a redirect response to a file stream for the requested extract of the Brightspace Data Sets schema and 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

Note that this call may result in you receiving a 302 with a pre-authorized redirect URL where your file stream actually resides. If this redirect URL is not in the same domain you used for the original back-end service, you should not provide any further authentication to use this URL (neither an OAuth 2 authentication header, nor legacy ID-Key authentication parameters).

Legacy actions

We still offer use of the following legacy actions, but you should by preference use the actions in the preceding section.

Warning

These actions are not available with LP API versions 1.44 and later. Their use with LP API versions 1.35 through 1.43 are still supported but not recommended.

GET /d2l/api/lp/(version)/dataExport/bds

Retrieves a list of Brightspace Data Sets plugins that you have permission to see.

Parameters:
Query Parameters:

  • pageSize (number) – Optional. Preferred number of entries to return in each data page.

Oauth2 Scopes:

datahub:dataexports:read

Status Codes:
API Versions:

  • 1.35-1.43 – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Input. The results may include fewer entries per page and results can be spread across multiple pages no matter the requested pageSize.

Return. This action retrieves a paged result set containing a PagedBrightspaceDataSetsReportInfo JSON block with a list of plugins that you have permission to see. You must be able to handle paginated results from this API.

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:
API Versions:

  • 1.35-1.43 – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.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

Note that this call may result in you receiving a 302 with a pre-authorized redirect URL where your file stream actually resides. If this redirect URL is not in the same domain you used for the original back-end service, you do not need to provide any further authentication to use this URL (neither an OAuth 2 authentication header, nor legacy ID-Key authentication parameters).

GET /d2l/api/lp/(version)/dataExport/bds/list

Retrieves a list of Brightspace Data Sets plugins that you have permission to see.

Parameters:
Permissions:

Caller must have Can Access Brightspace Data Sets permission.

Oauth2 Scopes:

datahub:dataexports:read

Status Codes:
API Versions:

  • 1.35-1.43 – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.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)

Oauth2 Scopes:

datahub:dataexports:download

Status Codes:
API Versions:

  • 1.35-1.43 – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.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

Note that this call may result in you receiving a 302 with a pre-authorized redirect URL where your file stream actually resides. If this redirect URL is not in the same domain you used for the original back-end service, you do not need to provide any further authentication to use this URL (neither an OAuth 2 authentication header, nor legacy ID-Key authentication parameters).

«  Permissions   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  IPSIS  »