Integrate Canvas LMS

Deploy the Canvas LMS integration to view courses, create course announcements, manage course enrollment, and view student’s grades.

• As a student, view courses and their related details.
• As a teacher, create a course announcement, view/add course members, and view student’s grades.

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 the out-of-the-box microapps for Canvas LMS, see Use Canvas LMS microapps.

Review prerequisites

After you set up this integration with Canvas LMS, you will need these artifacts to add the integration in Citrix Workspace Microapps:

• Base URL: https://{host_name}.com
• Authorization URL: https://{host_name}.com/login/oauth2/auth
• Token URL: https://{host_name}.com/login/oauth2/token
• Client ID: The client ID is the string representing client registration information unique to the authorization server.
• Client secret: The client secret is a unique string issued when setting up the target application integration.

Note:

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.

Configure Citrix Gateway to support single sign-on for Canvas LMS 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.

Enable APIs

Canvas APIs are enabled by default. You need a Canvas Partner Account to access the APIs. The number of API requests that can be made to specific resources is limited. We therefore recommend API limit throttling, as described in this article: https://canvas.instructure.com/doc/api/file.throttling.html.

Create a New Service Account

The integration requires regular access to your Canvas LMS instance, so we recommend creating a dedicated user account. This account must have the following permissions: Full administrator privileges

It is recommended to have a Canvas Partner account: https://www.instructure.com/canvas/become-partner.

Configure OAuth server

Configure the OAuth server to read data through the Canvas integration.

1. Sign in to https://{host_name}.com/accounts as an administrator.
2. Select the account that you want to integrate.
3. Select Developer Keys and the select + Developer Key.
4. Select + API Key and complete the required fields including Key Name, Owner Email, Redirect URIs.
5. Enter the following authorized redirect URLs for this app in the Redirect URL field: https://{yourmicroappserverurl}/admin/api/gwsc/auth/serverContext
6. Make the Client Credentials Audience as Canvas and click on Save.
7. Make the State as ON.
8. Copy the ClientID and Secret from the details. You use these values for Service Authentication while configuring the integration.

Configure OAuth client

Configure the OAuth client to write data back through the Canvas integration.

1. Sign in to https://{host_name}.com/accounts as an administrator.
2. Select the account that you want to integrate.
3. Select Developer Keys and the select + Developer Key.
4. Select + API Key and complete the required fields including Key Name, Owner Email, Redirect URIs.
5. Enter the following authorized redirect URLs for this app in the Redirect URL field: https://{yourmicroappserverurl}/admin/api/gwsc/auth/serviceAction/callback
6. Make the Client Credentials Audience as Canvas and click on Save.
7. Make the State as ON.
8. Copy the ClientID and Secret from the details. You use these values for Service Action Authentication while configuring the integration.

Add the integration to Citrix Workspace Microapps

Add the Canvas LMS integration to Citrix Workspace Microapps to connect to your application. This delivers out-of-the-box microapps with pre-configured notifications and actions which 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 Canvas LMS tile.
3. Enter a name for the integration.

4. Enter Connector parameters:

   • Enter the instance Base URL: https://{host_name}.com
   • 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 Authorization code from the Grant type menu.
   2. The Authorization URL is prefilled: https://{host_name}.com/login/oauth2/auth.
   3. The Token URL is prefilled: https://{host_name}.com/login/oauth2/token.
   4. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this when you configure the OAuth server.
   5. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration. You collect this 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 code from the Grant type menu.
   3. The Authorization URL is prefilled: https://{host_name}.com/login/oauth2/auth.
   4. The Token URL is prefilled: https://{host_name}.com/login/oauth2/token.
   5. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collected this value when you configure the OAuth client.
   6. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration. You collected this value when you configure the OAuth client.
7. Enable the Request rate limiting toggle. Enter 500 for Number of requests and 1 minute for Time interval.
8. Leave Request timeout empty.
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 Canvas button of My Grades page.

Follow these steps:

1. From the Microapp Integrations page, navigate to the Canvas LMS 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 Canvas button component, 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}/courses/\{\{id\}\}/grades
6. 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 as shown in the following list. For each Endpoint listed in the following table, you must change the Data type in the menu for the given attribute.

Table	Column	Data type
Assignments	points_possible	Binary
Assignments	description	Binary
Grades	current_grade	Binary

Follow these steps:

1. From the Microapp Integrations page, select the menu next to the Canvas LMS integration, and then Edit. The Data Loading screen opens. If not, select Data Loading from the left side navigation column.
2. For each endpoint, select the menu next to the endpoint and Edit.
3. 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.
4. 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.
5. Repeat this procedure 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.

Note:

We recommend setting the Full Synchronization interval to every 8 hours and Incremental Synchronization interval as hourly.

For more details of API endpoints and table entities, see Canvas LMS connector specifications.

Note:

Due to a limit in the number of API calls, incremental synchronization is set up to retain only Announcements. Remaining endpoints are triggered as part of full synchronization.

Use Canvas LMS microapps

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

Create Course Announcement: Teachers create an 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.

My Courses: View course announcements, assignments, and course files.

Notification or Page	Use-case workflows
Course Invitation notification	When a student is invited to a course, they receive a notification.
New Course Announcements notification	When there is a new announcement for a course, students enrolled to the course receive a notification.
New Course Announcements (Future) notification	When there is a new announcement for a course with a future publish date, students enrolled to the course receive a notification.
Accept/Reject Invitation page	Provides a read-only view of a course invitation with options to Accept or Reject.
List Courses page	Allows users to view their list of enrolled courses.
Course Details page	Allows users to view a list of announcements and files of a course.
Announcement Details page	Allows users to view the course announcement and its details.
Assignment Details page	Allows users to view an assignment and its details.
File Details page	Allows users to view and download files.

My Grades: Students view their course grades.

Notification or Page	Use-case workflows
New Grades notification	When new grades are posted for a course, students enrolled in the course receive a notification.
List Courses page	Allows users to view their list of enrolled courses.
My Grades page	Allow users to view the grades of the selected course.

Teacher’s View: Teachers view and add course members and view students.

Notification or Page	Use-case workflows
List Courses page	Allows teachers to view a list of available courses.
List Members page	Allows teachers to view a list of members enrolled for a course, with an Add button that navigates to the Add User page.
Member Details page	Allows teachers to view the grades and related details of members of a course.
Add User page	Allows teachers to add a student to the selected course.