Integrating Ares and Brightspace with LTI 1.3

The steps below will allow you to connect Ares and Brightspace using LTI 1.3. This process will require configuring side-wide settings in a new LTI 1.3 tool using a Brightspace 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 Brightspace. 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 Brightspace should be performed in the following order and will require input from both your Ares and Brightspace administrators:

Part One: Brightspace Web Interface Setup

A new LTI 1.3 tool for the Ares connection will first need to be created and deployed within the Brightspace interface. Your Brightspace administrator should follow the steps below when configuring the settings for this tool and its deployment. 

Step One: Register a New Tool

The administrator for your Brightspace system should first complete the following steps to register a new LTI 1.3 tool for the Ares connection:

1. Click the settings gear icon then click Manage Extensibility in the Admin Tools menu
2. Click the LTI Advantage tab, then click Register Tool
3. Choose Standard registration

4. Complete the following fields:

   Name	Enter a name that will identify the tool, for example, "Ares Course Reserves"
   Description	Enter a description for the tool, for example, "Connects to Ares using LTI 1.3"
   Domain	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.
   Redirect URLs	Enter the following values: 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.
   OpenID Connect Login 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.
   Target Link URI	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.
   Keyset 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.
   Extensions	Select the following: Assignment and Grade Services Deep Linking Names and Role Provisioning Services
   Roles	Check the Send Institution Role option
   Substitution Parameters	Optional: Select any parameters from the pre-defined list
   Custom Parameters	Optional: Enter any additional custom parameters

5. Click Register
6. The new tool should now be successfully created

Step Two: Deploy the New Tool

After the new tool is created, your Brightspace administrator should follow the steps below to deploy the tool:

1. Click on External Learning Tools from the main Brightspace navigation bar
2. Click the LTI Advantage tab
3. Click New Deployment
4. From the Tool dropdown menu, select the tool created in the section above

5. Fill out the following fields:

   Name	Enter a name that will identify the deployment, for example, "Ares Course Reserves Deployment"
   Description	Enter a description for the deployment, for example, "Deployment for Ares using LTI 1.3"
   Extensions	Select the following: Assignment and Grade Services Deep Linking Names and Role Provisioning Services
   Security Settings	Select Org Unit Information Select User Information options as needed Select any of the remaining available options according to your institution's preferences
   Link Information	Select any of the available options according to your institution's preferences
   Make tool available to:	Add the appropriate Org Units to the tool that should use the Ares connection

6. Click Create Deployment
7. The new deployment should now be successfully created

Step Three: Create New Deployment Links 

After creating the LTI 1.3 deployment, two deployment links should be created to enable linking to the Ares course home page and to enable deep linking to Ares items within Brightspace:

1. Click on the deployment just created for Ares in the section above
2. Scroll to the bottom of the page and click the View Links button located right above the Save and Close button
3. Click New Link

4. Fill out the following fields to create a link for the Ares course page:

   Email	Enter the email associated with the Brightspace administrator account
   Associated LTI Tool Deployment Name	Enter the name of the Ares deployment created in the section above, e.g. "Ares Course Reserves Deployment"
   Link Name	Enter a name to identify the link, e.g. "Ares Course Home"
   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.
   Description	Optionally enter a description, e.g. "Links to the Ares course home page using LTI 1.3"
   Link Type	Basic Launch

5. Click Save and Close
6. You will be sent to the Links page. Click LTI Advantage Deployments under the main navigation bar at the top of the screen to return to the Deployments page
7. Repeat steps 1-3 to create a second link that will enable deep linking to Ares items and fill out the following fields:

   Email	Enter the email associated with the Brightspace administrator account
   Associated LTI Tool Deployment Name	Enter the name of the Ares deployment created in the section above, e.g. "Ares Course Reserves Deployment"
   Link Name	Enter a name to identify the link, e.g. "Ares Item Selection"
   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.
   Description	Optionally enter a description, e.g. "Link to allow Ares item selection using LTI 1.3"
   Link Type	Deep Link Quicklink

8. Click Save and Close

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 when the Brightspace configuration is completed. The Ares administrator will need to coordinate with the Brightspace administrator for your institution to ensure that certain 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 first be checked to ensure that the values match those used for the newly created Brightspace 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 Brightspace 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 Brightspace 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 Brightspace using information about the LTI 1.3 tool created in the Brightspace configuration process detailed above. Some additional information about your Ares setup and the LTI roles used by Brightspace 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 Brightspace administrator to complete the following steps:

1. In Brightspace, click on the LTI Advantage tool you created for Ares in the External Learning Tools administrator interface. A window will appear with the configuration information necessary for populating the LTIPlatforms table in Ares
2. In the Ares Customization Manager, open the LTIPlatforms table under System | Integration
3. Click New Record to create a new entry in the table

4. Fill out each field with the information about the Brightspace LTI Advantage tool obtained in step 1:

   Authentication URL	Enter the value in the OpenId Connect Authentication Endpoint in the Brightspace tool configuration details. This value should be in the following format: https://<your.d2l.domain>/d2l/api/authenticate
   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	Enter the value in the Issuer in the Brightspace tool configuration details. This should be the URL of your Brightspace instance.
   Client ID	Enter the value in the Client ID in the Brightspace tool configuration details
   Deployment ID	Enter the value in the Deployment ID in the Brightspace tool configuration details
   Key	Leave this field blank
   Key Set URL	Enter the value in the Brightspace Keyset URL in the Brightspace tool configuration 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'

5. Click Save
6. 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 Brightspace, the LTIPlatformMappings table should be configured with information on how to map the LTI fields used by Brightspace 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 Brightspace 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 Brightspace 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 Brightspace 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.

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

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

Once all settings have been configured between Brightspace and Ares, the new LTI tool should be tested within the Ares and Brightspace 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 and Ares Item Selection (deep linking) to your Brightspace course pages.

Step One: Adding a Link to the Ares Course Home Page

Once the Ares LTI 1.3 integration has been successfully configured in Brightspace and Ares, links to the Ares course home page can be added to Brightspace course pages by course administrators: 

1. Navigate to the Brightspace course page

2. Click on the Content tab:

   

3. Click on the Existing Activities dropdown then click External Learning Tools:

   

4. From the Add Activity window, click on the name of the LTI 1.3 link created for the Ares Course Home:

   

5. The link should now be configured for the course. Test the new link to confirm it works as expected

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 Brightspace and Ares, deep links to Ares course items can be added to Brightspace course pages by course administrators: 

1. Navigate to the Brightspace course page

2. Click on the Content tab:

   

3. Click on the Existing Activities dropdown then click on the name of the LTI 1.3 link created for the Ares Item Selection:

   

4. The Ares course homepage will display the Reserve Items table. Click the Select button next to the relevant Ares item in this table:

   

5. The item link should now be configured for the course. Test the new link to confirm it works as expected