Canvas (LMS)

Canvas Connector Introduction

Campus Café offers a connector for the learning management system Canvas. Customers must establish a separate contract with Canvas by Instructure.

The connector supports the following sync functions:

• When a student is enrolled (registered) in a course in Campus Café, the connector automatically pushes the enrollment to Canvas. When a student is dropped from a course in Campus Café, the connector prompts Canvas to unenroll the student in Canvas. Registration actions flow only from Campus Cafe to Canvas. A registration change made in Canvas will not update Campus Cafe.
• If a student is registered for a course in Campus Cafe and the course section does not exist in Canvas, the connector will create the course section. If the Canvas course does not exist, the connector will create the course as well. 
• Changes made to course titles in Campus Cafe will be applied to the Canvas course.
• The connector will create a Canvas user for a student who is registered for a class and does not already have a Canvas account. The connector will also create a Canvas user for an instructor of a course who does not already have a Canvas account.
• The connector supports the ability to import mid-term/deficiency grades from Canvas to Campus Cafe.
• The connector supports the ability to import final course grades from Canvas to Campus Cafe.
• 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 Canvas.
• The connector will deactivate the Canvas enrollments of students with a hold in Campus Cafe if the hold is configured to do so. The connector will reactivate the Canvas enrollments when the hold is removed.

Canvas Configuration

The integration requires the following configuration be completed in Canvas.

Semesters

Semesters must be established in Canvas prior to any sync functions occurring. Campus Cafe recommends creating Canvas semesters as far out in the future as possible.

1. Log in to Canvas
2. Click Admin
3. Click the desired account
4. Click Terms
5. Click Add New Term
6. In the Term Name box enter a description of the term (e.g. Spring 2021)
7. In the SIS ID enter the numerical code of the Campus Cafe term (e.g. 202130)
8. Click Add Term

Users

Canvas User SIS ID

If your institution already uses Canvas, it is important to ensure all existing user accounts (students and instructors) have a Canvas SIS ID that matches the individual's Campus Cafe ID number. This will prevent the creation of duplicate user accounts for the same individual.

Attaching an SIS ID to Existing Canvas User

1. Individually in Canvas via Admin > Your School > People, consult Canvas help documentation
2. Through a CSV file import, consult Canvas help documentation at https://canvas.instructure.com/doc/api/file.sis_csv.html
   Campus Café provides a pre-defined report for a user upload. Students may be selected based on current degree status; faculty in the report are limited to those coded as active on the faculty detail screen (Person Selected > Faculty info). The report Canvas User SIS Import is available in Base Reports under the Administrator Reports folder.

Auto Creation of Canvas Users

When a student is registered for a class in Campus Cafe, the connector determines if the student has an account in Canvas by matching the Campus Cafe ID number to the Canvas SIS ID. If a match is not found, the connector will automatically create a Canvas account for the student. The username will be their Campus Cafe username.

When an instructor is associated with a class in Campus Cafe, the connector determines if the instructor has an account in Canvas by matching the Campus Cafe ID number to the Canvas SIS ID. If a match is not found, the connector will automatically create a Canvas account for the instructor. The username will be their Campus Cafe username.

Courses and course sections

Courses are the virtual classroom where all the content resides and where student users can learn and interact with instructors and peers.

Sections in Canvas are a group of students that have been organized for administrative purposes. When users are enrolled in a course, they are actually enrolled in one of the sections of that course. As such, Canvas requires each course - “course shell” - contain at least one section. It is possible to place more than one section in course, but it is not possible to put sections within sections. All sections of a course share the same content.

If a course is taught by one instructor, sections can remain under one course. However, if each section is taught by a different instructor, those sections will need to be housed under separate courses.

If your institution already uses Canvas, it is important to ensure all existing course sections have a Canvas SIS ID. This will prevent the creation of duplicate course sections. The SIS ID for course section in Canvas is constructed from the Campus Cafe Semester Code, Course Number, and Course Section with a tilde between each field (Term~CourseNumber~CourseSection). For example, the course CIS123, Section 1 offered in the term 202010 would be “202010~CIS123~1”.

Associate existing course section with SIS ID

1. In Canvas, navigate to the course
2. Click Settings
3. Click Sections
4. Click the Section
5. Click Edit Section
   
6. In the SIS ID box enter the Campus Cafe identifier constructed from the Term, Course Number, and Course Section with a tilde between each field (Term~CourseNumber~CourseSection). For example, the course CIS 123, Section 1 offered in the term 202010 would be “202010~CIS123~1”.
7. Click Update Section

Multiple Campus Cafe Course Sections Associated with Single Canvas Course

Your institution may combine students from multiple discrete Campus Cafe class sections, each with their own roster, meeting times, etc., into one Canvas course with sections under it. This is often done so the instructor does not need to independently maintain the same academic content across multiple Canvas courses. 

Such classes require special handling.

1. In Canvas, set the SIS ID of the section that will hold multiple Campus Cafe sections to something not used by any other Canvas section
2. In Campus Cafe navigate to the course section (Registrar > Course Finder > Magnifying glass next to course)
3. Click the Codes tab
4. In the LMS Course Code Override box enter the SIS ID number you entered in Canvas
5. Repeat steps 2-4 for each Campus Cafe section
6. Click Save

Auto Creation of Courses and Course Sections

When a course is scheduled in Campus Cafe, the connector will check if a course section with the SIS ID exists in Canvas. If not, the course section will be created in Canvas. If there is no course to associate with the section, a course will be created in Canvas.

Exclude Course and its Enrollments from the Integration

A specific course may be excluded from the integration. The course will not be created in Canvas and students enrolled in the course in Campus Cafe not enrolled in Canvas. 

To exclude a course:

1. In Campus Cafe navigate to the course section (Registrar > Course Finder > Magnifying glass next to course)
2. Click the Codes tab
3. Check the Exclude From LMS Integration box
4. Click Save

Create Canvas Role

A role in Canvas is required to join to the service account user that will serve as the bridge between Canvas and Campus Café.

1. Log in to Canvas
2. Click Admin
3. Click the desired account
4. Click Permissions
5. Click Account Roles
6. Click Add Role
7. Name the role (e.g. Campus Café API)
8. Click Save
9. Ensure the account permissions enabled for the below
   • Course Content - view
   • Courses - view list
   • Grades - view all grades
   • Mange Course Sections, including Course Sections - add; Course Sections - delete; Course Sections - edit
   • Mange Courses, including Courses - add; Courses - conclude; Courses - delete; Courses - publish; Courses - reset
   • Permissions - manage
   • SIS Data – manage
   • SIS Data – read
   • Users - Students, including Students - add; Students - remove
   • Users - Teachers, including Teachers - add; Teachers - remove
   • Users - manage login details
   • Users - manage students in courses
   • Users - view list

Create Canvas Service User

This user will act as the bridge between Canvas and Campus Café.

1. Click Admin
2. Click the desired account
3. Click Settings
4. Click the Admins tab
5. Click +Account Admins
6. In the Add More box, choose the role created earlier
7. Enter an email address to associate with the account
8. Click Continue
9. Click OK Looks Good, Add This 1 User

Create Canvas Developer Key

The next step to configure Canvas requires an administrative account to complete.

1. Log in to Canvas
2. Click Admin
3. Choose an account
4. Click Developer Keys
5. Click the + Developer Key and click +API Key to bring up the developer key creation dialog
6. Enter a descriptive key name (e.g. Campus Café)
7. Enter an email address associated with the service account created
8. In the Redirect URIs box enter
   <Campus Café host URL>/cafeweb/CanvasOauth2Callback
   Example: https://abc-web.scansoftware.com/cafeweb/CanvasOauth2Callback
9. Click Save
10. Canvas should return to a list of Developer Keys now including the key just created
11. Locate the developer ID, which is a string of numbers to the right of the owner email. Copy for future use.
12. Click the Show Key button to reveal the secret key. Copy for future use. Keep the Client Secret secure for security purposes.
13. Under the State column, click On

Campus Café Configuration

Campus Café requires configuration to manage enrollments in Canvas. This is accomplished by setting the developer key and related information.

Campus Cafe Class Drop Configuration 

The connection to Campus Cafe runs on a schedule where it processes any enrollment changes made since the last run. As such, the system requires that records of drops and replacements (swaps) be preserved. 

1. Navigate to Admin > Custom Control Maintenance
2. Local ProgramID WEBDROPLGC
3. Click the pencil next next to WEBDROPLGC Seq 1 Parm 1
4. In Parameter Value 1 enter Y
5. In Parameter Value 2 enter Y
6. Click Save
7. Refresh the cache by navigating to Admin > Refresh Data Cache > reload data

Configure Course End-Times and Nickname/Preferred Name Settings

The connection allows for the adjustment of course end-times.  Default is set to 0:00 z time; however, this may be adjusted from 0 to 2359 to account based on when you want the courses to end in Brightspace.  Additionally, the integration may now be configured to bring in the Campus Cafe Nickname as the Preferred Name in Canvas.  If set to Y and no Nickname exists in Campus Cafe, the First Name will be sent as the Preferred Name.

Configuring Course End-Times

1. Log in to Campus Cafe
2. Navigate to Admin > System Setup > Custom Control
3. Locate ProgramID MOODLE
4. Click the pencil icon next to Moodle Seq 2 Parm 9
5. Update the course end-times (HHMM) to a value from 0 to 2359
   1. Default is set to 0

Configuring Nickname Preferences

• Log in to Campus Cafe
• Navigate to Admin > System Setup > Custom Control
• Locate ProgramID MOODLE
• Click the pencil icon next to Moodle Seq 2 Parm 10
• Enter Y to send Nickname as Preferred Name
• Enter N to ignore Nickname field in Campus Cafe and only send First Name as preferred name
  • Default is set to N

Holds

Holds in Campus Cafe are placed on students to prevent certain actions, such as seeing a transcript. A hold may be configured to tie to permission 1245. Students with a hold configured as such will have their Canvas enrollments deactivated. Upon hold removal, the Canvas enrollments will be reactivated.

Campus Cafe Web App configuration

The next step in configuring the Canvas Connector.

1. Log in to Campus Café
2. Navigate to Admin > Web App
3. In the search box, enter Canvas to return the relevant values and update as follows:
   CANVAS_API_NAME - Enter CC_CNVS
   CANVAS_AUTO_QUEUE_ITEMS - If set to Y, the system will queue course sections created prior to the number of days specified in CANVAS_SECTION_DAYS_ACTIVE_BEF_BEGIN for creation in Canvas. The course sections will be created in Canvas the number of days prior to the course start date specified in CANVAS_SECTION_DAYS_ACTIVE_BEF_BEGIN.
   CANVAS_BASE_URL – This is the URL of your Canvas instance. Example: https://someUniversity.instructure.com (Caution, do not include a / at the end)
   CANVAS_CLIENT_ID – Client ID is the Developer ID number generated during the creation of a developer key in Canvas. Found on the Developer Keys page in Canvas.
   CANVAS_CLIENT_SECRET – Key generated during the creation of a developer key in Canvas. Found on the Developer Keys page in Canvas. Note that the Client Secret is labeled “key” and will be hidden unless clicked.
   CANVAS_COURSE_TITLE_FORMAT - Controls the name of the course section created in Canvas. 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 Canvas called "MTH101 - 4: Intro to Math in Fall 2021"
   CANVAS_CREATE_UPDATE_USER - "Y" indicates that the connection will create a Canvas user account for a student or faculty if one is not found in Canvas already. "N" will prevent the connection from creating a Canvas account. Without an account, the individual will not be able to be associated with a class in Canvas.
   CANVAS_CUTOVER_SEMESTER - Campus Cafe semester numerical code (e.g. 20210) of the first semester to sync between Campus Cafe and Canvas.
   CANVAS_EMAIL – Email account that will receive Campus Café Canvas Connector error notifications. Multiple emails may be entered, separated by commas. Required
   CANVAS_ENROLLMENT_DAYS_ACTIVE_AFT_END - Number of days enrollments will stop syncing following the end of a course. If set to 0, enrollments will stop syncing at the course end date. Set a higher number for enrollments to stop syncing after the course end date. For example, if set to 5, enrollments will stop syncing five days after the course end date.
   CANVAS_ENROLLMENT_DAYS_ACTIVE_BEF_BEGIN - Number of days enrollments will start syncing prior to the course start date. 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 Canvas.
   CANVAS_FILE_PATH – Server location of a file that is used to store token information. Use “./token.obj” by default. It is possible to use another location for special circumstances.
   CANVAS_INSTRUCTOR_ADD_ONLY - "Y" indicates that when an instructor is disassociated with a class in Campus Cafe the instructor will not be removed from the Canvas course. If your institution manually associates instructors or TAs with courses directly in Canvas, enter "Y" otherwise these individuals will be removed from their Canvas courses. "N" indicates that when an instructor is disassociated with a class in Campus Cafe the instructor will be removed from the Canvas course.
   CANVAS_MAX_RETRY_ATTEMPTS - Enter a zero "0." This field is no longer used. Previously, specified the number of times the connector would attempt a sync action.
   CANVAS_REDIRECT_URI – Enter the same value that was input in the developer key dialog (see above). For example: https://abc-web.scansoftware.com/cafeweb/CanvasOauth2Callback
   CANVAS_REMOVE_DOMAIN_FROM_USERNAME - Enter "Y" to remove the domain segment of the Campus Cafe username (e.g. bond@yourschool.edu would have a Canvas username of bond) from the Canvas username. Enter "N" to preserve the full username, including the domain.
   CANVAS_REMOVE_FROM_QUEUE_DAYS - Number of days to keep a technical log of sync actions. Campus Cafe recommends "30."
   CANVAS_RETRY_MINUTES - Number of minutes the connector will attempt a sync action if the first attempt fails. Campus Cafe recommends "30."
   CANVAS_SECTION_DAYS_ACTIVE_BEF_BEGIN - Enter a number representing days. Individual course sections will be created in Canvas only if created in Campus Cafe this many days or fewer prior to the course section start date.
   CANVAS_TIMEZONE - Time zone of your institution. US/Eastern; US/Central; US/Mountain or US/Pacific Case sensitive
   CANVAS_UPDATE_USER_EMAIL - "Y" indicates that if an individual's email changes in Campus Cafe, the connection should update the individual's email in Canvas to match. "N" will signal to Campus Cafe not to update emails in Canvas.
   CANVAS_UPDATE_USERNAME - "Y" indicates that the connection will replace the individual's Canvas username with his or her Campus Cafe username if different. "N" indicates that Campus Cafe will not attempt to change the individual's Canvas username to match his or her Campus Cafe username. If your institution already has Canvas in place and wishes to preserve existing Canvas usernames, set this to "N."
4. Contact Campus Café and request a server restart to load these values or wait overnight for the server to reboot automatically.

Campus Cafe Custom Control Configuration

1. Navigate to Admin > Custom Control Maintenance
2. In the search box, enter Moodle (Campus Café leverages the same technology to connect both Canvas and Moodle, hence the Moodle name)
3. Locate the control with ProgramId Moodle, Seq Num 1 and Parm 3 and click the pencil icon to edit
4. In the Parameter Value 3 box enter "YYY"
5. Click Save and back

Create Canvas token

For the sync to work, a pair of tokens, the Access Token and Refresh Token, is created. Canvas uses OAuth2 to authorize web service operations.

Generate the token

1. Log in to Campus Café with an account that possesses permission 293, which enables access to the Custom Control Maintenance button
2. Once logged into Campus Café, proceed to the following URL, in a separate tab/window: <hostURL>/cafeweb/AuthorizeCafeWithCanvas
   For example: https://abc-web.scansoftware.com/cafeweb/AuthorizeCafeWithCanvas
3. Click on the Request Authorization hyperlink to authorize Campus Café with Canvas.
4. The Canvas log in page will appear. Log in with an account with sufficient privileges (see above) to perform enrollments in Canvas.
5. To create the token, click on “Authorize”

Manual Sync

Enrollments, course creations and changes to student/instructor names/emails made in Campus Cafe will be queued to send to Canvas. To send these changes to Canvas 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 Canvas

You can direct Campus Cafe to send all enrollments for an entire semester or specific course or specific section to Canvas 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 Canvas

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 Canvas.

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 Canvas within a half hour.

Upon Sync Error

If a change cannot be made in Canvas, the system will send an email to the email address listed in the Web App Config CANVAS_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

Canvas Final Grade Import

Campus Café offers a course final grade synchronization feature in the Campus Café Canvas integration. This allows a user with the Final Grades File Import permission (permission 1169) to access the final grade import web page.

Prerequisites

Set grade override rule

To accommodate different school grade determination policies, Campus Café includes a custom control setting to modify the behavior of the final grade sync.

1. Navigate to Admin > Custom Control Maintenance
2. In the search box, enter Moodle (Campus Café leverages the same technology to connect both Canvas and Moodle, hence the Moodle name)
3. Locate the control with ProgramId Moodle, Seq Num 2 and Parm 6 and click the pencil icon to edit
4. In the Parameter Value 6 box enter set the value to ‘Y’ to overwrite grades that have already been set in Campus Café when running the Canvas sync. This setting will not overwrite ‘I’ (for incomplete) or ‘W’ (for withdrawal) grades set in Campus Café. When the setting is set to ‘N’ or is left at the default, once a grade is set in Campus Café, it is not overwritten during subsequent executions of the sync for the same semester.
5. Click Save and back

Sync grades

1. Navigate to Registrar > LMS Management
2. Click Final Grade Synchronization 
3. In the Semester to Synchronize choose the semester in which to import grades from Canvas to Campus Cafe
4. Click Synchronize. 

Troubleshooting Enrollment

If enrollments are not syncing between Campus Cafe and Canvas, below is a guide for identifying the possible issue.

1. Are enrollment syncing for any classes or students? If so, the issue is likely unique to the class or student. If not, check the custom control is set to allow syncs and continue.
2. Does the student have a username and password in Campus Cafe?
3. Does the student have his or her Campus Cafe ID as the SIS ID for his or her Canvas account?
4. Does the course contain a class section with the proper SIS ID? (In the form of the term code ~ course code ~ course section)