Integrating Ares and Canvas with LTI 1.3

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

Part One: Canvas Developer Key and Application Setup

A new LTI 1.3 key and application for the Ares connection will first need to be created in the Canvas interface. Your Canvas administrator should follow the steps below when configuring the settings for this key and its application:

1. Log in to your Canvas server with administrator credentials
2. Navigate to Admin > My Site > Developer Keys

3. Click the + Developer Key button then select + LTI Key:

   

4. Fill out the following fields on the key settings page:

   Key Name	Enter a name that will identify the key, for example, "Ares Course Reserves" or "Ares LTI Advantage" (note that this name will only appear in the Canvas administrator interface)
   Owner Email	Enter the email associated with the Canvas administrator account
   Redirect URLs	Enter the following two values on separate lines: 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.
   Configure Method	Manual Entry
   Title	Enter a name for the Ares tool that instructors and students will see when using the tool to connect to Ares on Canvas course pages, for example, "Course Reserves"
   Description	Enter a description for the Ares tool that instructors will see when using the tool to add deep links to Ares items on Canvas course pages, for example, "Add links to course reserve items"
   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.
   OpenID Connect 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. TThis path may need to be adjusted if your Web API is installed in a non-standard location.
   JWK Method	Public JWK URL
   Public JWK 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.
   LTI Advantage Services	Expand this section and enable the following options: Can create and view assignment data in the gradebook associated with the tool. Can view assignment data in the gradebook associated with the tool. Can view submission data for assignments associated with the tool. Can create and update submission results for assignments associated with the tool. Can retrieve user data associated with the context the tool is installed in. Can update public jwk for LTI services.
   Additional Settings	Expand this section and configure the following settings: Custom Fields (optional): Configure custom fields for any additional data you would like to send from Canvas to Ares that is not sent over by default. Custom fields should be entered one per line using a name=value format. Custom fields must be named using all lowercase letters. Privacy Level: Select PUBLIC
   Placements	Select Link Selection and Course Navigation
   Link Selection	Enter the following two settings in this section: Target Link URI: https://<your.web.domain>/ares/webapi/lti/launch Select Message Type: LtiDeepLinkingRequest 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.

5. Click Save

6. Find the entry for the newly created key on the Developer Keys page and click On under the State column to activate the key:

   

7. Copy the value in the Details column:

   

8. Use the navigation pane on the left side of the screen to navigate to Settings > Apps

9. Click the + App button:

   

10. Select By Client ID from the Configuration Type dropdown

11. Paste the value copied from the Developer Keys page in step 6 into the Client ID field:

    

12. Click Submit

13. Click Install:

    

14. The new application should now be successfully created

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 Canvas 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 be checked to ensure that the values match those used for the newly created Canvas developer key:

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 Canvas developer key in step 4 of the section above
   2. Contains the same path to the Ares API as used in the URLs configured in the settings of the Canvas developer key in step 4 of the section above. 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 Canvas using information about the LTI 1.3 application and key created in the Canvas configuration process detailed above. Some additional information about your Ares setup and the LTI roles used by Canvas 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 Canvas administrator to complete the following steps:

1. In the Ares Customization Manager, 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 described below:

   Authentication URL	https://<your.Canvas.domain>/api/lti/authorize_redirect
   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://canvas.instructure.com
   Client ID	In Canvas, navigate to Admin > My site >Developer Keys and copy the value in the Details column for the LTI 1.3 key you created for Ares and paste it into this field:
   Deployment ID	In Canvas, navigate to Admin > My site > Settings > Apps. Locate the application you created for the Ares LTI 1.3 connection in step 10 above and click the gear icon. Copy the Deployment ID value for the application and paste it into this field:
   Key	Leave this field blank
   Key Set URL	https://<your.Canvas.domain>/api/lti/security/jwks
   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 Canvas, the LTIPlatformMappings table should be configured with information on how to map the LTI fields used by Canvas 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 Canvas 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 Canvas 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 Canvas 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 Canvas administrator has defined for your Canvas instance 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, if Canvas is configured to send a custom parameter defined with the name ares_userId, this parameter should be entered as follows:

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

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

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

Once all settings have been configured between Canvas and Ares, the new LTI tool should be tested within the Ares and Canvas 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 Canvas course pages.

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

Once the Ares LTI 1.3 integration has been successfully configured in Canvas and Ares, a link to the Ares course home page will be available in the sidebar of the course page: 

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

1. Within the course page, create or navigate to the module to which to add the Ares item(s) and click the + button:

   

2. From the Add Item window, select External Tool from the dropdown menu, then click on the name of the Ares LTI 1.3 tool configured for Canvas:

   

3. The Ares course page will appear in a new window. Click the Select button for the individual item you want to add to the Canvas module:

   

4. The window to the Ares course page will close and the item information will be populated into the previous Add Item window:

   

5. Click Add Item

6. The link to the Ares item should now appear in the Canvas module: