View on GitHub

equella.github.io

Home

Brightspace Integration Guide

Table of Contents

Brightspace integration overview

EQUELLA integrates with Brightspace using LTI to create a seamless system for users. The purpose of this guide is to provide system administrators with an understanding of the EQUELLA Brightspace integration process to enable successful integration.

Please note that this guide has been developed for Brightspace version 10.5.3 and, as such, may differ in appearance to your own installation.

Prerequisites

To successfully complete this installation the system administrator will require:

System prerequisites for integration

Integration procedure

EQUELLA Brightspace integration can be broken into the following steps:

  1. Configure an EQUELLA App in Brightspace.
  2. Configure a Brightspace External system connector in EQUELLA.
  3. Create a new LTI consumer in EQUELLA.
  4. Setup remote plugins (Course Builder, Insert Stuff, Navbar, Quicklink) in Brightspace.
  5. Test the installation.

Configure Brightspace EQUELLA App

An EQUELLA App needs to be configured in Brightspace before further integration configuration can be carried out in EQUELLA.

To configure an EQUELLA App in Brightspace

  1. Log in to Brightspace as an Administrator, then click the Admin cog in the top right.
  2. The Administration menu displays. Select the Manage Extensibility link from the menu. 3. The Extensibility Management page displays. Select Register an App.
  3. The Register an application page displays.
  4. Enter an Application Name (e.g. EQUELLA).
  5. Enter the Trusted URL. This is the EQUELLA URL, including the institution name, appended with brightspaceauth. For example, https://alphabeta.equella.com/documentation/brightspaceauth NOTE: The URL must be SSL (i.e. https).
  6. Enter the Major Version (e.g. 6) and Minor Version (e.g. 4).
  7. Select I accept the Non-Commercial Developer Agreement.
  8. Click Register Application. Brightspace registers the application, and displays the details.
  9. Note the Application ID and Application Key, as they will be required to be entered when configuring the EQUELLA side of the integration.

Configure EQUELLA

This section describes the required configuration changes to EQUELLA to support a seamless integration. To achieve this, an External system connector and LTI Consumer need to be configured in EQUELLA.

Configure an External system connector

External system connectors are configured from the External system connectors option accessed from the Settings page in EQUELLA.

To create a new External system connector

  1. Select Settings from the navigation menu, and either type External in the filter box, then select External system connectors from the results or scroll down to External system connectors on the Settings list.
  2. The External system connectors page displays.
  3. Select the Add new connector link to open the Create new connector page.
  4. Select Brightspace from the Select a connector type drop-down list. The Brightspace configuration options display
  5. Enter a Connector name (e.g. Brightspace) and Connector description (optional).
  6. Enter your Brightspace URL.
  7. Click Test URL to ensure the entered Brightspace URL is correct. If an error displays, check the validity of the URL. A Connection successful message should display.

NOTE: The help text under Setup application includes a link to your Brightspace instance based on the Brightspace URL entered, and a reference to the Trusted (EQUELLA) URL that must be entered in Brightspace, based on the URL from which the EQUELLA configuration is being completed.

  1. Enter the Application ID (e.g. kWsF23rSJXXiknMLN—Uhg) and Application Key (e.g. Og-n64SRTd5CmMGBEvEFTA) that were provided when registering the EQUELLA App in Brightspace.
  2. Click Test application to ensure the correct Application ID and Key has been entered. If an error displays, check and correct the values. A Success message should display
  3. 10.Click Sign in as a Brightspace administrator. The Brightspace login page displays. Login to Brightspace as an administrator with Manage External Learning Tool Links and Create Quicklinks from available External Learning Tools Links privileges for all course offerings in Brightspace. The signed in Brightspace administrator displays.
  4. If Resource summary page links are not allowed to be added to LMS courses, uncheck Allow users to select the resource summary when pushing content via this connector.
  5. If required, click Change next to Exportable by to open the Select users page. Select the users, groups or roles to access the Add to external system link from the Resource summary page to push content to Brightspace.
  6. If required, click Change next to Content viewable by to open the Select users page. Select the users, groups or roles that can access the Find uses link from the Resource summary page. 14.Click Save.

Register an LTI consumer

LTI consumer client registrations are registered from the Settings page in EQUELLA.

To create a new LTI consumer

  1. Select Settings from the navigation menu, and either type LTI in the filter box, then select LTI consumers from the results or scroll down to LTI consumers on the Settings list. The LTI consumers page displays.
  2. Select the Create new LTI consumer link to open the Create new LTI consumer page.
  3. Enter a Title (e.g. Brightspace) and a Description (optional).
  4. A default Consumer key displays. This can be changed as desired (e.g. brightspaceint). Take note as the Consumer key is entered in Brightspace during integration configuration.
  5. A default Consumer secret displays. This can be changed as desired. Take note as the Consumer secret is entered in Brightspace during integration configuration.
  6. If required, enter a unique Username prefix (e.g. brsp_) or Username postfix (e.g._brsp) for this LTI consumer. This prefix or postfix is added when new users are created to distinguish those users accessing EQUELLA from this LTI consumer.
  7. The Usable by field allows administrators to restrict who can use this LTI consumer. The default is Everyone. Click Change to open the Select recipients… dialog to select users, groups or roles from the Home tab, or other options, such as Guest users, specific IP address etc. from the Other tab.
  8. From the Unknown user handling drop-down, select the system behavior when an attempt is made to logon to EQUELLA with a username that doesn’t exist. Options are:
    • Deny access and present error message
    • Treat user as a guest
    • Create local user and add them to the following groups… If the third option is selected, click the Add groups link open the Select group(s) dialog to search and select the required groups to which the user will be added.

LTI/LIS Role Mappings

Brightspace roles sent through to EQUELLA via the LTI integration need to be mapped to equivalent EQUELLA roles so that relevant privileges can be applied. This is done from the LTI/LIS Role Mappings section of the Create new LTI consumer or Edit LTI consumer pages.

The LTI/LIS Role Mappings section has three areas:

Mapping the Instructor and Unknown roles

In the Instructor and Unknown roles fields, the Add roles link is used to select the EQUELLA roles to be used in the mappings. An example using the Instructor role is shown below:

To map to EQUELLA role/s

  1. Click the Add roles link under the Instructor role field. The Select role(s) dialog displays.
  2. Enter a search query then click Search. Matching results display.
  3. Select the required role/s, then click Select these roles. The mapping/s displays in the Instructor role field. Select the Add roles link to add more mappings.

Mapping the ‘Other’ role

The Other roles section is used to map LTI/LIS standard roles (including the role ‘Other’ which is used in the Brightspace integration) to EQUELLA roles.

To map the ‘Other’ role

  1. In the Other roles area, start typing the required LTI/LIS role (Other) in the Enter LTI/LIS role field. A list of all the standard LTI/LIS roles displays in a drop-down list.
  2. Select Other from the drop-down list.
  3. Click the Add roles link next to the selected LTI/LIS role. k The Select role(s) dialog displays.
  4. Enter a search query then click Search . Matching results display.
  5. Select the required role/s, then click Select these roles. The mapping/s displays in the Other roles field.

To add further EQUELLA roles to ‘Other’ roles that have existing mappings or to add another LTI/LIS role mapping, repeat steps 1 to 5.

Configure Brightspace Plugins

This section describes how to add plugins to Brightspace to allow EQUELLA content to be added. There are four plugins that can be configured to open the EQUELLA integration screen, outlined below:

Course Builder

The Course Builder plugin allows EQUELLA content to be added to multiple course modules via the Course Builder function accessed from the Related Tools drop-down found on the Content page of a Brightspace course.

To configure an EQUELLA Course Builder item

  1. Log in to Brightspace as an administrator then click the Admin Tools icon in the top right hand corner of the Brightspace page. The administration menu displays.
  2. Select the Remote Plugins link. The Manage Remote Plugins page displays.
  3. Click New Remote Plugin. The Create a new Remote Plugin page displays.e Plugin page
  4. Select Course Builder from the Plugin Type drop-down.
  5. Enter a Name for the Course Builder item (e.g. EQUELLA Content).
  6. Enter the Launch Point URL in the form: https://yourinstitution.com/institution/brightspace/coursebuilder.do
  7. Enter the LTI Key and LTI Secret from the Brightspace LTI consumer configured in EQUELLA
  8. If desired, enter an Icon URL.
  9. Click Add Org Units. The Add Org Units page displays.
  10. Select the courses (and descendant options) in which the Course Builder item should be available, then click Insert .The selections display on the Create a new Remote Plugin page.
  11. Click Save. The Manage Remote Plugins page displays with the new Course Builder item listed.
  12. Click the Admin Tools icon in the top right hand corner of the Brightspace page. The administration menu displays.
  13. Select the External Learning Tools link. The Manage External Learning Tools Links page displays.
  14. Click the EQUELLA Course Builder link (e.g. EQUELLA Content launch). The Edit Link page displays.
  15. Scroll down to the Security Settings section, and if not already selected, select Send system username to tool provider and Send system Org Defined ID to tool provider.
  16. Click Save and Close.

To test the Course Builder item

  1. Open a Brightspace course that was added as an Org Unit.
  2. Select the Content link. The course content displays.
  3. Select Course Builder from the Related Tools drop-down. The Course Builder page displays.
  4. Drag the EQUELLA item to a course module.
  5. An access message may display the first time the Course Builder item is used. If so, select the Do not ask me again for this application checkbox, then click Continue. The EQUELLA Integration screen displays.

Insert Stuff

The Insert Stuff plugin allows an EQUELLA content link to be added to the Insert Stuff menu accessed from the Brightspace HTML editor, opening the EQUELLA Integration screen to select and add a single content item which may be embedded or display as a link, depending on the MIME type.

To configure an EQUELLA Insert Stuff link

  1. Log in to Brightspace as an administrator then click the Admin Tools icon in the top right hand corner of the Brightspace page. The administration menu displays.
  2. Select the Remote Plugins link. The Manage Remote Plugins page displays.
  3. Click New Remote Plugin. The Create a new Remote Plugin page displays4. Select Insert Stuff from the Plugin Type drop-down.
  4. Enter a Name for the Insert Stuff link (e.g. EQUELLA Content).
  5. Enter the Launch Point URL in the form: https://yourinstitution.com/institution/brightspace/insertstuff.do
  6. Enter the LTI Key and LTI Secret from the Brightspace LTI consumer configured in EQUELLA
  7. If desired, enter an Icon URL. A small EQUELLA logo can be found at https://yourinstitution.com/institution/images/equella.gif
  8. Click Add Org Units. The Add Org Units page displays.
  9. Select the courses (and descendant options) in which the Insert Stuff link should be available, then click Insert.The selections display on the Create a new Remote Plugin page.
  10. Click Save. The Manage Remote Plugins page displays with the new Insert Stuff link listed.
  11. Click the Admin Tools icon in the top right hand corner of the Brightspace page. The administration menu displays.
  12. Select the External Learning Tools link. The Manage External Learning Tools Links page displays.
  13. Click the EQUELLA Insert Stuff link (e.g. EQUELLA Content launch). The Edit Link page displays. 15.Scroll down to the Security Settings section, and if not already selected, select Send system username to tool provider and Send system Org Defined ID to tool provider.
  14. Click Save and Continue .

To test the Insert Stuff link

  1. Open a Brightspace course that was added as an Org Unit.
  2. Select the Content link. The course content displays.
  3. From a course module select Create a File from the New drop-down. The Brightspace HTML Editor displays.
  4. Click the Insert Stuff button to open the Insert Stuff page.
  5. Select the EQUELLA plugin link to open the EQUELLA Integration screen.
  6. An access message may display the first time the Insert Stuff link is opened. If so, select the Do not ask me again for this application checkbox, then click Continue. The EQUELLA Integration screen displays.

The Navbar plugin allows a link to the EQUELLA Integration screen to be added to course Navigation menus in Brightspace.

To configure an EQUELLA Navbar link

  1. Log in to Brightspace as an administrator then click the Admin Tools icon in the top right hand corner of the Brightspace page. The administration menu displays.
  2. Select the Remote Plugins link. The Manage Remote Plugins page displays.
  3. Click New Remote Plugin . The Create a new Remote Plugin page displays.
  4. Select Navbar from the Plugin Type drop-down.
  5. Select a Target option from the drop-down. Same frame is recommended.
  6. Enter a Name for the Navbar link (e.g. EQUELLA Content).
  7. Enter the Launch Point URL in the form: https://yourinstitution.com/institution/brightspace/navbar.do
  8. Enter the LTI Key and LTI Secret from the Brightspace LTI consumer configured in EQUELLA
  9. If desired, enter an Icon URL. A small EQUELLA logo can be found at https://yourinstitution.com/institution/images/equella.gif
  10. Click Add Org Units. The Add Org Units page displays.
  11. Select the courses (and descendant options) in which the Navbar link should be available, then click Insert .The selections display on the Create a new Remote Plugin page.
  12. Click Save. The Manage Remote Plugins page displays with the new Navbar link listed.
  13. Click the Admin Tools icon in the top right hand corner of the Brightspace page. The administration menu displays.
  14. Select the External Learning Tools link. The Manage External Learning Tools Links page displays.
  15. Click the EQUELLA Navbar link (e.g. EQUELLA Content launch). The Edit Link page displays.
  16. Scroll down to the Security Settings section, and if not already selected, select Send system username to tool provider and Send system Org Defined ID to tool provider.
  17. Click Save and Close.

To add the Navbar link to a Navigation bar

  1. Click the Admin Tools icon in the top right hand corner of the Brightspace page. The administration menu displays.
  2. Select the Navigation and Themes link.
  3. The Navbars page displays.
  4. Select the relevant Navbar link (e.g. Standard Course Navigation). The Edit Navbar page displays.
  5. Click Add Links in the bottom right panel. The Add links dialog displays a list of all available links.
  6. Scroll or search for and select the required Navbar link (e.g. EQUELLA Content), then click Add. The Navbar link now displays in the bottom right panel. Drag and drop to reorder links.
  7. Click Save and Close. The new Navbar link should now appear on the Standard Course Navigation Navbar.

To test the Navbar link

  1. Open a Brightspace course that was added as an Org Unit. The new link appears on the Navbar.
  2. Click on the new link.
  3. An access message may display the first time the Navbar link is opened. If so, select the Do not ask me again for this application checkbox, then click Continue. The EQUELLA integration screen displays.

The Quicklink plugin is accessed from within a course’s Content page, and allows the user to select a single EQUELLA resource to be added to the course module from which the integration screen was accessed.

To configure an EQUELLA Quicklink

  1. Log in to Brightspace as an administrator then click the Admin Tools icon in the top right hand corner of the Brightspace page. The administration menu displays.
  2. Select the Remote Plugins link. The Manage Remote Plugins page displays.
  3. Click New Remote Plugin. The Create a new Remote Plugin page displays.
  4. Select Quicklink from the Plugin Type drop-down.
  5. Enter a Name (e.g. EQUELLA Content).
  6. Enter the Launch Point URL in the form: https://yourinstitution.com/institution/brightspace/quicklink.do
  7. Enter the LTI Key and LTI Secret from the Brightspace LTI consumer configured in EQUELLA.
  8. If desired, enter an Icon URL. A small EQUELLA logo can be found at https://yourinstitution.com/institution/images/equella.gif
  9. Click Add Org Units. The Add Org Units page displays.
  10. Select the courses (and descendant options) in which the Quicklink should be available, then click Insert. The selections display on the Create a new Remote Plugin page.
  11. Click Save. The Manage Remote Plugins page displays with the new Quicklink listed.
  12. Click the Admin Tools icon in the top right hand corner of the Brightspace page. The administration menu displays.
  13. Select the External Learning Tools link. The Manage External Learning Tools Links page displays.
  14. Click the EQUELLA Quicklink link (e.g. EQUELLA Content launch). The Edit Link page displays.
  15. Scroll down to the Security Settings section, and if not already selected, select Send system username to tool provider and Send system Org Defined ID to tool provider.

To test the Quicklink

  1. Open a Brightspace course that was added as an Org Unit in step 11 above.
  2. Select the Content link. The course content displays.
  3. Select a course module then select the Quicklink (e.g. EQUELLA content) from the Add Existing Activities drop-down.
  4. An access message may display the first time the Quicklink is opened. If so, select the Do not ask me again for this application checkbox, then click Continue. The EQUELLA Integration page displays.

NOTE: The dialog needs to be manually resized to see the whole integration page.

Manage external resources and Find uses

The Manage external resources page displays all instances of EQUELLA resources or resource attachments that have been allocated to courses within Brightspace. It enables suitably privileged administration users to perform a variety of actions to any of these EQUELLA resources or resource attachments. These actions include editing the Brightspace display name, and deleting and moving (the latter two can be done in bulk).

The Find uses function allows users to view the Brightspace course modules in which a single resource and/or its attachments have been added. This function is accessed from the Details panel on the EQUELLA Resource summary page.

Enable Manage external resources and Find uses

To enable the Find uses and Manage external resources functionality, a Brightspace configuration process must be completed.

To configure Brightspace for Manage external resources and Find uses

  1. Log in to Brightspace then click the Customization Configuration link in the Navbar. The Customization Configuration Settings page displays.
  2. Select the Equella Domain Match link in the Equella APIs section. The Equella Domain Match page displays.
  3. Click the Edit icon in the Org Value field to open edit mode.
  4. Enter the Org Value in the fields. The Org Value is the institution and path URL (http://myinstitution.com/path/), the institution going in the first field, and the path in the second. The second field is left blank if no path is used in the URL (for example, if your institution URL is just http://myinstitution.com). For example, if the EQUELLA URL is http://eqinstitute/equella/, http://eqinstitute would be entered in the first field, and the path /equella/ in the second. NOTE: This is not to be confused with your EQUELLA institution instance, which is not included in this URL.
  5. Click Save.

Manage external resources page

To view the Manage external resources page

  1. Select Manage external resources from the navigation menu. The Manage external resources page displays.
    The first time a user accesses the Manage external resources function during a session, and if there are multiple connectors (LMSs) configured in the system, the page will prompt for a connector to be selected, otherwise the results page will display immediately.
  2. Select the Brightspace connector from the Within drop-down. The Manage external resources results page displays for Brightspace resources.

The Brightspace Manage external resources page displays EQUELLA resources and resource attachments that have been added to Brightspace courses as links. It provides functionality for viewing, sorting and filtering resources. Additionally, resources can be edited and deleted. The ability to select multiple resources to perform bulk actions (delete and move) is also available from this page. Elements of this page include:

Screen options

Click Screen Options to display the screen options at the top of the page. One screen option is available from this page, Number of results per page. Select the required option from the drop-down list. Options available are Minimum (10), Medium (50) or Maximum (100).

Search pane

Search results

Results can be displayed in groups of 10, 50 or 100 per page, with paging displayed at the end of the search results page. Information displayed for each matching result can include:

Edit

The names that display in Brightspace for resource and resource attachments can be edited from the Manage external resources page. This does not affect the EQUELLA names.

To edit names

  1. Locate the required Brightspace resource on the Manage external resources results page, then click Edit. The Edit external resource dialog displays.
  2. Edit the Name field as required, then click OK. The new text displays on the Manage external resources results page, and in the Brightspace system.

Sort and filter

The Sort and Filter tabs on the Manage external resources results page (Brightspace) display options relevant to Brightspace resources. The sort options are:

From the Manage external resources results page (Brightspace), the following filter options are available:

Bulk actions

Administrators can remove or move individual or multiple external resources in a single operation using the Perform an action button to the right-hand side of the Manage external resources page.

Selecting resources

Select the required resource or resources by clicking Select beside each resource. To select all resources on the results page, click the Select all external resources link in the Selection pane. The selection pane displays the current number of selected resources, as well as the following links:

Actions

Remove

Selecting this action removes the selected resources from their location within the associated LMS. They are also removed from the Manage external resources results page.

To remove external resources

  1. With the required resources selected, click Perform an action to display the Bulk actions page. Click X next to a resource to remove that resource from the list.
  2. Select Remove from the Choose an action to perform: drop-down list then click Execute. A confirmation dialog displays.
  3. Click OK. An information dialog displays, confirming the action was successful. In the case of an unsuccessful action, an error message displays with an explanation of the failed action.

Move

The Move action moves the selected resources from their current locations within the associated LMS to the one selected on the Move dialog.

To move selected resources

  1. With the required resources selected, click Perform an action to display the Bulk actions page. Click X next to a resource to remove that resource from the list.
  2. Select Move from the drop-down list, then click Next. The Bulk actions—Select the locations to add to dialog displays.
  3. Click to expand courses and select the required location to move the selected resources to. Select Show inactive courses to display Brightspace courses marked as ‘inactive’.
  4. Click Execute. A confirmation dialog displays.
  5. Click OK. In the case of an unsuccessful action, an error message displays with an explanation of the failed action.