diff --git a/guides/BlackboardLearnIntegrationGuide.md b/guides/BlackboardLearnIntegrationGuide.md index dcd23d3..9fc092b 100644 --- a/guides/BlackboardLearnIntegrationGuide.md +++ b/guides/BlackboardLearnIntegrationGuide.md @@ -1,204 +1,164 @@ -[Home](https://equella.github.io/) +[Home](https://openequella.github.io/) # Blackboard Learn Configuration Guide Table of Contents -* [openEquella Blackboard Learn integration overview](#openequella-blackboard-learn-integration-overview) -* [Prerequisites](#prerequisites) -* [Integration procedure](#integration-procedure) -* [Configure openEquella](#configure-openequella) -* [Register an LTI consumer](#register-an-lti-consumer) +* [openEQUELLA Blackboard Learn integration overview](#openequella-blackboard-learn-integration-overview) +* [Prerequisites](#prerequisites) +* [Integration Procedure](#integration-procedure) +* [Configure openEQUELLA](#configure-openequella) * [Configure Blackboard](#configure-blackboard) -* [openEquella portal](#openequella-portal) -* [Troubleshoot an unsuccessful integration](#troubleshoot-an-unsuccessful-integration) +* [Usage](#usage) +* [Notes](#notes) +* [Migration from B2 to LTI Links](#migration-from-b2-to-lti-links) -## openEquella Blackboard Learn integration overview -openEquella integrates easily with Blackboard Learn™ (Blackboard) by using the openEquella Blackboard Building Block to create a seamless system for users. Additionally the openEquella Shared Secret functionality provides a single sign-on for users. +## openEQUELLA Blackboard Learn Integration Overview +openEQUELLA integrates easily with Blackboard Learn™ (Blackboard) by using Blackboard LTI and REST APIs to create a seamless system for users. -The purpose of this guide is to provide system administrators with an understanding of the openEquella Blackboard integration process to enable successful integration. +The purpose of this guide is to provide system administrators with an understanding of the openEQUELLA / Blackboard integration process to enable successful integration. -Please note that this guide has been developed for Blackboard version 9.1 (SP16) and, as such, may differ in appearance to your own installation. +Please note this guide has been developed using Blackboard version v3800 and, as such, may differ in appearance to your own installation. + +The openEQUELLA / Blackboard integration has historically been achieved with a building block and web service that was uploaded into the Blackboard site. This has presented some difficulties in the past and Blackboard retired their [SOAP Web Services in Q2 2020](https://help.blackboard.com/node/28021) which effectively broke the openEQUELLA web service. Due to this upcoming loss of functionality, and the complexity of maintaining the building block and web service, a pure LTI / REST integration was developed. + +As part of migrating from the building block and web service integration to the LTI / REST integration, a [migration building block](https://github.com/openequella/openEQUELLA-blackboard-integration) was developed to aid in the process. + +Adopters will no longer be able to use the 'My Institution' integration that was part of the building block and web service integration. ## Prerequisites To successfully complete this installation the system administrator will require: -* Sufficient privileges to access the Blackboard system integration functionality. -* Sufficient privileges to access the openEquella User Management functionality +* Sufficient privileges to access the Blackboard system integration functionality +* Sufficient privileges to access the openEQUELLA user management, LTI Consumers, and External System Connector functionality + +In order to make REST calls into a Blackboard site, adopters will need to obtain a REST Application ID via . This REST Application ID will then be used (via the same site), to create a REST Application key and secret that is tied to your Blackboard site URL. You will need this key and secret when configuring the integration in Blackboard. Please read this [post](https://community.blackboard.com/docs/DOC-4258-developer-groups-site-quotas-and-rate-limits) for more information on how Blackboard handles REST Application IDs. System prerequisites for integration -* openEquella version 6.4 and Blackboard version 9.1 (SP16) must be installed and running. -* Ensure the time settings of the servers have the correct time and time zone for their location. This way both will report to Greenwich Mean Time (GMT) and synchronize correctly. -* To access the openEquella Home page at least one course must have been created in Blackboard. Refer to the Blackboard documentation for more information. - -## Integration procedure -openEquella Blackboard integration can be broken into the following steps: -1. Register an LTI OAuth Client in openEquella. -2. Configure and enable the Shared Secret in the openEquella User Management tool. -3. Download the Blackboard Building Block from the openEquella Institution Manager. -4. Upload the building block into Blackboard. -5. Activate the openEquella Plugin in Blackboard. -6. Test the installation. - -## Configure openEquella -This section describes the required configuration changes to openEquella to support a seamless integration. To achieve this, an openEquella LTI OAuth Client Application needs to be registered, along with a Shared Secret configuration. -### Register an LTI consumer -LTI consumer client registrations are registered from the Settings page in openEquella. - -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. Canvas) and a Description (optional). -4. A default Consumer key displays. This can be changed as desired (e.g. canvas). Take note as the Consumer key is entered in Canvas during integration configuration. -5. A default Consumer secret displays. This can be changed as desired. Take note as the Client secret is entered in Canvas during integration configuration. -6. Other options can be enabled as required. - -### LTI/LIS Role Mappings -Canvas roles sent through to openEquella via the LTI integration need to be mapped to equivalent openEquella roles so that relevant privileges can be applied. This is done from the LTI/LIS Role Mappings section of the Add new LTI consumer or Edit LTI consumer pages. - -The LTI/LIS Role Mappings section has three areas: -* Instructor role – map the ‘Teacher’ role to openEquella role/s. -* Other roles –this area is used to map all other roles that might be used in the integration. A list of the standard LTI/LIS roles is supplied. -* Unknown roles – use this area to select the openEquella roles to default to when an unknown role is sent to openEquella. - -### Mapping the Instructor and Unknown roles -In the Instructor and Unknown roles fields, the Add roles link is used to select the openEquella roles to be used in the mappings. An example using the Instructor role is used below: - -To map to openEquella 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 other roles -The Other roles section is used to map LTI/LIS standard roles and other custom roles to openEquella roles. - -To map other roles -1. In the Other roles area, start typing the required LTI/LIS role (e.g. Student) in the Enter LTI/LIS role field. A list of all the standard LTI/LIS roles displays in a drop-down list. -2. Select the required value (e.g. Student) from the drop-down list. -3. Click the Add roles link next to the selected LTI/LIS role. -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 openEquella roles to the Other roles that have existing mappings or to add another LTI/LIS role mapping, repeat steps 1 to 5. - -### Configure a shared secret -Shared secrets are configured in the openEquella Administration Console. -NOTE: The shared secret is used in the openEquella portal functionality outlined below. - -To configure a shared secret -1. Open a browser and enter your openEquella URL (e.g. ‘http://equella.myequellainstitution.edu’). -2. Log in to openEquella as an administrator, select Settings then Administration console. -3. The Administration console displays. Select User Management to display a list of plug-ins. -4. Highlight the Shared Secrets user management plug-in, then click Configure. The Shared Secrets dialog displays. -5. Click Add to create a new shared secret. The Shared Secrets dialog now displays a new shared secret named ‘DEFAULT’ in the left hand pane, and the configuration elements to the right of the pane. -6. Enter a unique Identifier (ID) (e.g. blackboard). -7. Enter a Shared Secret (e.g. bbS3cr3t). The secret may be any combination of characters and numbers, but strings longer than eight characters consisting of upper and lower case alphanumeric characters are recommended. -8. Make a note of the identifier and shared secret; they will be needed to complete the Enable the openEquella Plugin section. -Other options can be enabled as required. -9. Click Save. -10. Click Close to close the dialog. -The Shared Secrets plug-in must be enabled (checked). If not already, enable the plug-in: -1. Check the Enabled checkbox for the Shared Secret plug-in. -2. Click Yes to confirm. -3. Click Exit Console to close the Administration Console. - -NOTE: Only trusted users should be able to see the shared secret, as this information can be used to impersonate any user within openEquella. - -The next step in the integration process is to download the Blackboard Building Block. - -## Configure Blackboard -This section describes the required configuration changes to Blackboard to support the integration. openEquella provides a Building Block tool that allows Blackboard users to easily contribute, search and select openEquella content and link them to a course. -### Download the openEquella Blackboard Building Block -The Blackboard Building Block is available from the Downloads page accessed from the openEquella Server administration page. - -To open the Server administration page -1. Open a browser and enter the complete openEquella admin.url URL (as set in the mandatory-config.properties file in the learningedge-config directory of your openEquella install) with ‘/institutions.do?method=admin’ appended (e.g. where your admin.url URL is set as ‘’ the Institution Manager URL would become ‘’). -2. Enter the password used by the openEquella server administrator (this is set during installation) to display the Server administration - Institutions page. - -To download the Blackboard Building Block: - -3. Select the Downloads button to display the Downloads page. -4. Select the Download the openEquella Blackboard Building Block link for your Blackboard version. -5. Save the relevant .war file (e.g. equella-building-block-9.1.war) to your filesystem. -The next step in the integration process is to install and activate the Blackboard Building Block. - -### Install and activate the Building Block -To access Blackboard Learn -1. Open a browser window and enter your Blackboard URL (e.g. ‘http://blackboard.myequellainstitution.edu’). -2. Log in to Blackboard as a system administrator to display the Blackboard My Institution page. -3. Select System Admin to display the System Admin page. -4. Select the Building Blocks option from the Building Blocks portlet to display the Building Blocks page. -5. Select Installed Tools to display the Installed Tools page. -6. Click Upload Building Blocks to display the Install Building Block page. The Install Building Blocks page displays. -7. Click Browse and select the equella-building-block.war file from your temporary directory. The file name is displayed in the Building Block Package field. -8. Click Submit to install the Building Block and save the settings. -The openEquella Plugin is listed on the Installed Tools page. -The next step in the integration process is to enable the openEquella Plugin. - -### Enable the openEquella Plugin - -To make the openEquella Plugin available -1. Click the down arrow next to openEquella Plugin, then select Set Available from the drop-down list. The openEquella Plugin now displays as Available. - -To configure the openEquella Plugin -1. Click the down arrow next to openEquella Plugin, then select Settings from the drop-down list. The openEquella Server Configuration page displays. -2. Enter the complete openEquella URL to your institution (e.g. ‘http://equella.myinstitution.edu’). -3. Enter the LTI OAuth Client ID (e.g. bboardint). This must be the same as previously configured in the Register an LTI OAuth Client section. -4. Enter the LTI OAuth Client Secret (e.g. f78dbe31-ada6-44cd-90de-4b60afb83cbc). This must be the same as previously configured in the Register an LTI OAuth Client section. -5. Enter the Shared Secret ID (e.g. blackboard). This must be the same as previously configured in the Configure a shared secret section. -6. Enter the Shared Secret (e.g. bbS3cr3t). This must be the same as previously configured in the Configure a shared secret section. -7. From the Restrict to drop-down in the Restrict Selections section, select from: -* Attachments only – users can select only resource attachments to add to courses. -* Items only – users can select only resource summaries to add to courses. -* Packages only – users can select only packages to add to courses. -* No restrictions – users can select both attachments and resource summaries to add to courses. -8. Web service download – this is used for Push to LMS and is not required for the initial Blackboard Learn/openEquella integration process. -9. Click Submit to complete the openEquella Blackboard Learn integration. - -To enable the openEquella Object option in the drop-down -1. Select System Admin, then Tools from the Tools and Utilities section. -2. The Tools page displays. Scroll down to openEquella Plugin. -3. Click OFF beside Course Tool. The button changes to ON and a drop-down list displays in the Scope of Change column. -4. Select New and existing courses from the list. -5. Repeat step 3 and 4 for both Organization Tool (selecting New and existing organizations from the drop-down) and Content Type (selecting New and existing courses and organizations from the drop-down). -6. Scroll to the bottom of the page and click Submit. - -### Test the installation -To access Blackboard - -1. Open a browser and enter your Blackboard URL (e.g. ‘’). -2. Log in to Blackboard as a user with contribution or administration privileges. -3. Select the relevant course (e.g. Physiology 101) from the My Courses pane to display the Course home page. -4. Select either the Content or the Information link from the course menu. (NOTE: The pages represented by these links are different although they contain the same features. For the purposes of this guide they are interchangeable, and the Information page has been used.) The course Information documents page will display. -5. Click Tools to display a drop-down a menu. -6. Select openEquella Object to display the openEquella Integration page. This confirms Blackboard can reach openEquella successfully. - +* openEQUELLA version 2020.1.0+ (or the latest hotfix for 2019.1) +* Blackboard v3800+ + +## Integration Procedure +openEQUELLA Blackboard integration comprises the following steps: +1. Configure an LTI Consumer in openEQUELLA +2. Configure an External System Connector in openEQUELLA +3. Configure REST Application in Blackboard +4. Configure LTI Provider Domain in Blackboard +5. Configure Course Content Tool Placement in Blackboard +6. Test the installation + +## Configure openEQUELLA + +### Configure a LTI Consumer +LTI consumer client registrations are registered from the Settings page in openEQUELLA. The guide to setting up an LTI Consumer can be found in [LTI Consumer Configuration Guide](/guides/LTIConsumerConfigurationGuide.md). + +Use the standard LTI launch endpoint `/ltisignon.do`. -## openEquella portal -The openEquella portal can be displayed on the My Institution page in Blackboard, and provides links to openEquella functions, including workflow tasks and notifications. - -To add the openEquella portal -1. Open a browser window and enter your Blackboard URL (e.g. ‘’). -2. Log in to Blackboard as a system administrator to display the Blackboard My Institution page. -3. Select the System Admin tab to display the System Administration page. -4. Select the Tabs and Modules link from the Communities portlet. The Tabs and Modules page displays. -5. Select Modules to open the Modules page, then navigate to the page that displays openEquella in the Title column. -6. Click the down arrow next to openEquella, then select Edit Properties from the drop-down list. -The Module Properties page displays. -7. Select the System Availability Yes radio button in the Availability section, then click Submit. -The Modules page displays, with the openEquella module now set as Available. -8. Select My institution to display the My institution page. -9. Select Add module. The Add Module page displays. -10. Scroll down to openEquella and click Add. -The My Institution page now displays the openEquella portal. - -## Troubleshoot an unsuccessful integration -If the integration is unsuccessful, these are the points to check first: -1. Check that both the Blackboard server and the openEquella server have synchronized time settings. -2. Ensure that the Shared Secret plugin in the openEquella User Management tool is enabled. -3. Check that the openEquella Blackboard Building Block file is installed. -4. Check that the openEquella Plugin is available in Blackboard. -5. Check the configuration data in Blackboard. -6. \ No newline at end of file +### Configure an External System Connector +1. Under **Settings > External System Connectors**, click on **Add new connector** +2. Select **Blackboard REST** +3. Configure a Connector name, and provide a Blackboard REST URL +4. Click on **Test URL** +5. Specify the REST API Key and REST API Secret from . +6. The rest of the configuration is standard **External System Connector** details + +### Permissions +Grant the following to your openEQUELLA users +* `EXPORT_VIA_CONNECTOR`, `EXPORT_TO_LMS_ITEM`, `VIEWCONTENT_VIA_CONNECTOR`, `FIND_USES_ITEM` - Push to LMS / Find Uses / Manage External Resources. +* `INTEGRATION_SELECTION_SESSION` - LTI launch from Blackboard to openEQUELLA to the selection session page +* `DISCOVER_ITEM` - Discover openEQUELLA items in a search (such as from the selection session). Allows some of the metadata to show. +* `VIEW_ITEM` - View attachments from an LTI launch, view attachments from a selection session. + +## Configure Blackboard + +### Register a LTI Provider Domain + +1. Under **System Admin > LTI Tool Providers**, select **Register Provider Domain**. +2. Configure the Provider domain. e.g. for the openEQUELLA institution, `https://my.learning.center/oeq`, you would put `my.learning.center`. +3. Set **Provider Domain Status** to `Approved`. +4. Under **Default Configuration**, set **Default Configuration** to **Set globally**. +5. Configure the **Tool Provider Key** and **Tool Provider Secret** with the values you configured in the `openEQUELLA LTI Consumer`. +6. Optionally, you can customize how Blackboard sends the user ID and username to openEQUELLA. For example, if you configure the following custom parameters in Blackboard's LTI Provider Domain: +```properties +bb_username=@X@user.id@X@ +bb_user_id=@X@user.batch_uid@X@ +``` +You would need to configure the following in the **openEQUELLA LTI Consumer**: +```properties +Custom User ID: custom_bb_username +Custom Username: custom_bb_user_id +``` +_Note: Blackboard prepends `custom_` to each custom parameter._ +_Note: openEQUELLA prepends a unique value (by **LTI Consumer**) to the user ID. Unticking the checkbox in the **LTI Consumer** config will force openEQUELLA to use the user ID exactly as it is given. +7. Under **Institution Policies**, set **Send User Data** to **Send user data only over SSL**. + * Note: You can select **Send user data over any connection**, but it is not recommended for a Production install. +8. Set **User Fields to Send** to **Role in Course, Name, and Email Address**. +9. Set **Allow Membership Service Access** to **Yes**. + +### Configure a Course Content Tool Placement + +1. Under the newly registered provider domain, select **Manage Placements**. +2. Select **Create Placement**. +3. Configure the label and description. +4. Configure the handle (this cannot change after the placement is created). +5. Leave **Availability** set to **Yes**. +6. Set **Type** to **Course content tool**, and then select **Supports deep linking**. +7. Under **Tool Provider Information**, set the **Tool Provider URL** to `{https://your.oE.domain.xyz/demo/}ltisignon.do`. +8. The **Tool Provider Key** and **Tool Provider Secret** will be preconfigured (and readonly). + +### Configure a REST Application in Blackboard +___TODO - this needs to be updated with the REST MVP logic___ + +1. Under **System Admin > REST API Integrations**, select **Create Integration**. +2. Configure the Application ID from your registration on https://developer.blackboard.com/ . +3. Select a 'Learn User' that has sufficient permissions. +4. Leave **End User Access** as the default **Yes**. +5. Leave the **Authorized To Act As User** as the default **Service Default (No)**. + +## Usage + +### Add an openEQUELLA content link with the Course Content Tool Placement + +In an original Blackboard course, navigate into **{your course} > Information > Build Content > your-oEQ-CCT-placement** . This is known as 'Pull to LMS'. + +### Other integration abilities + +The rest of the integration abilities are similar to the building block and web service flows: +* 'Push to LMS' + * From openEQUELLA, select courses / folders to integrate content links from a given openEQUELLA resource. +* Manage External Resources +* Find Uses + +## Notes + +* The default REST Application ID adopters obtain a 'developer' level ID - there is a 7 Blackboard site limit, and API call rate limits. It is recommended openEQUELLA / Blackboard adopters reach out to their Blackboard Support contacts to discuss the appropriate REST Application ID level for their institution. +* The Blackboard REST integration can be enabled / disabled with the **Available** flag in Blackboard. +* A good write up of the configuration options for Blackboard REST applications is [here](https://community.blackboard.com/community/developers/learn/blog/2019/02/12/end-user-access-authorized-to-act-as-user). +* If you get an error in openEQUELLA `CacheLoader returned null for key TOKEN.`, confirm your Blackboard REST Application is configured and available. + +## Migration From B2 to LTI Links +The building block / web service approach is now deprecated and as of April, 2020 will no longer work properly in Blackboard instances running the version on Blackboard's SaaS installs. It is recommended to upgrade to an openEQUELLA version that supports the integration via LTI and REST. As part of that upgrade and conversion from building block linking to LTI linking, a migration effort needs to occur. This can be accomplished with the [oEQ LTI Migration B2](https://github.com/openequella/openEQUELLA-blackboard-integration/releases/). + +### Notes +* Technically openEQUELLA building block Links are LTI, so this enhancement removes the use of the building block when selecting openEQUELLA links and accessing linked openEQUELLA content from Blackboard. +* It's recommended to backup your Blackboard institution before beginning, and if possible, test the migrations on a Test environment. +* The migration can run institution-wide or by course. It's recommended to run by course for a representative set and do more in-depth testing prior to an institution-wide migration. +* It's supported to re-run a migration over courses. +* The migration utility is a single instance for the institition, so only 1 instance can run at any given time. + +### Quick Start +1. Download the latest version of the migration building block from the github releases page +2. Upload the migration building block into the Blackboard instance you want to migrate +3. Access the building block `Settings` option +4. Your Institution URL is pulled from the primary openEQUELLA integration building block and can only be changed via the primary integration building block. +5. Specify the Placement handle. This is your _NEW_ Blackboard LTI Tool Provider placement handle. Should be something like `apereo/oeq`. +6. Course ID (optional) - when you access your course, the URL contains the course ID (in this case `_1234_1`): +``` +https://my.blackboard.com/ultra/courses/_1234_1/cl/outline +``` +7. Tick the checkbox to allow the migration to run +8. Click 'Submit'. To refresh for updated status, click 'Submit'. +9. Once the migration completes (or errors), you can reset the migration utility (and logs) by ticking the checkbox under the 'RESET' section. + + diff --git a/guides/LTIConsumerConfigurationGuide.md b/guides/LTIConsumerConfigurationGuide.md index 73bb520..838d3c3 100644 --- a/guides/LTIConsumerConfigurationGuide.md +++ b/guides/LTIConsumerConfigurationGuide.md @@ -17,6 +17,7 @@ LTI consumer client registrations can be created in openEQUELLA and used with LM This guide details the configuration of LTI consumers in openEQUELLA, and the LTI/LIS role mappings to openEQUELLA roles. +The standard, non-vendor specific LTI endpoint is `/ltisignon.do`. There are a couple specific LTI endpoints (Canvas and Desire 2 Learn) that have their own LTI endpoints (and accompanying LTI custom logic), but are configured from the same `LTI Consumer`. ## LTI consumer ACLs @@ -37,8 +38,12 @@ To create a new LTI consumer 4. A default Consumer key displays. This can be changed as desired. The Consumer key is entered in the LMS/LTI tool during integration configuration. 5. A default Consumer secret displays. This can be changed as desired. The Consumer secret is entered in the LMS/LTI tool during integration configuration. 6. If required, enter a unique Username prefix (e.g. mdl_) or Username postfix (e.g._mdl) for this LTI consumer. This prefix or postfix is added when new users are created to distinguish those users accessing openEQUELLA 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 openEQUELLA with a username that doesn’t exist. Options are: +7. The following 3 configuration points only apply for standard LTI connections ( that are configured with `/ltisignon.do` ). All three are optional. + 1. `Custom user ID` - Allows configuration of a custom LTI parameter to provide the user ID. + 2. `Custom username` - Allows configuration of a custom LTI parameter to provide the username. + 3. The checkbox to configure the prefix for the user ID allows the system to prepend a hash of the consumer's unique system ID to the user ID to help avoid user ID and username collisions. +8. 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. +9. From the Unknown user handling drop-down, select the system behavior when an attempt is made to logon to openEQUELLA 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… @@ -109,4 +114,4 @@ To delete an 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 Disable link beside the LTI consumer to be deleted. The LTI consumer is disabled, and the Disable link changes to Enable, and a Delete link displays. 3. Select the Delete link beside the LTI consumer to be deleted. A confirmation box displays. -4. Click OK. \ No newline at end of file +4. Click OK.