Integrating Ares and Blackboard with LTI 1.3

The steps below will allow you to connect Ares and Blackboard using LTI 1.3. This process will require configuring side-wide settings in a new LTI 1.3 tool using a Blackboard account with administrator permissions. Your Ares administrator will then need to configure tables in the Ares Customization Manager with information from the configuration details for the LTI tool in Blackboard. It is recommended that both administrators work closely together to coordinate work during this process. 

Overview

The process to configure an LTI 1.3 connection between Ares and Blackboard should be performed in the following order and will require input from both your Ares and Blackboard administrators:

Part One: Blackboard Developer Portal and Web Interface Setup

A new LTI 1.3 application for the Ares connection will first need to be created in the Blackboard Developer Portal and then registered in the Blackboard web interface. Your Blackboard administrator should follow the steps below when configuring the settings for this key and its application.

Step One: Creating and Registering an LTI Application in the Developer Portal

Before the new LTI 1.3 application can be registered in the Blackboard interface, it must first be created and registered through the Blackboard Developer Portal. Your Blackboard administrator should follow the steps below when configuring the application:

1. Navigate to the Blackboard Developer Portal
2. Click Sign up to create a new account, or click Log In if you have an existing Blackboard developer account

3. Once logged in, click Register a REST or LTI application:

   

4. Fill in the following settings:

   Name	Enter a name that will identify the tool, for example, "Ares Course Reserves" (note that this name will carry over as the name of the tool in the Blackboard interface where it will not be editable)
   Description	Enter a description for the tool, for example, "Connects to Ares using LTI 1.3"
   Domain(s)	Enter the domain for your Ares server

5. Check the My Integration supports LTI 1.3 toggle and then fill out the remaining settings:

   Login Initiation URL	https://<your.AresWeb.domain>/ares/webapi/lti/login Note: https://<your.AresWeb.domain>/ares/webapi/ is the Web API path used for standard Ares installations. This path may need to be adjusted if your Web API is installed in a non-standard location.
   Tool Redirect URL(s)	Enter the following URLs separated by a comma: https://<your.AresWeb.domain>/ares/webapi/lti/launch, https://<your.AresWeb.domain>/ares/webapi/lti/deeplink Note: https://<your.AresWeb.domain>/ares/webapi/ is the Web API path used for standard Ares installations. This path may need to be adjusted if your Web API is installed in a non-standard location.
   Tool JWKS URL	https://<your.AresWeb.domain>/ares/webapi/lti/keyset Note: https://<your.AresWeb.domain>/ares/webapi/ is the Web API path used for standard Ares installations. This path may need to be adjusted if your Web API is installed in a non-standard location.
   Signing Algorithm	RS256
   Custom Parameters	Create any custom parameters for additional data you would like to send from Blackboard to Ares that is not sent over by default. To create a custom parameter, you will need to create a custom parameter name and set it equal to the relevant Blackboard context variable that contains the data the parameter should hold: UserDefinedParameterName=ContextVariable For more information on context variables, see the Blackboard documentation.  Example: To create a custom parameter with the name blackboard_user_external_uid that will contain data in the @X@user.batch_uid@X@ context variable, enter the following: blackboard_user_external_uid=@X@user.batch_uid@X@ Note: The custom parameter name defined here will be used in the LTI Field Name column when configuring the mapping for the field in the Ares LTIPlatformMappings Customization Manager table. Tip: Create a Custom Parameter to Map to the Ares LibraryID Field It is recommended to create a custom Blackboard parameter that will send over appropriate data to map to the LibraryID User field in Ares. The context variable used for this parameter should contain data that can uniquely identify the user between the two systems and will depend on your institution's Blackboard setup. The example above that uses the @X@user.batch_uid@X@ context variable is one recommended choice for this parameter.

6. Click Register Application
7. You will be taken to a screen displaying various settings for the new application. It is recommended to copy and share these settings with the Ares administrator as many will be used to configure the LTI connection in the Ares LTIPlatforms Customization Manager table later in this process.
8. Ensure that you copy the Application ID for tool as this will be used to register the tool in the Blackboard interface
9. Click Done

10. The tool should now be registered in the Blackboard Developer Portal

    Tip: The settings for the application (excluding application key and secret) can be accessed at any time by clicking the menu button () next to the application name and selecting Edit

Step Two: Registering the Tool in the Blackboard Web Interface

After the new LTI 1.3 application is created in the Blackboard Developer Portal, the Blackboard administrator should register the application as a tool in the Blackboard web interface following the steps below:

1. Log in to your Blackboard server with administrator credentials

2. Click System Admin in the navigation bar at the top of the screen:

   

3. Click LTI Tool Providers under Integrations:

   

4. Click Register LTI 1.3 Tool:

   

5. Enter the Application ID for the tool you created in the Blackboard Developer Portal into the Client ID field
6. Click Submit
7. You will be taken to the Accept LTI 1.3 Tool page, which will automatically populate most tool settings with the information from the Blackboard Developer Portal

8. Configure several additional settings on this page as follows:

   Tool Status	Approved
   Tool Provider Custom Parameters	Confirm that these match the custom parameters defined for the tool in the Blackboard Developer Portal
   User Fields to Send	Check the following options: Role in Course Name Email Address
   Allow grade service access	No
   Allow Membership Service Access	No
   Show User Acknowledgement Message	No

9. Make note of the Deployment ID value on this page, as this value will be used in the Ares LTIPlatforms Customization Manager table to configure the LTI connection
10. Click Submit
11. The tool should now be registered in the Blackboard web interface

Step Three: Creating Placements

After the tool is registered, placements must be created for both the link to the Ares course home page and for the tool to add deep links to individual Ares items within your Blackboard course pages. 

Create a Placement for Deep Links to Ares Course Items

To configure the placement for the tool that will allow instructors to add deep links to Ares items:

1. Hover over the name of the LTI 1.3 tool configured for Ares and click the dropdown button. Click Manage Placements from the dropdown menu:

   

2. Click Create Placement:

   

3. Fill out the following settings:

   Label	The name that will appear for the link on Blackboard course pages, e.g., "Ares Course Reserves Item Selection"
   Handle	A unique identifier for the placement, e.g., "Ares LTI 1.3 Item Selection"
   Availability	For best practice, select No until the LTI 1.3 configuration has been set up on the Ares side as this will enable the Ares LTI 1.3 links to begin appearing on Blackboard course pages.
   Type	Select Deep Linking content tool and then check the box next to Allow student access:
   Tool Provider URL	https://<your.AresWeb.domain>/ares/webapi/lti/launch Note: https://<your.AresWeb.domain>/ares/webapi/ is the Web API path used for standard Ares installations. This path may need to be adjusted if your Web API is installed in a non-standard location.
   Tool Provider Custom Parameters	Enter the custom parameters you defined for the tool in the Blackboard Developer Portal

4. Click Submit
5. The placement for the functionality to add deep links to Ares item is now added to the tool

Create a Placement for the Ares Course Home Page Link

To configure a placement for the link to the Ares course home page on your Blackboard course pages:

1. Hover over the name of the LTI 1.3 tool configured for Ares and click the dropdown button. Click Manage Placements from the dropdown menu:

   

2. Click Create Placement:

   

3. Fill out the following settings:

   Label	The name that will appear for the link on Blackboard course pages, e.g., "Ares Course Reserves"
   Handle	A unique identifier for the placement, e.g., "Ares LTI 1.3 Course Home"
   Availability	For best practice, select No until the LTI 1.3 configuration has been set up on the Ares side as this will enable the LTI 1.3 links to begin appearing on Blackboard course pages.
   Type	Select Course tool and then check the box next to Allow student access:
   Tool Provider URL	https://<your.AresWeb.domain>/ares/webapi/lti/launch Note: https://<your.AresWeb.domain>/ares/webapi/ is the Web API path used for standard Ares installations. This path may need to be adjusted if your Web API is installed in a non-standard location.
   Tool Provider Custom Parameters	Enter the custom parameters you defined for the tool in the Blackboard Developer Portal

4. Click Submit
5. The placement for the Ares course home page is now added to the tool

Part Two: Ares Customization Manager Setup

Your Ares administrator will need to perform several steps to verify and complete the LTI tool configuration in the Ares Customization Manager. The Ares administrator will need to coordinate with the Blackboard administrator for your institution to ensure that specific values are configured consistently across the systems. 

Step One: Verify the APIConfig Table Configuration

The configuration for the Ares API in the APIConfig table should be checked to ensure that the values match those used for the newly created Blackboard tool:

1. Open the ClientUploadAPIConfig key under System | Client Upload and note the key's value
2. Open the APIConfig table under System | Integration 
3. Locate the row of the table with an ID matching the value of the ClientUploadAPIConfig key
4. Verify that the Base API Url value of this row (Note that these values are case-sensitive):
   1. Has a domain matching that of the domain for the URLs configured in the settings of the Blackboard tool configured for the LTI 1.3 connection
   2. Contains the same path to the Ares API as used in the URLs configured in the settings of the Blackboard tool configured for the LTI 1.3 connection. This path is located directly after the domain and will be https://<your.AresWeb.domain>/ares/webapi/ for standard Ares installations. 

Step Two: Configure the LTIPlatforms Table

The LTIPlatforms table in the Ares Customization Manager will then need to be configured for the new connection to Blackboard using information about the LTI 1.3 tool created in the Blackboard configuration process detailed above. Some additional details about your Ares setup and the LTI roles used by Blackboard that you would like to map to the instructor and course proxy roles in Ares will also be required. The Ares administrator should coordinate with the Blackboard administrator to complete the following steps:

1. Open the LTIPlatforms table under System | Integration
2. Click New Record to create a new entry in the table

3. Fill out each field with the information obtained from the tool details in the Blackboard Developer Portal and Blackboard web interface:

   Authentication URL	Enter the value in the OIDC auth request endpoint field located in the Blackboard Developer Portal application details
   Ares Web URL	This field is only needed if you use multiple CMS systems that use multiple sets of web pages. Otherwise, leave it blank and it will use the SystemURL customization key value.
   Issuer	https://blackboard.com
   Client ID	Enter the value in the Application ID field located in the Blackboard Developer Portal application details
   Deployment ID	Enter the value in the Deployment ID field located in the Blackboard web interface tool details
   Key	Leave this field blank
   Key Set URL	Enter the value in the Public keyset URL field located in the Blackboard Developer Portal application details
   Instructor Roles	A comma-delimited list of all of the roles from your CMS that will be considered Instructors in the Ares system. These roles should be entered in the URI format detailed in the IMS Global documentation, e.g. 'http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor'
   Course Proxy Roles	A comma-delimited list of all of the roles from your CMS that will be considered Course Proxies in the Ares system. These roles should be entered in the URI format detailed in the IMS Global documentation, e.g. 'http://purl.imsglobal.org/vocab/lis/v2/membership/Instructor#TeachingAssistant'

4. Click Save
5. Note the ID value of the new row in the LTIPlatforms table you have just created. This ID will need to be entered for each mapping entered in the LTIPlatformMappings table detailed below.

Step Three: Configure the LTIPlatformMappings Table

Once the LTIPlatforms table is created to initiate the connection between Ares and Blackboard, the LTIPlatformMappings table should be configured with information on how to map the LTI fields used by Blackboard to the fields in Ares. Information can also be migrated from the LTIFieldMappings table into this table if you had previously configured an LTI 1.1 connection between Blackboard and Ares, however, please note that the existing LTI Field Name values will need to be updated according to the changes noted in the IMS Global documentation:

1. Open the LTIPlatformMappings table under System | Integration
2. Click New Record to create a new entry in the table

3. Fill out each field with your preferred mappings. Ensure that the LTIPlatformID for each entry matches the ID value for the entry you just created in the LTIPlatforms table :

   LTI Platform ID	Enter the ID of the row in the LTIPlatforms table you configured for the Blackboard tool in the previous section
   Ares Field Name	The name of the Ares database field to which to map the LTI field
   Ares Object Name	Course or User
   LTI Field Name	The name of the LTI field that should map to the specified Ares field Please consult with your campus Blackboard administrator to obtain the proper LTI parameter field names to use for each Ares field mapping. More information on the formatting required for LTI parameter names in LTI 1.3 is available in the IMS Global documentation.

   Formatting Custom LTI Parameters

   Any custom parameters that your Blackboard administrator defined for the Blackboard tool during the configuration process should be entered into the LTI Field Name column in the following format:

   https://purl.imsglobal.org/spec/lti/claim/custom#user_defined_parameter_name

   For example, a custom parameter that was defined with the name blackboard_user_external_uid should be entered as follows:

   https://purl.imsglobal.org/spec/lti/claim/custom#blackboard_user_external_uid

4. Click Save
5. Repeat steps 1-4 until all field mappings are configured.

Part Three: Testing the Connection and Adding Ares Links to Blackboard Courses

Once all settings have been configured between Blackboard and Ares, the new LTI tool should be tested within the Ares and Blackboard interfaces to ensure that all mappings and settings have been configured correctly and that the connection is working as intended. To do so, follow the instructions below to add the new LTI 1.3 links configured for the Ares course home page and the Ares item selection (deep linking) tool to your Blackboard course pages.

Step One: Enabling the Link to the Ares Course Home Page

Once the Ares LTI 1.3 integration has been successfully configured in Blackboard and Ares, the link to the Ares course home page will be added to course pages as soon as the placement created for the link is enabled: 

1. Log in to your Blackboard server with administrator credentials

2. Click System Admin in the navigation bar at the top of the screen:

   

3. Click LTI Tool Providers under Integrations:

   

4. Hover over the name of the LTI 1.3 tool configured for Ares and click the dropdown button. Click Manage Placements from the dropdown menu:

   

5. Select to edit the placement you created for the Ares course home page

6. Change the Availability setting to Yes:

   

7. Click Save

8. The link to the Ares course home page will now appear on course pages in the Course Tools menu:

   

Step Two: Adding Deep Links to Ares Course Items

<script type="text/javascript" src="js/ltiContentItem.js"></script>

Once the Ares LTI 1.3 integration has been successfully configured in Blackboard and Ares, deep links to Ares course items can be added to Blackboard course pages by course administrators.

Enabling the Ares Item Selection Placement

The Blackboard administrator should first ensure that the placement created for the Ares item selection is enabled in the System Admin interface:

1. Log in to your Blackboard server with administrator credentials

2. Click System Admin in the navigation bar at the top of the screen:

   

3. Click LTI Tool Providers under Integrations:

   

4. Hover over the name of the LTI 1.3 tool configured for Ares and click the dropdown button. Click Manage Placements from the dropdown menu:

   

5. Select to edit the placement you created for the Ares item selection link

6. Change the Availability setting to Yes:

   

7. Click Save
8. The link to the Ares item selection is now available for instructors on course pages

Adding Deep Links to Ares Items on a Blackboard Course Page

Once enabled, the Ares item selection tool can be used by instructors to add deep links to Ares reserve items on Blackboard course pages:

1. Navigate to the course home page and click Content:

   

2. Click Build Content and then click on the name Ares item selection tool:

   

3. You will be taken to the Ares course page with the Reserve Items table displayed

4. Locate the item you want to add to the Blackboard course and click Select:

   

5. The link to the Ares item will be added to the Blackboard course: