About Blackboard Learn API connector

Blackboard Learn is a web-based learning management system (LMS) that provides a platform for instructors to manage courses, deliver content, and assess student work.

Leveraging the Blackboard application program interface (API), you can sync select information such as class rosters between Blackboard and Campus Cafe. This saves you time and ensures data integrity.

With the API connector:

• When a student is enrolled (registered) in a course in Campus Cafe, the student is enrolled in the Blackboard course section. (Registrations made directly in Blackboard won’t register the student in Campus Cafe.)

• When a student is dropped (unenrolled) from a course in Campus Cafe, the student is unenrolled from the Blackboard course section.

• If a student is registered for a course in Campus Cafe and the course section doesn’t exist in Blackboard, the connector creates the course section in Blackboard. If the Blackboard course does not exist, the connector creates the course in Blackboard. 

• When a course title is changed in Campus Cafe, the change is applies to the Blackboard course.

• When a student is registered for a course section and doesn’t have a Blackboard account, the connector creates a student account in Blackboard.

• When an instructor is assigned to a course section and doesn’t have a Blackboard account, the connector creates an instructor account in Blackboard.

• When a student or instructor’s name or email is changed in Campus Cafe, the connector applies the change to the person in Blackboard.

Considerations:

• The connector doesn’t automatically create semesters in Blackboard.

• The connector doesn’t sync student photos.

• The connector doesn’t sync or import final course grades.

• The connector won’t prevent students with Campus Cafe holds from accessing Blackboard or their classes.

• When students graduate or otherwise separate from your institution, they retain user accounts in Blackboard. The connector doesn’t disable or remove these accounts. If you don’t want these students to have access to Blackboard or receive communications from Blackboard, you must disable or remove their accounts directly in Blackboard or using your Identity Provider.

Prerequisites

• Purchase and configure Blackboard Learn.

• Configure the Campus Cafe Quality Points to include all final course grades that instructors can enter in Blackboard. For example, A, A-, B+, etc. If your institution uses numerical final grades such as 0 to 100, you’ll need to enter each numerical grade (0, 1, 2, 3, etc.) in Campus Cafe Quality Points.

• Create academic periods (semesters, quarters, trimesters, etc.) in Campus Cafe. These must match the academic periods you create in Blackboard. In Campus Cafe, you must include a semester for site 0, even if you don’t utilize such a site.

Required permissions

Configure Blackboard

Users (students and instructors)

The API will create user accounts in Blackboard for students and instructors who do not already exist in Blackboard based on a match of the Campus Cafe ID number to the Blackboard External ID number.

It is not possible to view the Blackboard External ID number in Blackboard.

If your institution already uses Blackboard, it is important to ensure all existing user accounts (students and instructors) have a Blackboard External ID that matches the individual's Campus Cafe ID number. This will prevent the creation of duplicate user accounts for the same individual. Uploading a person file allows updating of the external ID. Refer to Blackboard documentation.

Create Blackboard system role

This role will be assigned to the user that authorizes the connection between Campus Cafe and Blackboard.

1. Log in to Blackboard.

2. Click Admin.

3. In the Users area click System Roles.

4. Click Create Role.

5. In Role Name describe the role. For example, Campus Cafe.

6. In Role ID enter a few letters to associate with the role. For example, CC.

7. Click Submit.

8. Permit the following Privileges by checking the box next to them and then clicking Privileges > Permit Privileges.

   • Administrator Panel (Courses) > Courses

   • Administrator Panel (Courses) > Courses > Create Course

   • Administrator Panel (Courses) > Courses > Edit > Course Properties

   • Administrator Panel (Courses) > Courses > Edit > Enrollments

   • Administrator Panel (Courses) > Courses > Edit > Enrollments > Add Enrollment

   • Administrator Panel (Courses) > Courses > Edit > Enrollments > Delete Enrollments

   • Administrator Panel (Courses) > Courses > Edit > Enrollments > Edit Enrollment

   • Administrator Panel (Courses) > Courses > Merge

   • Administrator Panel (Courses) > Create/Modify Term

   • Administrator Panel (Courses) > Terms

   • Administrator Panel (Users) > Users

   • Administrator Panel (Users) > Users > Available/Unavailable

   • Administrator Panel (Users) > Users > Create User

   • Administrator Panel (Users) > Users > Edit > Change Password

   • Administrator Panel (Users) > Users > Edit > User Properties

   • Administrator Panel (Users) > Users > Edit > View Course Enrollments

   • Administrator Panel (Users) > Users > Set User's System Roles

   • Course/Organization Control Panel (Customization) > Properties

   • Course/Organization Control Panel (Users and Groups) > Users

   • Course/Organization Control Panel (Users and Groups) > Users > Change User's availability in Course/Organization

   • Course/Organization Control Panel (Users and Groups) > Users > Change User's Role in Course/Organization

   • Course/Organization Control Panel (Users and Groups) > Users > Remove Users from Course/Organization User management by Web Services

Create Blackboard user

This user will connect Campus Cafe and Blackboard. Campus Cafe recommends creating a dedicated user for this purpose. 

1. Log in to Blackboard.

2. Click Admin.

3. In the Users area click Users.

4. Click Create User.

5. In First Name enter a given name. For example, Campus.

6. In Last Name enter a surname. For example, Cafe.

7. In Username enter a username. For example campus_cafe.

8. In Password enter a complex password.

9. In Verify Password enter the same password.

10. Assign the System Role created earlier to the user as the Primary System Role.

11. Click Submit.

Configure Blackboard application

1. Log in to Blackboard.

2. Click Admin.

3. In the Integrations area click REST API Integrations.

4. Click Create Integration.

5. In Application ID enter 1f171441-0528-440c-8fe3-7fb38644efb2

6. Next to Learn User click Browse and select the user created earlier.

7. Next to End User select Yes.

8. Next to Authorized to Act As User select Yes.

9. Click Submit.

Configure Campus Cafe

After configuring Blackboard, you’ll need to set up Campus Cafe to make the connection.

Campus Cafe Web App configuration

1. Log in to Campus Cafe.

2. Go to Admin > Web App.

3. In Search enter Blackboard. One at a time, next to each of the below select the checkbox then click Edit Selected. In the Value enter the required information. You must complete all values.

   • BLACKBOARD_API_NAME - enter CC_BB

   • BLACKBOARD_AUTO_QUEUE_ITEM - If set to Y, the system will queue course sections created prior to the number of days specified in BLACKBOARD_COURSE_DAYS_ACTIVE_BEF_BEGIN for creation in Blackboard. The course sections will be created in Blackboard the number of days prior to the course start date specified in BLACKBOARD_COURSE_DAYS_ACTIVE_BEF_BEGIN

   • BLACKBOARD_BASE_URL - this is the URL of your Blackboard instance. Example: https://someUniversity.blackboard.com/

   • BLACKBOARD_COURSE_DAYS_ACTIVE_BEF_BEGIN - Enter a number representing days. Individual courses will be created in Blackboard only if created in Campus Cafe this many days or fewer prior to the course section start date.

   • BLACKBOARD_COURSE_TITLE_FORMAT - controls the name of the course created in Blackboard. Variables supported are @SEMESTER@, @COURSE_NUMBER@, @COURSE_SECTION@, @COURSE_TITLE@ and @SEMESTER_DESCRIPTION@. For example, for the Fall 2021 class Intro to Math, MTH101, Section 4 setting this value to @COURSE_NUMBER@ - @COURSE_SECTION@: @COURSE_TITLE@ in @SEMESTER_DESCRIPTION@ would create the section in Blackboard called "MTH101 - 4: Intro to Math in Fall 2021"

   • BLACKBOARD_CREATE_UPDATE_USER - A "Y" indicates that the connection will create a Blackboard user account for a student or faculty if one is not found in Blackboard
     already. A "N" will direct the connection not to create a Blackboard account. Without an account, the individual will not be able to be associated with a class in Blackboard.

   • BLACKBOARD_CUTOVER_SEMESTER - the Campus Cafe semester numerical code (e.g. 20210) of the first semester to sync between Campus Cafe and Blackboard

   • BLACKBOARD_EMAIL - email account that should receive Campus Cafe Blackboard Connector error notifications. Can enter multiple emails separated by commas. Required

   • BLACKBOARD_ENROLLMENT_DAYS_ACTIVE_AFT_END - Enrollments will stop syncing after the course end date if this is set to 0. Set a higher number for enrollments to stop syncing after the course end date. For example, set 5, enrollments would stop syncing file days after the course end date.

   • BLACKBOARD_ENROLLMENT_DAYS_ACTIVE_BEF_BEGIN - Enrollments will sync for registrations starting the entered number of days prior to the course start date. Registrations that occur prior to this date will not be processed in Blackboard.

   • BLACKBOARD_FILE_PATH - deprecated, leave blank

   • BLACKBOARD_INSTRUCTOR_ADD_ONLY - A "Y" indicates that when an instructor is disassociated with a class in Campus Cafe the instructor will not be removed from the Blackboard course. If your institution manually associates instructors or TAs with courses directly in Blackboard, enter "Y" otherwise these individuals will be removed from their Blackboard courses. A "N" indicates that when an instructor is disassociated with a class in Campus Cafe the instructor will be removed from the Blackboard course.

   • BLACKBOARD_INSTRUCTOR_ROLE_ID - the Blackboard Role ID for course teachers. Found in Blackboard by navigating to Admin >  Course/Organization Roles

   • BLACKBOARD_REMOVE_DOMAIN_FROM_USERNAME - Enter "Y" to remove from the Blackboard username the domain segment of the Campus Cafe username (e.g. bond@yourschool.edu would have a Blackboard username of bond). Enter "N" to preserve the full username inclusive of the domain.

   • BLACKBOARD_REMOVE_FROM_QUEUE_DAYS - How long to keep a technical log of sync actions. Campus Cafe recommends "30"

   • BLACKBOARD_STUDENT_ROLE_ID - the Blackboard Role ID for learners. Found in Blackboard by navigating to Admin > Course/Organization Roles

   • BLACKBOARD_TIMEZONE -  Enter the timezone of your institution. US/Eastern; US/Central; US/Mountain or US/Pacific Case sensitive

   • BLACKBOARD_UPDATE_USER_EMAIL - A "Y" indicates that if an individual's email changes in Campus Cafe, the connection should update the individual's email in Blackboard to match. A "N" will signal to Campus Cafe not to update emails in Blackboard.

   • BLACKBOARD_UPDATE_USERNAME - A "Y" indicates that the connection will replace the individual's Blackboard username with his or her Campus Cafe username if different. A "N" indicates that Campus Cafe will not attempt to change the individual's Blackboard username to match his or her Campus Cafe username. If your institution already has Blackboard in place and wishes to preserve existing Blackboard usernames, set this to "N".

4. Go to Admin > Refresh Data Cache.

Turn on connection

1. Log in to Campus Cafe.

2. Go to Admin > Custom Control.

3. In Search, enter Moodle. (The connector uses the same architecture as our Moodle connector.)

4. Next to Seq Num 1 click the pencil.

5. In Parameter Value 4 enter YYY

6. Click Save.

7. Contact Campus Cafe Support to turn on automated syncing.

Sync data between Blackboard and Campus Cafe

The API connection means that data can flow between Blackboard and Campus Cafe. Most institutions opt to have this data exchanged automatically on a regular schedule. However, you can also initiate a manual sync if you need the data exchanged earlier or need to address data discrepancies.

Automatic sync

After testing the connection, contact Campus Cafe support to request an automated sync. Changes made in Campus Cafe will typically update in Blackboard within a half hour.

If a transaction such as an enrollment, account creation or name change can’t be made in Blackboard, Campus Cafe sends an email to the email address listed in the Web App Config Blackboard_EMAIL. The email will only be sent for changes that fail. Other transactions that didn’t encounter issues will still process. Put another way, a single failure won’t prevent other transactions from processing.

Manual sync

Enrollments, course creations and changes to student/instructor names/emails made in Campus Cafe will be queued to send to Blackboard during the next scheduled automated sync. However, you can sync these immediately through a manual sync.

View pending data to sync

Campus Cafe monitors for transactions that need to be passed to Blackboard such as class registrations. Campus Cafe places these in a queue and processes the queue on an automated, regular schedule such as every 30 minutes.

You can view the queue to see what changes Campus Cafe plans to push to Blackboard.

1. Go to Registrar > LMS Management.

2. On the Blackboard Management tab next to Unprocessed Entries you can view the number of pending transactions.

3. Click Blackboard Queue to view details of the transactions awaiting processing. Each line represents a transaction, including the ID number of the student or instructor (if applicable), the semester, course and section. Lines without a Process Timestamp haven’t been sent to Blackboard.
   
   

   You can use the ID Number, Semester, Course and Section boxes at the top to find transactions associated with a specific person, semester, course or section.
   
   

   If you want to view only transactions that weren’t successful, select (check) Errors Only.
   
   

Manually sync data

You can tell Campus Cafe to send to Blackboard all enrollments for an entire semester, or a specific course or section regardless of when the students registered.

Manually push student enrollments to Blackboard

1. Go to Registrar > LMS Management.

2. On the Blackboard Management tab select the Semester that includes the enrollments you want to sync.

3. Optionally, to limit the enrollments all sections of a course, in Course enter the full course code. For example, MTH101. This will send enrollments for all sections of MTH100 in the semester you selected.

4. Optionally, to limit the enrollments to a single section of a course, in Section enter the section number. For example, 01.

5. Click Enqueue Enrollments to add the enrollments to the API queue.

6. In # to Manually Run enter the number that appears next to Unprocessed Entries.

7. Click Manually Run.

Manually push courses to Blackboard

You can tell Campus Cafe to create all courses for an entire semester or specific course or specific section.

1. Go to Registrar > LMS Management.

2. On the Blackboard Management tab select the Semester that includes the courses you want to sync.

3. Optionally, to limit course creations to all sections of a course, in Course enter the full course code. For example, ENG107.

4. Optionally, to limit course creations to a single section of a course, in Section enter the section number. For example, 01.

5. Click Enqueue Courses to add the courses to the API queue.

6. In # to Manually Run enter the number that appears next to Unprocessed Entries.

7. Click Manually Run.