Integrating Ares and Blackboard with LTI 1.3

Print Friendly and PDF Follow

Note that while Ares supports maintaining LTI 1.1 and LTI 1.3 connections simultaneously, configuring LTI 1.3 within Blackboard will disable your previous LTI 1.1 configuration within the Blackboard interface and break the LTI 1.1 connection with Ares. Therefore, it is recommended to set up a separate LTI 1.3 test environment for Blackboard if you would like to test out the LTI 1.3 connection with Ares before going live.

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. 

Please see Integrating Ares with LTI 1.3 for more general information on the LTI 1.3 integration 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.

Warning: Verifying Your Ares Web Domain and Web API Installation Path

The Ares web domain and path to the Ares Web API used in the links configured in the Blackboard settings below must match that of the value used in the entry for the ClientUploadAPIConfig key in Ares Customization Manager's APIConfig table. Your Blackboard administrator should verify this domain and path with the Ares Administrator during the configuration process. See Verify the APIConfig Table Configuration below for more information on checking the APIConfig table for these values.

Note that https://<your.AresWeb.domain>/ares/webapi/ is the Web API path used for standard Ares installations. This path may differ if your Web API is installed in a non-standard location. For example, if your Web API is installed in a 'nonshib' folder, your links would need to be adjusted to reflect this installation path: https://<your.AresWeb.domain>/nonshib/webapi/

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:

    Register_LTI_application.png

  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 (Menu.png) 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:

    System_Admin.png

  3. Click LTI Tool Providers under Integrations:

    LTI_Tool_Providers.png

  4. Click Register LTI 1.3 Tool:

    Register_LTI_tool.png

  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:

    Manage_Placements.png

  2. Click Create Placement:

    Create_Placement.png

  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:

    Deep Linking placement type

    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:

    Manage_Placements.png

  2. Click Create Placement:

    Create_Placement.png

  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:

    Course tool placement type

    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:

Configuring the Ares LTIPlatforms table will require obtaining settings for the LTI 1.3 application/tool in both the Blackboard Developer Portal and Blackboard web interface. To access each of these sets of details, follow the instructions below:

  • Blackboard Developer Portal: The information for the LTI 1.3 application in the Blackboard Developer Portal can be accessed from the home page by clicking the menu button (Menu.png) next to the name of the application and selecting Edit
  • Blackboard web interface: The information for the LTI 1.3 tool in the Blackboard web interface can be accessed from the LTI Tool Providers page in the System Admin interface by clicking the name of the tool
  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.

Due to a known bug in Blackboard, first-time Ares users may encounter issues accessing Ares from the Blackboard course page if deep links to Ares items are clicked by that user before the link to the Ares course home page. Please see First Time Users Unable to Access Ares Content in Blackboard Using LTI 1.3 Links for more details and information on implementing a workaround.
An entry containing key information for the LTI connection will be automatically generated in the LTIKeys table in the Ares Customization Manager upon first connection by Blackboard to the Ares server. 

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:

    System_Admin.png

  3. Click LTI Tool Providers under Integrations:

    LTI_Tool_Providers.png

  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:

    Manage_Placements.png

  5. Select to edit the placement you created for the Ares course home page
  6. Change the Availability setting to Yes:

    Availability.png

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

    Course_Home_Page.png

Step Two: Adding Deep Links to Ares Course Items

Note: Ares items that link to external content hosted on an HTTP connection may not load properly within a Blackboard interface using an HTTPS connection. For more details, click here.

Deep linking functionality requires that the ltiContentItem.js file is present in the js folder of your Ares web directory. If your web directory does not contain this file, please visit the Ares Downloads page to download the latest version of the Ares web pages, then locate and copy this file from the downloaded web pages into the js folder in your web directory. After adding the file, ensure that the following line of code is added to your include_head.html file: 

<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:

    System_Admin.png

  3. Click LTI Tool Providers under Integrations:

    LTI_Tool_Providers.png

  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:

    Manage_Placements.png

  5. Select to edit the placement you created for the Ares item selection link
  6. Change the Availability setting to Yes:

    Availability.png

  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

Click here to view a video tutorial on this process. 

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:

    Course_Content.png

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

    Build_Content.png

  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:

    Reserve_Items.png

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

    Course_Items.png

Questions?

If this article didn’t resolve your issue, please contact Atlas Support for assistance:

Contact Support