The Homepage Widget Expansion Pack offers an array of homepage system widgets to provide a more customized learning experience for your homepages.
Important: The Custom Hosted Homepage Widget Expansion Pack will be retired in September 2024/20.24.9. Clients can continue to use the hosted versions of the widget until that date; however, they are no longer supported by D2L. Clients using the custom hosted versions of widgets should upgrade to the new Brightspace System widgets.
Custom hosted widgets that will be replaced with system widgets include:
- Visual Table of Contents Widget
- Welcome Window Widget
- Photo Banner Widget
- Learner Awards Widget
- Slim Announcements Widget
- Single Profile Card Widget
- Content Navigator Widget
Custom hosted widgets that will no longer be supported include:
Note: The Multi-Profile Widget is part of the Homepage Widget Expansion Pack and will continue to function normally as a system widget.
If you currently have a Custom Hosted widget available in your Brightspace instance, a new System Widget version of the same widget is added to your instance.
Check if your widgets need to be replaced
If you have the Create/Edit Homepage permission, a warning message is displayed on all Custom Hosted widgets active on the homepage in the following format: “Action Required: Widget Update: Support for this widget is ending. For automated support to replace this widget visit HWEP EOL Support Service.”
Figure: Use the in-widget message service (for example, in the Visual Table of Contents Widget) to navigate to the HWEP EOL Support Service.
Note: A similar warning also appears on the Homepage Management Tool page if there are Custom Hosted versions of widgets active in the environment. Click on this warning to navigate to the Custom Widget Automated Replacement Service page.
From the Custom Widget Automated Replacement Service page, you can do the following:
- Check a list of all Custom Hosted widgets and the number of homepages the widget is active on.
- Find the exact locations where each widget is active by clicking on a number in the corresponding row of the Homepages Using Legacy Widgets column.
Figure: Use the Custom Widget Automated Replacement Service page to locate, replace, or remove Custom Hosted widgets.
For more information about how to identify which legacy widgets you are using and plan for the retirement of the Homepage Widget Expansion Pack in your environment, refer to Upgrading from the Hosted Widgets.
Note: Automated replacement functionality will be added at a later date.
Use Custom Hosted Widget Replacement Service
The Custom Hosted Widget Replacement Service is a part of the Custom Hosted Widget (Custom Hosted Widget EOL Support) page. The replacement service allows you to:
- Bulk replace all instances of the Custom Hosted widget with the system version (configurations are automatically migrated).
- Bulk delete all instances of the Custom Hosted widget.
Prepare your site
To support a smooth replacement of custom-hosted widgets, consider the following:
-
Ensure that no one is able to add custom-hosted widgets to homepages while the service is active: either announce to the team that custom-hosted widgets are no longer permitted or temporarily change homepages editing permissions for relevant roles.
-
Ensure that for each custom-hosted widget, the corresponding system widget is enabled for your instance, and the system widget tool is activated for your organization. D2L has automatically provided entitlements for system widget equivalents to all clients using Custom Hosted HWEP widgets.
-
Plan to run your widget replacements during a period of off-peak usage. Custom Hosted and System Widgets have minor variations that may distract users if suddenly changed.
Warning: When scheduling blackout periods, consider that widgets have a cache duration of two minutes. After the migration is complete, widgets may not immediately appear as migrated until this two-minute period has elapsed.
Run the Custom Hosted Widget Replacement Service
Warning: Automated replacements cannot be reversed automatically. The only method to revert the actions performed by the replacement service is to manually undo the changes.
To run the Custom Hosted Widget Replacement Service
- Navigate to the Custom Hosted Widget page.
- Select a widget you want to replace. The service can only be applied to one custom-hosted widget at a time, and this widget must be at its end-of-life stage. This includes all HWEP widgets except for the Multi-Profile Widget.
Note: The replacement service cannot be run against custom hosted widgets that have no system widget analog. This includes the K12 Calendar and the K12 Footer.
- Click Replace next to the widget.
Figure: Click Replace to run the Custom HostedWidget Replacement Service.
The replacement service runs as a background task on the Brightspace site.
Note: If you try to run the replacement service on a widget while it is already in progress for that same widget, the latest attempt is not proceeded.
You can navigate away from the Custom Hosted Widgets page without interrupting the replacement service.
Upon completion, the replacement service sends a notification to the Update Alerts section (represented by the bell icon) of the Brightspace main navigation bar. If the replacement service encounters an issue, the notification includes an error code. Click on the notification to navigate to the Custom Hosted Widgets page for details about the error code.
Refer to the list of error codes provided below for more information.
| Code |
Definition |
Solution |
|---|
| x001 |
The custom widget you are attempting to replace does not have an equivalent system widget. |
Submit a support ticket. |
| x002 |
Configuration files associated with this widget could not be migrated. |
Submit a support ticket. |
| x003 |
There was a problem migrating the role definition of the earliest installed custom widget at the organization level.
|
Submit a support ticket. |
| x004 |
A user added this widget to a homepage while the replacement service was running. |
Run the replacement service for this custom widget again. |
| x005 |
This widget could not be replaced. |
Submit a support ticket. |
| x006 |
There was a problem. The system widget analog for this custom widget is not entitled. |
Submit a support ticket. |
| x007 |
Another user is currently running the replacement process for this widget. |
Re-run the service again after the current run is complete (if required). |
| x008 |
Custom titles associated with this widget could not be migrated. |
Submit a support ticket. |
Overview of Actions and Considerations for the Replacement Service
Confirm Entitlement and Tool Status
The replacement service verifies that the system version of the widget is enabled for the instance and checks whether the system widget is activated in Organization Tools:
- If the replacement service discovers that the system widget is not enabled at the instance level, it exits and notifies the user.
- If the replacement service discovers that the system widget is not enabled at Organization Tools, it activates the widget at the organization level and continues.
- If the widget is not active at any child org unit, the replacement service proceeds as though the widget is active for that org unit and replaces the widget. The replaced widget appears inactive on the homepage until the homepage owner activates the widget for that org unit.
Catalog all affected Homepages and Courses
The replacement service scans the site for all instances of the widget on homepages and identifies all courses using homepages with this widget. On certain sites, the widget may have been installed multiple times by mistake. In these cases, the service selects the widget installation at the organization level with the earliest installation date as the canonical version. In most cases, secondary installations are identical to the original organization installation, making this strategy harmless. However, there are special cases, identified by database queries, where secondary installations have been customized in some way. These customized secondary installations must be managed manually before running the replacement service. D2L has directly contacted such clients.
Migrate Configuration Files
Custom Hosted widgets have a default config.txt at the organization level. The replacement service verifies whether this organization config.txt has already been migrated to Widget Data for the organization and carries out the migration if it has not yet been done.
Custom hosted widgets use a combination of locally stored config.txt files and remotely stored Widget Data to save configurations for each course occurrence of a widget. This approach allows a widget to be unique in every course.
System widgets exclusively use Widget Data for data storage. For migration to be successful, the service must transfer data from config.txt files into Widget Data. Using its catalog of affected courses, the replacement service reads the data from the config.txt file of each course and copies it to the Widget Data specific to that course.
The following cases are possible:
- If the local config.txt is identical to the data already stored in the organization's Widget Data, the local configuration is deemed redundant and is not migrated. Custom configurations can be added in the future as needed. Legacy config.txt files are not removed from the file system; they are retained on-site as a backup in case the replacement service fails.
- If the config.txt file is missing at the organization level, configurations from all course levels are migrated.
- If a course has a configuration present in both Widget Data and a config.txt file, the replacement service keeps the version in Widget Data and discards the config.txt data. Although this scenario is unlikely, it could happen if in a course both the system and custom versions of a widget are used.If the JSON inside the config.txt file cannot be read or the file itself is unreadable, the configuration is not migrated. If this happens in the case of a course-level configuration, the widget will inherit the configuration stored at the organization.
Note: Configurations for recycled courses are not migrated.
Migrate Role Configurations
The Learner Awards, Slim Announcements, and Welcome Window widgets have role definitions. Role definitions are a mapping between the roles available in the widget, such as learner or moderator, and the roles defined within Brightspace. For custom hosted widgets, these definitions are stored as a JavaScript variable within the content field of the custom widget. For system widgets, role definitions are stored in a configuration variable specific to each widget.
Note: For custom hosted widgets, role definitions can only be defined per widget installation, not by org unit.
Below is an example of role definitions:
var roleDefinitions = {
"administrator": [
"D2LAdmin"
],
"moderator": [
"D2LAdmin",
"Super Administrator",
"Instructor"
],
"instructor": [],
"learner": []
};
The replacement service scans the content field of the widget, extracts the role definition, and saves it to the appropriate organization configuration variable for that widget.
If the JavaScript object defining the role definition is not valid, the corresponding role definition is not migrated.
In cases where a widget has been installed multiple times on a site, the replacement service uses the role definitions from the widget installation at the organization level with the earliest installation date as the canonical role definitions for the site. A database search of all role configurations was conducted to ensure that there are no sites with divergent role definitions across multiple installations.
Migrate Widget Title and Custom Titles
The replacement service attempts to migrate custom naming associated with the custom hosted widget including custom widget name, custom widget name override, and homepage widget name override:
| Title Type |
Brightspace UI |
Location |
Operation |
|---|
| Custom widget name field |
 Figure: The Name field.
|
Click the edit icon next to the widget name > Custom Widget Properties > Name. |
The override is applied at the org unit where the widget is installed, provided there is no existing custom widget name override for the system widget. The replacement service adopts the name of the most recently created widget. |
| Custom widget name override |
 Figure: The Widget Settings check boxes and the Widget Name radio buttons.
|
Click the customize icon next to the widget name > Widget Settings > Widget Name > select Custom. |
If present, it is applied as an additional override at the org unit where the widget is installed. The widget adopts the name from the most recently created override. |
| Homepage widget name override |
Figure: The Widget Settings check boxes and the Widget Name radio buttons.
|
Click Style this Widget from any homepage > Widget Settings > Widget Name > select Custom. |
If present, this override is applied additionally to the homepage. The widget takes on the name from the most recently created override.
Note: The widget prioritizes adopting the Homepage Widget Name Override over any other name.
|
Replace the Custom Hosted Widget
All system widgets and all custom widgets have unique IDs. Widgets are added to homepages by referencing these IDs. To replace a custom widget on a homepage, the replacement service updates the homepage record to use the ID of the corresponding system widget. This action removes the old custom widget and adds the system widget. The newly added system widget functions identically to the old custom widget, as its configuration and roles have been migrated beforehand.
Courses are not directly modified. Individual courses are only affected if a homepage that they are using is updated.
Uninstall the Custom Hosted Widget
At the final stage, the widget is uninstalled from the site to prevent its future use on homepages. Within the database, the widget is removed from the list of custom widgets, deleting all custom content previously stored in the widget's content field. This is equivalent to using the Delete function on the Custom Widgets panel of the Manage Widgets page.
Warning: If a user added a widget to a homepage while the replacement service is running, the service completes its operation but it is not uninstall the widget. Instead, a notification is sent to the user. In this case, the replacement service must be re-run to remove the recently added widget. Refer to Run the Custom Hosted Widget Replacement Service section.
Once the widget is uninstalled from the site, it becomes unavailable for use on homepages. Since the replacement service updates homepages but not courses, this means that recycled, deleted, and inactive courses are also affected, even though they are not available to users.