To integrate Ally with your D2L Brightspace instance you need to follow these steps:

  1. User and Role creation. This needs to be done before any call with the Anthology Ally contact. 
  2. Main configuration
  3. Configure LTI
    • Client configuration
    • Institution Report
    • Course Accessibility Report

User and role creation 

  1. Create a new role 
    1. From the Settings menu​​​ (gear icon) navigate to Roles and permissions 
    2. Start the create role process by selecting the Create/Copy button 
    3. Create a new blank role by selecting the Start Fresh button 
    4. Role settings:  
      • Name: Ally REST Role 
      • Description: The set of permissions to allow Ally to securely communicate with the Brightspace REST APIs 
      • Enable Cascading Role 
        Leave the Primary Facilitator option disabled since it may not be needed anymore
      • Role alias: ally 
      • No changes need to be made under Tool Behavior Options, everything can remain disabled 
      • No changes need to be made under Classlist Display Options, everything can remain disabled 
      • Under Course Access Options:  
        • Enable all access options: 
          • Access inactive courses 
          • Access past courses 
          • Access future courses 
        • Sections and  Groups can remain set to None of the above 
    5. Role interactions:  
      1. Under Enroll Ally REST Role, select the checkbox at the intersection of the Administrator row and Organization column. This allows for creating a user with this role later on. 
      2. Under Search Ally REST Role, select the checkbox at the intersection of the Administrator row and Organization column. This allows for searching for a user with this role later on. 
      3. No further changes are necessary .
         
  2. Configure the role’s permissions 
    Once saved, the new Ally REST Role will appear at the bottom of the role list. Open the dropdown and select Edit Permissions. In this screen, the following permissions need to be granted:  
    1. Filter by the Content tool and grant the following permissions in the Course Offering column:  
      • View Course Content 
      • Compile and Download Content 
      • Download Content Topics 
      • View Content that is Not Released 
      • Manage Content 
      • Create and Edit Modules and Topics 
      • Delete Modules and Topics  (necessary to delete potentially seizure-inducing images )
    2. Course Management Console
      •  See Course Info (Course Offering). This permission is required for Ally to retrieve the department's organizational units.
    3. Classlist 
      • Has Access to the Classlist
    4. Discussions  
      • View discussions (Course Offering)
        This is necessary to list links to discussion topics in a course and its table of contents. 
    5. Quizzes  
      • View quizzes (Course Offering)
        This is necessary to list links to quizzes in a course's table of contents. 
    6. Org Unit Editor  
      • View Org Unit Editor (Organization)  
      • Can add and Edit Org Unit Types (Organization).
        We need this role to list the semesters. Unfortunately, there is no “read-only” permission available. Ally will never create or edit organizational unit-type information.
    7. Security  
      • See Roles and Permissions (Organization)
    8. User Information Privacy 
      1. See Usernames (Course Offering)
        This permission allows Ally to see the User’s identifier, but nothing else. This information is never stored, but due to technical reasons, it is necessary to determine how many students are enrolled in a course.
      2. See First Names (Organization)
        Necessary to retrieve the user’s name and email when they request help. This is never stored on Ally’s end and only passes through in the help email.
      3. See Last Names (Organization)
        Necessary to retrieve the user’s name and email when they request help. This is never stored on Ally’s end and only passes through in the help email.
      4. See Email Addresses (Organization)
        Necessary to retrieve the user’s name and email when they request help. This is never stored on Ally’s end and only passes through in the help email.
    9. Users 
      1. View User Enrollments (Course Offering)
      2. Search for ‘Student’ (Course Offering)
        Student is the default name for the student role. If your institution uses a different name for this user type, enable the Search for ‘...’ instead. This is necessary to retrieve the student count in a course offering. The data that is sent, is anonymized.
      3. View the Users' Email Address (Organization)
        It is necessary to retrieve the user’s email when they request help. This is never stored on Ally’s end and only passes through in the help email.
      4. See the User Management Tool (Organization)
        It is necessary to retrieve the user’s name and email when they request help. This is never stored on Ally’s end and only passes through in the help email.)
  3. User creation
    Once the role has been configured, a new user can be created with this limited set of permissions. 
    1.  From the Settings menu (gear icon), navigate to Users 
    2. Start the create role process by selecting the New User button 
    3. Settings:  
      • First Name: Ally 
      • Last Name: User 
      • Role: Ally REST Role 
      • Username: allyuser 
      • Select Manually set password and enter a suitably secure password in the Password field. It is vital that this password is sufficiently secure as changing it later on will require setting up everything again.
      • Save the user by selecting the Save button 

Main configuration 

Make sure that the User and Role configuration is done first. The following configuration is done in a call with an Anthology Ally contact. Make sure that the configuration call is scheduled first.

  1. From the Settings menu (gear icon), navigate to Manage extensibility
  2. Make sure that you are on the OAuth 2.0 tab
  3. Select the Register an App button
  4. Fill out the form as follows: 
    • Name: Ally
    • Redirect URI: <Redirect URI provided by Anthology contact>
      e.g. https://[Ally env]/api/v1/d2l/callback?clientId=[Ally client ID]
    • Scope: content:*:read content:file:write core:*:* custom:contentaccess:read enrollment:orgunit:read
    • Prompt for user consent: No
    • Enable refresh tokens: Yes
    • I accept the Non-Commercial Developer agreement: Yes
  5. Select the Register button
  6. You will now be presented with the details of the newly created application. Copy down the client id and secret key, and share them with your Anthology Ally contact.
  7. After having the Anthology Ally confirmation, select Update
  8. Sign in to Brightspace as the allyuser
  9. Go to the URL that was provided by your Anthology Ally contact (under Ally admin Client integration details). Although it’s a URL whose hostname ends in .ally.ac you will be automatically redirected to your Brightspace instance. Brightspace will present a screen asking your permission for Ally to interact with the REST API. Select Accept.
  10. If all went well, the following success message should display: The REST integration has successfully been set up!
  11. From the Settings menu (gear icon), navigate to Config Variable Browser
  12. Locate the Ally configurations by using the tree menu on the left: 3rdParty > Ally
    The ally integration lives in d2l.3rdParty.Ally.*
  13. Add the configuration values with the ones provided to you by your Blackboard contact 
    • ClientId
    • ClientSecret – Brightspace will present two inputs. Use the LTI secret for both inputs.
    • ScriptUrl
  14. From the Settings menu (gear icon), navigate to Organizational Tools
  15. Find the row for the Ally Integration and toggle the checkbox so that it’s turned on

Configure LTI

Follow this step to configure the LTI and register Ally tools.