Product News Product blogs

Brightspace Data Sets Change Management Policy

Written by: Monica Gaertner, Product Manager

A key feature of the Brightspace Data Sets (BDS) is a strong data contract, ensuring that the data we deliver works consistently and changes predictably. To facilitate this, we've developed a change management policy that outlines changes will be made in a way that adds value while protecting that important data contract.

The policy also outlines a version numbering scheme, which is used to communicate and control release of all changes.

Categories of Change

Changes to BDS fall into two categories: Minor Changes and Major Changes.

Change Category	CD Disruption	Enablement	Comments
Minor	None/Slight	Automatically enabled with no opt-out.	Notice provided in Preview Release Notes with details in Release Notes with GA.
Minor	Moderate	Automatically enabled with no opt-out.	Notice provided 60 days in advance.
Major	Large/Severe	Opportunity to opt-in for 4 months before automatically enabled with no opt-out.	Notice provided 60 days in advance with 4-month adoption period.

Minor Changes

These changes trigger an increment of a minor version number – for example, from version 6.9 to 6.10. It is recommended to develop around these types of changes so that code changes are not required.

Examples of Minor Changes:

Change	Hypothetical Example	Impact	Assumptions	CD Disruption
Add a new Brightspace Data Set	Intelligent Agents BDS added.	New data set appears in UI and API.	Integrations are designed to ignore new data sets listed in the Data Sets API Route.	Slight
Add a column to the composite primary key	Primary Key of Quiz Questions BDS updated to include additional columns: one new and one existing.	The combination of columns that functions as Primary Key changes to include one or more additional columns.	Integrations may need to be updated to use new composite Primary Key, but integrations will continue to function using previous composite Primary Key.	Slight
Remove a column from the composite primary key, but column remains in data set	Primary Key of Quiz Questions BDS updated to no longer require a column, but removed column still exists.	The combination of columns that functions as Primary Key no longer requires one or more columns.	Integrations continue to function using previous composite Primary Key, but integrations may find more value using the new composite Primary Key.	Slight
Change whether a column can be NULL	Updated a column that previously could be null to not nullable.	No longer need to expect NULL values when processing.	Integrations continue to function when something that could be NULL in the past now has a value for every row. However, there may need to be an update to expect a NULL value where there couldn’t be one before.	Slight
Append a new column	LastModifiedDate column added to the end of the Grade Objects BDS.	New column appears in data set after existing data elements.	Integrations are designed to ignore new data elements but proceed with other data elements. See a code example that demonstrates one approach to implementing this behavior.	Moderate
Add new data in the form of additional rows	Soft deletes added to existing BDS.	Additional rows appear in data set. Depending on use, they may need to be filtered out.	Integrations may need to be updated to handle the new rows or filter them out.	Moderate
Change whether a column can be NULL	Updated a column that previously could not be null to nullable.	Expect NULL values when processing the data set.	Integrations continue to function when something that could be NULL in the past now has a value for every row. However, there may need to be an update to expect a NULL value where there couldn’t be one before.	Moderate
Change data type of a column	Changed a column's data type from bit to int.	Previous data type is no longer valid.	Integrations may need to be updated to handle the new data type.	Moderate

Major Changes

Major Changes are disruptive in nature. These changes may trigger an increment of a Major Version number, for example: version 7.x to 8.0. Major Version Changes can be opted into upon release and are automatically adopted four months after the Brightspace monthly update in which they are introduced. Some Major Changes may occur without a new Major Version and these changes will also come with a four month adoption period.

Examples of Major Changes:

Change	Hypothetical Example	Impact	Assumptions
Remove a column	Removed ObjectLookupId2 column from Calendar Events BDS.	Column no longer exists in BDS. In cases where the column was part of the composite Primary Key, the combination of columns that functions as composite Primary Key no longer requires the column being removed.	Integrations must be updated to no longer expect the column being removed in the BDS.
Rename a column	Renamed ObjectId to QuizId.	The column name previously used no longer exists, with a new name taking its place.	Integrations must be updated to update the name of the existing column.
Change character(s) in column name to upper or lower case	Changed HistoryID to HistoryId.	The column name previously used no longer exists, with a new name taking its place.	Integrations must be updated to update the name of the existing column (automatic column detection is case sensitive).
Remove a data set	Awards BDS removed.	Data set is no longer available for download. Some data set removals may occur without a major version change.	Integrations must be updated to remove dependencies on the removed data set.

Please Note: Exceptions for High Priority Defect Fixes

When a defect is found that results in the inability to continue using a data set or blocks normal use, it will be addressed in the next available release. All attempts to fix the defect without disruption will be considered. However, this fix may include actions classified as Major Changes in the table above if no other options are available. If the impact of not adopting the fix is high, the Major Change may be enabled by default following the release.

Release Scenarios

Minor Changes are automatically adopted during the Brightspace monthly update in which they are introduced. Major Changes are automatically adopted four months after the Brightspace monthly update in which they are introduced. This latency is intended to provide sufficient lead time to update integrations to cope with the change. Clients can opt to adopt the Major Change at any time during the four-month adoption period by updating their Brightspace Data Sets active version (d2l.Tools.BrightspaceDataSets.Version). Refer to Set up Data Hub for instructions.

Scenario A - Minor Version release

A Minor Version is released and automatically adopted.

Example: 8.3 is the current active version. When 8.4 is released, it becomes the active version and 8.3 is no longer available. There are no options to opt out of new changes. Minor Version updates can be expected every release.

Scenario B - Major Version release

A Major Version is released, automatic adoption occurs after a four-month adoption period in which you can opt-in to the major version.

Example: 7.4 is the current active version. When 8.0 is released, it is available to opt-in. Once it has been live for four releases, the active version becomes 8.x and 7.x is no longer available.

Scenario C - Major Version release with Minor Versions that follow

A Major Version is released, any subsequently released Minor Versions replace that opt-in version throughout the four-month adoption period and continue to be added to the current Major Version.

Example: 7.8 is the current active version, and 8.0 is released (as the opt-in version) to allow four releases before automatic adoption. One month later, 8.1 is released and replaces 8.0 as the opt-in version during the adoption period, at the same time 7.9 replaces 7.8. This continues each month until the adoption period ends and the opt-in version becomes the active (and only) version available.

Please note, there may be some cases where the Minor Change being released is not applicable to the current Major Version and will therefore only be applied to the new Major Version and be communicated as such.

Scenario D - Major Version release with another Major Version that follows

When adoption of a Major Version occurs, any subsequent Major Version must wait until there is once again a single version in production before releasing. D2L will only support two active Brightspace Data Set versions at a time.

Example: 7.8 is the current active version, and 8.0 is released as the opt-in version to allow four releases before automatic adoption. Once the 4-month adoption period is over, 8.4 will become the active version (and 7.x will no longer be available) and there is the possibility of releasing 9.0 as the opt-in version which will begin its 4-month adoption period.

Tell us what you think

We welcome your feedback on this change management policy and Brightspace Data Sets in general. Please post questions & feedback in the Data and Analytics Community Group or share your feedback with your D2L account representative.