Canvas Documentation

canvas/canvas-users.md

@@ -0,0 +1,59 @@
+---
+layout: page
+title: Canvas Users
+parent: Canvas
+nav_order: 3
+---
+
+# Canvas Users
+
+## Adding Users
+* [How do I add users?](https://community.instructure.com/en/kb/articles/660963-how-do-i-add-users-to-a-course#add-new-user)
+* [How do I add an admin?](https://community.instructure.com/en/kb/articles/661407-how-do-i-add-an-admin-to-an-account)
+* [SIS Import Format Documentation](https://developerdocs.instructure.com/services/canvas/sis/file.sis_csv)
+* SIS Sheet (Non-students):
+
+<div class="table-wrapper" tabindex="0" role="region" aria-label="User Data Table">
+
+| user_id | login_id | email | first_name | last_name | full_name | sortable_name | canvas_password_notification | declared_user_type | status | account_id | authentication_provider_id |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| UID:952109 | ball | ball@berkeley.edu | Michael | Ball | Michael Ball | Ball, Michael | TRUE | administrative | active | 1 | canvas |
+
+</div>
+
+Likely, you won't have the permissions to add users or promote to admin as linked above on the production bCourses Canvas instance, but these articles are still useful for use in the [Sandbox]({{ 'canvas/sandbox' | relative_url }}). For production bCourses, check out:
+* [How do I request an administrator role in bCourses?](https://berkeley.service-now.com/kb_view.do?sysparm_article=KB0011247)
+* [bCourses Roles and Permissions Summary Matrix](https://docs.google.com/spreadsheets/u/0/d/e/2PACX-1vSz0eGkR8ZobudN62PsXyohlO1gHX8_3oE28SOngVhyxHvzWbixMMHE76wYBtYUwn024rtWi6l0OcWL/pubhtml?pli=1)  Toggle between "course roles" and "account roles."
+* [bCourses Admin Roles and Permissions](https://berkeley.service-now.com/kb/en/bcourses-admin-roles-and-permissions?id=kb_article_view&sysparm_article=KB0011079)
+
+
+## Available IDs
+*  `User ID` / `UID` / `directory ID`: exposed as `sis_login_id` in Canvas. 
+    * Numeric, sequential, monotonically increasing from the date of creation of CalNet. 
+    * Immutable.
+    * Technically not FERPA procteded. 
+* `Student ID`: exposed as sis_user_id in Canvas for current students.
+    * Comes in many forms. Not all SIDs are 10 digits, but newly issued ones are.
+    * Immutable.
+    * FERPA protected. 
+* `Cnavas User ID`: created by Canvas for use internal to Canvas.
+    * Numeric.
+    * Immutable.
+* `CalNet ID`: a public facing user name. 
+    * String.
+    * Mutable. 
+* `Email`: often the same as CalNet ID. 
+    * String.
+    * Mutable.
+
+
+## Emails
+* We don't recommend using emails as primary keys. 
+    * While emails are unique, they are not a singular identifier of a person. A person may change their [CalNet ID](https://calnet.berkeley.edu/calnet-me/manage-my-calnet-account/you-change-your-calnet-id). In most cases, the updated CalNet ID is used, however the first CalNet ID is not deleted so it may still surface. 
+    * Additionally, people may set up email aliases. It can be annoying to detect when an alias is provided in place of a login email. 
+
+
+## Student ID Numbers in Canvas
+* Student IDs (SIDs) are found in Canvas under "SIS User ID" or "SIS ID." 
+* Sometimes, a SID is unavailable so the value will be "UID:*******" (Canvas user ID).
+* Because of this, do not assume that SIS User IDs are numeric.

canvas/dev-keys.md

@@ -0,0 +1,30 @@
+---
+layout: page
+title: Developer Keys
+parent: Canvas
+nav_order: 2
+---
+
+# Developer Keys
+
+From the [official Canvas documentation](https://developerdocs.instructure.com/services/canvas/oauth2/file.developer_keys): 
+
+> "Developer keys are OAuth2 client ID and secret pairs stored in Canvas that allow third-party applications to request access to Canvas API endpoints via the OAuth2 flow. Access is granted after a user authorizes an app and Canvas creates an API access token that’s returned in the final request of the OAuth2 flow.  
+> Developer keys created in a root account, by root account administrators or Instructure employees, are only functional for the account they are created in and its sub-accounts... By scoping the tokens, Canvas allows root account administrators to manage the specific API endpoints that tokens issued from a developer key have access to."
+
+Said another way, the API server (Canvas) validates third-party apps (domain+redirect URI) and API key/API secret, and makes a request. Requests can authenticate users and provide information available on Canvas.
+
+## Use in Development
+You can complete development work and test dev keys on the [Sandbox]({{ 'canvas/sandbox' | relative_url }}). 
+
+Individual persons do not need individual dev keys; you can (and should) re-use dev keys within development groups. For example, one dev key has been used by multiple iterations of CS61A and other course staff for development work on [sections]({{ 'course-software/seamless-learning/sections' | relative_url }}) for multiple semesters. When the domain, routes (redirect URIs) and scopes are the same, you can (and should) share the use of a single dev key.
+
+We recommend that scoped keys are turned on even during development. Keys must be scoped in production, so doing this step early will decrease headaches later. If you have separate development efforts on the same app happening simultaneously that require different scopes, you may want to create separate dev keys. However, please keep dev keys created to a minimum. 
+
+## Use in Production
+Once you have verified your workflow in your development environment using a dev key for the Sandbox AND you've determined a minimal set of scopes, you're ready to request use in production. A staff (non-student) or faculty member should reach out to bcourseshelp AT berkeley DOT edu.  The process of granting a production key includes Docusign. 
+
+## More on OAuth2
+[Canvas Oauth2 Overview](https://developerdocs.instructure.com/services/canvas/oauth2/file.oauth)
+
+If something is going wrong with authentication, make sure that what is listed in the developer key is correct. Redirect URIs must match **exactly.**

canvas/index.md

@@ -10,3 +10,6 @@ nav_order: 3
 * [Community Page](https://community.instructure.com/en/categories/canvas)
 * [Resource Page](https://community.instructure.com/en/kb/canvas-resource)
 * [Developer Documentation](https://developerdocs.instructure.com/services/canvas)
+
+## More Questions? 
+You can ask on the `#canvas-dev-support` channel in EECS Crossroads for help from CDSS faculty, staff, and TAs. You can also open a ServiceNow ticket by emailing bcourseshelp AT berkeley DOT edu.

canvas/sandbox.md

@@ -0,0 +1,12 @@
+---
+layout: page
+title: Sandbox
+parent: Canvas
+nav_order: 1
+---
+
+# Canvas Sandbox
+We have access to a [Canvas sandbox environment](https://ucberkeleysandbox.instructure.com/login/canvas). This is a separate, development Canvas instance from the production [bCourses](https://bcourses.berkeley.edu/) Canvas instance. This separate environment allows for fast development work, not gated by communication with the bCourses team. 
+
+To be added to the sandbox, message in the `#canvas-dev-support` channel in EECS Crossroads. Be sure to include what kind of development work you're planning on so we can add you as an admin if necessary. 
+