Blackboard Learn (LMS)

About Blackboard Learn API

Campus Cafe provides an application program interface (API) to the Blackboard Learn learning management system. Clients must contract directly with Anthology for use of the Blackboard platform. 

The API supports the following sync functions:

• When a student is enrolled (registered) in a course in Campus Café, the connector automatically pushes the enrollment to Blackboard. When a student is dropped from a course in Campus Café, the connector prompts Blackboard to unenroll the student in Blackboard  Registration actions flow only from Campus Cafe to Blackboard. A registration change made in Blackboard will not update Campus Cafe.
• If a student is registered for a course in Campus Cafe and the course does not exist in Blackboard, the connector will create the course in Blackboard.
• Changes made to course titles in Campus Cafe will be applied to the Blackboard course.
• The connector will create a Blackboard user for a student who is registered for a class and does not already have a Blackboard account. The connector will also create a Blackboard user for an instructor of a course who does not already have a Blackboard account.
• The connector will apply changes to student/instructor names and email addresses that occur in Campus Cafe to the corresponding user's name and email in Blackboard.

The API does not support importing final course grades from Blackboard to Campus Cafe.

There are no student holds that impact the API and Blackboard connection.

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 briefly describe the role (e.g. Campus_Cafe)
6. In Role ID put a letter to associate with the role (e.g. 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 (e.g. Campus)
6. In Last Name enter a surname (e.g. Cafe)
7. In Username enter a username (e.g. 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 Learn

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 Web App Config

1. Log in to Campus Cafe
2. Navigate to Admin > Web App Config
   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 Café 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".
3. Refresh the cache by navigating to Admin > Refresh Data Cache > reload data

Configure Campus Cafe Custom Control

1. Log in to Campus Cafe
2. Navigate to Admin > Custom Control Maintenance
3. Search for MOODLE (the API uses the same underlying technology as Moodle)
4. Next to ProgramId MOODLE, Seq Num 1 click the pencil
5. In Parameter Value 4 box enter YYY
6. Click Save

Manual Sync

Enrollments, course creations and changes to student/instructor names/emails made in Campus Cafe will be queued to send to Blackboard. To send these changes to Blackboard for processing, launch the manual sync.

Permission #1236 is required to access this function.

View number of pending changes

1. Navigate to Registrar > LMS Management
2. The number next to Unprocessed Queue Entries Count indicates the number of changes waiting to sync. This may represent changes to an individual's name, enrollments, course creations, etc.

Queue enrollments and send to Blackboard

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

1. Navigate to Registrar > LMS Management
2. In the Semester Box enter the Campus Cafe semester code (e.g. 202110)
3. Optionally, to limit the enrollments all sections of a course, in the Course box enter the full course code (e.g. MTH100)
4. Optionally, to limit the enrollments to a single section of a course, in the Section box enter the section number (e.g. 14)
5. Click Add Enrollments to API Queue

Queue courses to be created in Blackboard

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

1. Navigate to Registrar > LMS Management
2. In the Semester Box enter the Campus Cafe semester code (e.g. 202110)
3. Optionally, to limit course creations to all sections of a course, in the Course box enter the full course code (e.g. MTH100)
4. Optionally, to limit course creations to a single section of a course, in the Section box enter the section number (e.g. 14)
5. Click Add Courses to API Queue

Process all pending changes

This queue represents all changes (enrollments, changes to names, etc.) made in Campus Cafe that are waiting to be sent to Blackboard.

1. Navigate to Registrar > LMS Management
2. The number next to Unprocessed Queue Entries Count indicates the number of changes waiting to sync
3. Click Click Here to Manually Run queue processor for 100 entries
4. If necessary, click Click Here to Manually Run queue processor for 100 entries again to process the next 100 entries and repeat until nothing remains in queue

Automatic Sync

After testing the connection, contact Campus Cafe support to request a near real-time connection be activated if desired. Changes made in Campus Cafe will typically update in Blackboard within a half hour.

Upon Sync Error

If a change cannot be made in Blackboard, the system will send 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 in the queue that did not encounter issues will still process. Put another way, a single failure will not prevent other changes from processing.

Queue History Log

The queue history log shows the results of synchronization attempts between Campus Cafe and the LMS. For example, if a student's enrollment is not initiated in the LMS, the history log will show why.

Access the log

1. Log in to Campus Cafe
2. Navigate to Registrar > LMS Management
3. Click Queue History Log

First time it sets up a course it will set up the term in Blackboard

How do we update student external ID numbers in Blackboard

https://help.blackboard.com/Learn/Administrator/Hosting/System_Integration/SIS/SIS_Integration_Legacy/SIS_Feed_File_Headers_and_Object_Types