Updated configuration guide and educator guide

docs/CONFIGURATION_GUIDE.md

@@ -1,19 +1,32 @@
-## Configuration Guide
+# Configure the tool
 
-The following guide shows the steps to configure Moodle LMS to work with the Assessment App. Please, check if you obtained the following parameters from the Platform Registration Tool:
+The following guide shows the steps to configure several popular LMS to work with the Assessment Application. If your LMS is not listed here, consult your LMS vendor on how to configure LTI application. Regardless of the LMS, the typical workflow should remain the same:
 
-* Login URL
-* Launch URL
-* Domain URL
-* Public Key
-* Public JWK
-* Public JWK Set URL
+1. Obtain parameters from the deployed  LTI Assessment Application’s registration page
+2. Configure an LTI tool on the LMS using the parameters from step 1.
+3. Obtain parameters from the configured LTI tool.
+4. Configure the LTI Assessment Application using the parameters from step 3.
+
+By now, you should've obtained the following parameters from the LTI Assessment Application’s registration page. If not, follow the [deployment guide](./DEPLOYMENT_GUIDE.md) to deploy Assessment Application LTI application and obtain the following parameters from the registration page.
+
+- Login URL
+- Launch URL
+- Domain URL
+- Public Key
+- Public JWK
+- Public JWK Set URL
 
 If you are not the one who deployed the application, you need to obtain the parameters from that person.
 
-Complete the following steps to configure the Assessment App in Moodle:
+The configuration steps slightly differ depending on the LMS you are using. In general, they will involve registering the Assessment Application as an external tool in the LMS and registering the parameters of external tool back in the Assessment Application's registration page. The following examples show how to configure Assessment Application with three of the popular LMS.
 
-### Moodle LTI 1.3
+- [Moodle](#Moodle-LMS)
+- [Canvas](#Canvas-LMS)
+
+
+## Moodle LMS
+
+LTI 1.3
 
 1. Open your LMS and sign in with the admin account.
 2. Click **Site administration** from the left navigation pane.
@@ -86,3 +99,89 @@ The following steps show how to register the parameters back in the Platform Reg
 4. Click **Save Registration**.
 
 The Assessment App is now configured on Moodle LMS and educators will be able to use it.
+
+
+## Canvas LMS
+
+The following steps show how to configure an LTI tool on a Canvas LMS.
+
+### LTI 1.1
+
+At this time, we do not support LTI 1.1 with Canvas LMS.
+ 
+### LTI 1.3
+
+The LTI 1.3 and LTI Advantage platform requires a tool to be initially configured in the Developer Keys page, followed by being added to an account or course. First, configure the tool in the Developer Keys page.
+
+1. Open your LMS and sign in with the admin account (Users who want to manage Developer Keys must have the **Developer Keys - manage** permission).
+2. Click **Admin** from the left navigation pane, then click the name of the account.
+3. Click **Developer Keys**.
+4. Click **+Developer Key** and click **+LTI Key**.
+5. Enter the following information:
+ * **Key Name**: give the tool a name of your choice. For example: "Assessment Application".
+ * **Redirection URIs**: enter the "Launch URL" from Assessment application’s registration page. 
+ * **Method**: select **Manual Entry**
+ * **Title**: give the tool a title.
+ * **Description**: give the tool a description.
+ * **Target Link URI**: enter the "Launch URL" from Assessment application’s registration page.
+ * **OpenID Connect Initiation URI**: enter "Login URL" from the Assessment application’s registration page.
+ * **JWK Method**: select **Public JWK URL**
+ * We recommend to select the **Public JWK URL** as **JWK Method**. 
+ * If you are trying to connect to a locally hosted Assessment Application, you will need to use the **JWK Method** method. 
+ * **Public JWK URL**: enter "Public JWK Set URL" from the Assessment Application’s registration page.
+ * If you select **Public JWK**, instead of **Public JWK URL**, as **JWK Method**, you can enter the "Public JWK" from the Assessment Application's registration page instead of the "Public JWK Set URL".
+![Config.Canvas.2](/images/Config.Canvas.2.png). 
+6. Under **LTI Advantage Services**, enable the following options:
+ * Can create and view assignment data in the gradebook associated with the tool.
+ * Can view assignment data in the gradebook associated with the tool.
+ * Can view submission data for assignments associated with the tool.
+ * Can create and update submission results for assignments associated with the tool.
+ * Can retrieve user data associated with the context the tool is installed in.
+ * Can lookup Account information
+ * Can list categorized event types.
+![Config.Canvas.3](/images/Config.Canvas.3.png) 
+7. Under **Additional Settings**, select the **Privacy Level** as **PUBLIC**.
+![Config.Canvas.4](/images/Config.Canvas.4.png) 
+8. Under **Placements**, make sure **Link Selection** and **Assignment Selection** are selected.
+![Config.Canvas.5](/images/Config.Canvas.5.png) 
+9. Click **Save**. The key should now appear and listed with the name you provided. 
+10. Ensure that the newly added key is set to **Enabled**.
+11. Ensure to uncheck the "eye" for the key under the "Actions", as it allows the developer key to be used. 
+11. Take note of the following parameters:
+ * **Client ID**: the number in the **Details** column, above the **Show Key** button
+![Config.Canvas.6](/images/Config.Canvas.6.png) 
+
+At the account level, external tools must be installed in the External Apps page in Account Settings. The Assessment Application can be added via the Client ID option. Only the Client ID is required to be added.
+
+1. Click **Settings** from the left navigation pane.
+2. Click **View App Configurations**.
+3. Click **+App**.
+4. Enter the following information:
+ * **Configuration Type**: select **By Client ID**
+ * **Client ID**: enter the "Client ID" from the LTI key registration.
+![Config.Canvas.7](/images/Config.Canvas.7.png) 
+5. Click **Submit**.
+6. If the Client ID is associated with an external tool, the tool name displays in the page. The page also confirms the tool should be installed.
+![Config.Canvas.8](/images/Config.Canvas.8.png) 
+7. Click **Install**.
+8. Repeat the above installation steps to install the application to every course you wish to use it in. 
+9. Continue to configure the Assessment application, by registering the parameters back in the Assessment application's registration page.
+
+The following steps show how to register the parameters back in the Assessment application's registration page. If you are not the one who deployed the application, you need to provide these parameters to that person.
+
+1. Open the tool registration page from your browser.
+2. Enter the following information:
+  * **Display name**: give the tool a name of your choice. 
+  * **Issuer**: enter **https://canvas.instructure.com** (this should always be canvas.infrastructure.com not matter your tenant url)
+  * **JWK Set URL**: enter https://[tenant-name].instructure.com/api/lti/security/jwks
+  * **Access Token URL**: enter https://[tenant-name].instructure.com/login/oauth2/token 
+  * **Authorization URL**: enter https://[tenant-name].instructure.com/api/lti/authorize_redirect 
+   NOTE: [tenant-name] is where your Canvas tenant name hosted by instructure. For example if the url of the LMS is https://canvas1.instructure.com, then the [tenant-name] is "canvas1". If you are using self-hosted Canvas, replace https://[tenant-name].instructure.com with your canvas URL.
+  * **Client ID**: enter "Client ID" from the LTI key registration.
+  * **Audience**: This can be left blank 
+3. Optionally, you can add your Institution name and logo on the registration page.
+4. Click **SAVE REGISTRATION**.
+
+You're all set. The Assessment tool is now configured on your Canvas LMS and your Educators will be able to use it within their courses. Follow the [educator guide](./USER_GUIDE.md) to create assignments that use the Assessment Application tool.
+
+

docs/EDUCATOR_GUIDE.md

@@ -1,14 +1,49 @@
 # Educator Guide
 
-This guide is designed for educators who use [Moodle LMS](https://moodle.org/).
+This guide is designed for educators who use [Moodle LMS](https://moodle.org/) and [Canvas LMS](https://learn.canvas.net/login/canvas).
 
 ## Table of content
 1. [How to create an assessment on Moodle using the Assessment App](#create-assessment)
-2. [How to set up an assessment in the Assessment App](#assessment-setup)
-3. [How to create a new question bank](#create-question-bank)
-4. [How to create a new question](#create-question)
-5. [How to import and export question banks](#import-export-question-banks)
-6. [How to browse Assessment Analytics](#assessment-analytics)
+2. [How to create an assessment on Canvas using the Assessment App](#create-assessment-canvas)
+3. [How to set up an assessment in the Assessment App](#assessment-setup)
+4. [How to create a new question bank](#create-question-bank)
+5. [How to create a new question](#create-question)
+6. [How to import and export question banks](#import-export-question-banks)
+7. [How to browse Assessment Analytics](#assessment-analytics)
+
+## How to create an assessment on Canvas using the Assessment App <a name="create-assessment-canvas"/>
+
+To begin, you need to login to Canvas LMS and follow the steps:
+
+1. Pick the course where you would like to create an assessment.
+
+![createassessment](../images/Educator.Canvas.1.PNG)
+
+2. Verify that the Assessment Application has been added as an external tool within this course by going to settings. If it hasn't, request the LMS admin to follow the [configuration guide](../docs/CONFIGURATION_GUIDE.md)
+
+![verification](../images/Educator.Canvas.7.PNG)
+
+3. Go to the Assignments section of the course and click **+ Assignment**.
+
+![assignments](../images/Educator.Canvas.2.PNG)
+
+4. Enter title to the assignment.
+
+![addtitle](../images/Educator.Canvas.3.PNG)
+
+5. Change **Points** to 100. Change **Display Grade as** to Percentage. Verify **Assignment Group** is set to Assignments
+
+![assessmenttool](../images/Educator.Canvas.4.PNG)
+
+6. Change the submission type to **External Tool**. Click on **Find**. Select the assessment application from the list of external tools. Tick the **Load This Tool In A New Tab** checkbox. Click on **Save**.
+
+![turnoffediting](../images/Educator.Canvas.5.PNG)
+
+7. Click **Save and Publish**.
+
+![createdassessment](../images/Educator.Canvas.6.PNG)
+
+The assessment should be created. You will be redirected to the assessment page, where you have to click on "Load Assessment In A New Window".  This will direct you to the Assessment App, where you can configure the created assessment: choose the deadline, assessment duration, questions and participants.
 
 ## How to create an assessment on Moodle using the Assessment App <a name="create-assessment"/>
 
@@ -118,15 +153,21 @@ Here is an example of how the downloaded question bank might look like:
     "questions":[
         {"name":"Applications of machine learning",
         "description":"Applications of machine learning are all around us",
-        "options":["True","False"],"answer":0},
+        "options":["True","False"],"answer":["0"],"textType": "text", "questionType":"MCQ"
         {"name":"Machine learning algorithms",
         "description":"Machine learning algorithms are meant to simulate",
         "options":["intelligent machines","the human brain","orangutans"],
-        "answer":1},
+        "answer":["0"], "textType": "text", "questionType":"MCQ"},
         {"name":"Example of a classical ML technique?",
         "description":"What is an example of a classical ML technique?",
         "options":["natural language processing","deep learning","neural networks"],
-        "answer":0},
+        "answer":["0"], "textType": "text", "questionType":"MCQ"},
+        {"name": "Examples of machine language techniques", 
+        "description": "Which of the following are machine language techniques", 
+        "options": ["Linear Regression", "Log Functions", "Random Forest"], 
+        "answer": ["0", "2"], 
+        "textType": "text", 
+        "questionType": "MCQ"}
     "assessmentType":"Quiz"
 }]
 ```
@@ -138,7 +179,48 @@ Click **Upload** on the top of the Home page. You will see a dialog window where
 ![selectqbtoupload](../images/selectqbtoupload.png)
 
 The question bank will appear in the list of question banks. 
-Please, note that currently, the Assessment App supports question banks only in JSON format. 
+There are currently four different question bank formats that are supported by the Assessment Application. 
+
+1. QTI format - This format is questions banks being imported from Canvas, which can be exported in QTI format. More information can be found [here](https://www.imsglobal.org/activity/qtiapip#:~:text=QTI%20is%20an%20open%20format,2.2%20and%20APIP%20version%201.1.)
+2. GIFT format - This format is for question banks being imported from Moodle, which can be exported in GIFT format. More information can be found [here](https://docs.moodle.org/311/en/GIFT_format#:~:text=GIFT%20format%20allows%20someone%20to,format%20available%20in%20Question%20bank.)
+3. Microsoft Open Source Curriculum quiz format - This format is for questions from the Microsoft Open Source Curriculum quizzes. More information can be found [here](https://docs.moodle.org/311/GIFT_format#:~:text=GIFT%20format%20allows%20someone%20to,format%20available%20in%20Question%20bank.)
+4. Assessment Application JSON format - This format is native to the assessment app and can be used if an Educator wishes to upload their questions via JSON format. The following JSON format must be followed. The following example shows one True/False question. 
+```
+[{
+    "name":"Introduction to Machine Learning",
+    "description":"Machine Learning for Beginners (Microsoft)",
+    "questions":[
+        {"name":"Applications of machine learning",
+        "description":"Applications of machine learning are all around us",
+        "options":["True","False"],"answer":["0"],"textType": "text", "questionType":"MCQ"
+    "assessmentType":"Quiz"
+}]
+```
+Please consider the following keys for the **questionType** attribute of the JSON. 
+If the question is of type True/False or Multiple Choice, questionType="MCQ". 
+If the question is of type Long answer/Short Answer, questiponType="QA"
+
+Please consider the following keys for the **textType** attribute of the JSON. 
+TextType indicates whether the question entered contains HTML embeddings or not. Some question banks exports such as those from Moodle LMS(GIFT), use HTML embeddings - and in that case the textType will be set to "html". In most cases, the textType should be set to "text". 
+
+Please consider the following information about the **Description** attribute of the JSON
+This attribute should describe the entire question as this will be shown to students before showing them the options/textbox. 
+
+Please consider the following information about the **Name** attribute of the JSON
+This attribute is for convenience purposes for the Educator, as they can get a quick summary of the question by looking at the Name, especially in the Question Bank view. 
+
+
+## What are the different question types supported <a name="question-type"/>
+1. Multiple Correct Answer - Educators can set a question description with multiple correct options for student to pick from. Student can select one or more correct options that they deem appropriate.  
+How is this marked? 
+Educators need to provide one or more correct answers to the question. Only if the student selects all provided answers do they receieve full on this question (score of 1), else 0. 
+2. True/False questions- Similar to Multiple Correct Answers, but the options are set to True and False. 
+How is this marked? 
+Educators need to provide the correc answer to this. Only if the student selects the correct answer, do they receive full on this question (score of 1), else 0. 
+3. Long/Short Answer - Educators can provide a question description, and students get to enter correct answers.
+How is this marked? 
+Educators can provide one or more correct answers to this question. If any of the correct answers match with the answer provided by the student, the student receives a full score (score of 1), else 0.  
+
 
 ## How to browse the Assessment Analytics <a name="assessment-analytics"/>