Integrate Blackboard Learn

Deploy the Blackboard Learn integration to register for a new course and view the course and its related details as a student, and as an instructor to create a course announcement and view the course members and grades.

Note:

We want your feedback! Please provide feedback for this integration template as you use it. For any issues, our team will also monitor our dedicated forum on a daily basis.

For comprehensive details of out-of-the-box microapps for Blackboard Learn, see Use Blackboard Learn microapps.

Review prerequisites

You need these artifacts to add the integration in Citrix Workspace Microapps:

• Base URL: https://{host_name}.com
• Authorization URL: https://{host_name}.com/learn/api/public/v1/oauth2/authorizationcode
• Token URL: https://{host_name}.com/learn/api/public/v1/oauth2/token
• Client ID: The client ID is the string representing client registration information unique to the authorization server. You collect this as Application Key when you configure the OAuth server.
• Secret: The client secret is a unique string issued when setting up the target application integration. You collect this as Secret when you configure the OAuth client.

Note:

We recommend that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum-security compliance with your configured microapp.

Configure Citrix Gateway to support single sign-on so that once users log in they are automatically logged in again without having to enter their credentials a second time. For more information about configuring SSO, see Citrix Gateway Service https://docs.citrix.com/en-us/citrix-gateway-service/.

Create user account

The integration requires regular access to your Blackboard instance. We recommend creating a dedicated user account: Blackboard Partner account https://docs.blackboard.com/partners/become-a-partner.

The following permissions are required: Full administrator privileges.

API access

Blackboard APIs are enabled by default, we need either Blackboard Developer AMI or Blackboard Partner Account to access the APIs. The number of API requests that can be made to specific resources is limited. We recommend reviewing the following information: https://docs.blackboard.com/learn/rest/admin/groups-quotas-rates

Important

The pagination limit is set to 100. Administrators can extend this limit up to 200 based on APIs.

Blackboard Learn developer server supports up to 10000 API calls/Site/24hours.

Blackboard Learn production server supports up to 75000 API calls/Site/24hours.

Due to limit in API call, incremental synchronization is setup to retain only Course Memberships and Course Announcements. Remaining endpoints will be triggered as part of full synchronization.

Configure OAuth server

Configure the OAuth server to read data through the Blackboard Learn integration.

1. Sign in to https://developer.blackboard.com/.
2. Select My Apps and select the + icon to Create a New App. Alternatively, navigate to: https://developer.blackboard.com/portal/applications/create.
3. Complete the required fields and select Register application and generate API key.
4. Copy and save the Application ID, Application Key and Secret shown on the screen. Use these details for Service Authentication while configuring the integration.
5. Log in to the Blackboard Learn application as an Administrator.
6. Navigate to System Admin.
7. Select REST API Integrations under the Integrations table.
8. Select Create Integration.

9. Complete the required fields:

   1. Paste the Application ID that you selected in step 4 above.
   2. Enter your administrator user name in the Learn User field.
   3. Select Yes for End User Access and Authorized To Act As User.

Configure OAuth client

Configure the OAuth client to writing back data through the Blackboard Learn integration.

1. Sign in to https://developer.blackboard.com/.
2. Select My Apps and select the + icon to Create a New App. Alternatively, navigate to: https://developer.blackboard.com/portal/applications/create.
3. Complete the required fields and select Register application and generate API key.
4. Copy and save the Application ID, Application Key and Secret shown on the screen. Use these details for Service Action Authentication while configuring the integration.
5. Log in to the Blackboard Learn application as an Administrator.
6. Navigate to System Admin.
7. Select REST API Integrations under the Integrations table.
8. Select Create Integration.

9. Complete the required fields:

   1. Paste the Application ID that you selected in step 4 above.
   2. Enter your administrator user name in the Learn User field.
   3. Select Yes for End User Access and Authorized To Act As User.

Add the integration to Citrix Workspace Microapps

Add the Blackboard Learn integration to Citrix Workspace Microapps to connect to your application. The authentication options are preselected. Ensure that these options are selected as you complete the process. This delivers out-of-the-box microapps with pre-configured notifications and actions that are ready to use within your Workspace.

Follow these steps:

1. From the Microapp Integrations page, select Add New Integration and Add a new integration from Citrix-provided templates.
2. Choose the Blackboard Learn tile.
3. Enter an Integration name for the integration.
4. Enter Connector parameters.
   • Enter the instance Base URL:
   • Select an Icon for the integration from the Icon Library, or leave this as the default icon.

5. Under Service authentication, select OAuth 2.0 from the Authentication method menu and complete the authentication details. The authentication options are preselected. Ensure that these options are selected as you complete the process. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

   1. Select Client credentials from the Grant type menu.
   2. Select Authorization Header from the Token authorization menu.
   3. The Token URL is prefilled: https://{host_name}.com/learn/api/public/v1/oauth2/token
   4. Ensure the following is entered for Scope: read
   5. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this as Application Key when you configure the OAuth server.
   6. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration. You collect this as Secret when you configure the OAuth server.

6. Under Service Action Authentication, enable the Use Separate User Authentication in Actions toggle. Service action authentication authenticates at the service action level. The authentication options are preselected. Ensure that these options are selected as you complete the process.

   1. Select OAuth 2.0 from the Authentication method menu and complete the authentication details.
   2. Select Authorization Header from the Token authorization menu.
   3. The Authorization URL is prefilled: https://{host_name}.com/learn/api/public/v1/oauth2/authorizationcode
   4. The Token URL is prefilled: https://{host_name}.com/learn/api/public/v1/oauth2/token
   5. Ensure the following is entered for Scope: write
   6. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this as Application Key when you configure the OAuth client.
   7. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration. You collect this as Secret when you configure the OAuth client.
7. The Enable request rate limiting toggle is enabled. Leave 60 for Number of requests and 1 minute for Time interval.
8. Request timeout is set to 120 by default.
9. (Optional) Enable Logging toggle to keep 24 hours of logging for support purposes.
10. Select Save to proceed.

Configure Service action parameters

After you configure the template above, you need to configure a service action correctly. For the My Grades microapp, update their host_name in the View on Blackboard button of My Grades page.

Follow these steps:

1. From the Microapp Integrations page, navigate to the Blackboard Learn integration and select the My Grades microapp.
2. Select Pages, and then the My Grades page.
3. In the page builder, select the View on Blackboard button element, and then the Actions tab in the right pane.
4. Under Actions, select Go to URL.

5. In the URL template field, replace host_name with your instance host name. This form is used: https://{host_name}/webapps/bb-social-learning-BBLEARN/execute/mybb?cmd=display&toolId=MyGradesOnMyBb_____MyGradesTool

   When finished, leave the screen. Changes are saved automatically for the builder.

Edit table attributes

To finish configuring the integration, you need to change the data type of the endpoints listed below.

Follow these steps:

1. From the Microapp Integrations page, select the menu next to the Blackboard Learn integration, and then Edit. The Data Loading screen opens. If not, select Data Loading from the left side navigation column.

2. For each Endpoint listed in the table below, you need to change the Data type in the menu for the given Attribute.

   Endpoint	Attribute	Data type change
   Course Announcements	Body	Binary
   User Grades	Display Score	Double
   Grade Score	Score Possible	Double

3. For each endpoint, select the menu next to the endpoint and Edit.
4. In the Edit Data Endpoint screen, scroll to the bottom of the page. In the table under Data structure, select the pencil icon to edit the table.
5. In the Edit table attributes screen, change the Data type by selecting the new value from the menu. For each change made for each endpoint, select Save and then Apply.
6. Repeat for the other data endpoints.

You are now ready to set and run your first data synchronization. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see Blackboard Learn connector specifications.

Notes

The pagination limit is set to 100. Administrators can extend this limit up to 200 based on APIs.

Due to limit in API call, incremental synchronization is setup to retain only Course Memberships and Course Announcements. Remaining endpoints will be triggered as part of full synchronization.

Use Blackboard Learn microapps

Existing application integrations come with out-of-the-box microapps. Start with these microapps and customize them for your needs.

Note

For the My Grades microapp, an administrator needs to update their “host_name” in the View on Blackboard button of My Grades page. For complete steps, see Configure Service action parameters.

Course Registration: Register for a course.

Notification or Page	Use-case workflows
New Course Registration notification	When a student enrolls in a course, the enrolled student receives a notification.
Course Registration Detail page	Provides a read only view of enrolled courses with course and instructor details.
List Courses page	Provides a list of available courses.
Course Details page	View course details, instructor details, with a Quick Enroll option.

Create Course Announcement: Allows instructors to an create announcement for a course.

Notification or Page	Use-case workflows
Create Course Announcement page	Provides a form to create an announcement for a course with the following details: Course (Courses drop-down menu), Title, Message, and Publish Date.

Instructor View: Allows instructors to view course members and grades.

Notification or Page	Use-case workflows
Course Details page	Allows the instructor to view a list of available courses.
Member Details page	Allows the instructor to view a list of members enrolled in a course.
Grade Details page	Allows the instructor to view the grades of specific course members.

My Courses: View course announcements and attachments of a course

Notification or Page	Use-case workflows
New Course Announcements notification	When there’s a new announcement, students enrolled in the course receive a notification.
Course Announcement Detail page	Provides a read only view of new announcements for a course with details.
My Courses page	Provides a list of courses the user is enrolled in.
Course Details page	Provides a list of announcements and attachments of a course.
Announcement Detail page	View a course announcement and its details.
Attachment Detail page	View and download the attachment.

My Grades: Allows students to view course grades.

Notification or Page	Use-case workflows
New Grades notification	When there’s a new grade posted, students enrolled in the course receive a notification.
My Grades page	Allow students to view the grades by selecting the course.