htwkmooc/codeocean
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document mandatory and optional LTI parameters

Browse Source 
Closes #1988
This commit is contained in:
Sebastian Serth
2024-02-13 13:35:34 +01:00
committed by Sebastian Serth
parent a903182216
commit 37e5dfaba1
1 changed files with 85 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/lti_parameters.md Normal file
View File

@ -0,0 +1,85 @@
# LTI Parameters
This document provides an overview of the Learning Tools Interoperability (LTI) parameters supported in CodeOcean. Those need to be configured in the Learning Management System (LMS) used to integrate CodeOcean. Once configured, the LTI parameters are passed to CodeOcean when a user accesses an exercise and might alter the defined behavior.
## Introduction
CodeOcean supports LTI in version 1.0 and 1.1 (recommended) with the LTI Basic Outcomes Service in version 1.1. The LTI standard with the Basic Launch component, which builds on top of OAuth 1.0 for authorization, provides access from an LMS and allows for deep linking to a specific exercise. During the launch, the LMS submits basic user information and passes some general, platform, or course-specific parameters to the external tool such as CodeOcean. On the other hand, the LTI Basic Outcome Service is used to send scores from CodeOcean back to the e-learning platform, where it might contribute to the learners' progress.
Regarding the development of an LTI consumer, we recommend consulting the [LTI specification](https://www.imsglobal.org/activity/learning-tools-interoperability) of the IMS Global Consortium, which defines the standard. Please note the different, incompatible versions of LTI: Version 1.2 and 2.0 are considered deprecated. Most systems use the older version 1.1 and some already adopted the newest version 1.3, which includes some breaking changes due to adopting OAuth 2.0. For now, we strongly recommend implementing LTI 1.1 for the best compatibility.
The LTI implementation of CodeOcean is fully compatible with the standard and interoperability has been proven with different LTI consumers. A great example for developers is the [LTI Tool Consumer emulator](https://lti.tools/saltire/tc), which provides debug insights for the LTI workflow.
### Terminology
| LTI Name | Description |
|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| Basic Outcome Service | An extension to the LTI standard providing the ability to transmit a score between 0.0 and 1.0 from the Tool Provider to the Tool Consumer |
| Gradebook | A collection of scores transmitted from a tool consumer for a specific user |
| Learning Information Services (LIS) | An extension to the LTI standard referencing a host to contact for updates to the grade book and learner-data, e.g., the HPI MOOC platform or Moodle |
| Resource | A specific exercise/activity within the Tool Provider that a learner can access |
| Roster | A group of learners that share some similarities, e.g., a school class or all participants in a MOOC |
| Tool Provider | An external system offering specific exercises/activities, e.g., CodeOcean |
| Tool Consumer | A Learning Management System, e.g., the HPI MOOC platform or Moodle |
## Standard LTI Parameters
| Parameter | Usage | Description |
|------------------------------------|--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `context_id` | recommended | A unique identifier for the course in the LMS. It must be unique per consumer (as configured in CodeOcean) if present and is used to create a *Study Group* in CodeOcean automatically. |
| `context_title` | optional | The name of the course in the LMS. This parameter is used to name the resulting *Study Group* once created. The *Study Group* in CodeOcean is not renamed automatically once created. |
| `lis_person_contact_email_primary` | required | The user's email address, as used for email notifications (such as for new replies to *Requests for Comments*. |
| `lis_person_name_full` | strongly recommended | A username as shown on the platform, e.g., for interactions with *Requests for Comments*. We encourage to use a display name rather than the real name here. |
| `lis_person_name_given` | optional, but required if no `lis_person_name_full` is given | The user's first name. We use this name as a fallback if no `lis_person_name_full` is provided. The user's family name is not used on CodeOcean. |
| `resource_link_id` | optional | A unique identifier of the exercise in the LMS used to launch CodeOcean. This parameter is not used, unless a `context_id` is missing. In that case, the `resource_link_id` is used to create a *Study Group* (since some implementations such as the dBildungscloud falsely provide the course information in this field). |
| `user_id` | required | A unique identifier for the current user in the LMS. It must be unique per consumer (as configured in CodeOcean). |
| `roles` | recommended, fallback if not given: `Learner` | One out of `Learner`, `Instructor`, and `Administrator` - depending on the permission of the user in the LMS. CodeOcean assigns the corresponding permissions to `Learner` and `Instructor` automatically. An `Administrator` must be confirmed manually through the database or Rails Admin interface for security reasons. |
| `lis_result_sourcedid` | optional | Required for the LTI Basic Outcome Service to store the user's points (unique for `context_id`, `resource_link_id`, `user_id` combination, valid until a new `lis_result_sourcedid` is generated) |
| `lis_outcome_service_url` | with Basic Outcome service: required | Required for the LTI Basic Outcome Service. A callback URL where the "outcome" (i.e., the points the user achieved) can be sent to. When this parameter is missing, CodeOcean will not be able to send any scores to the LMS. |
## Custom LTI Parameters
Besides the standard LTI parameters defined by the LTI standard, CodeOcean supports (and partially requires) custom parameters.
These parameters **must be prefixed by `custom_` according to the LTI standard** to be recognized by CodeOcean. Values for these parameters are case-sensitive, URL-encoded strings separated by an equal sign (`=`) from the parameter name. Hence, the parameter `custom_token` with the value `12345678` is passed as `custom_token=12345678`.
### Mandatory LTI Parameters
The following mandatory parameters must be passed from the LMS to CodeOcean.
| Custom Parameter | Description |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `token` | A unique identifier for the desired exercise to launch. This parameter is generated per exercise and can be retrieved by an administrator or teacher when viewing a "published" exercise. For each tool launch through LTI, this parameter is required (even for those "edge cases" where a user is not redirected to a specific exercise). |
### Optional LTI Parameters
Further, the following parameters can be used to customize the behavior of CodeOcean.
| Custom Parameter | Valid Values | Description |
|---------------------------------|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `bonus_points` | \<any\> | For LimeSurvey, a bonus point can be awarded by setting this parameter. The bonus point is given to users immediately when opening the survey and transmitted as a score of 100% to the LMS. |
| `locale` | one of `{en, de}` | Specify the system language on CodeOcean as shown for users. The value given must be one of the configured locales in CodeOcean and will take precedence over an automatic detection (based on the browser) or the fallback to English. |
| `pair_programming` | not set or one of `{mandatory, optional}` | If the parameter is not set, the exercise is opened in individual work mode. If the parameter is set to `mandatory`, the exercise can only be solved in pair programming with a partner. If the parameter is set to `optional`, each user can decide for themselves whether they want to solve the exercise with a partner or alone. |
| `redirect_target` | Any valid path on the CodeOcean instance | Instead of opening an exercise, the user can be redirected to any internal path of the current CodeOcean system. No external domain and no query parameters are supported. For example, a value of `/` will launch CodeOcean and redirect the user to the landing page afterwards. |
| `survey_id` | LimeSurvey ID, e.g., `123456` | Instead of opening an exercise, the user can be redirected to a LimeSurvey survey by setting this parameter. Currently, only surveys hosted on <https://survey.openhpi.de> are supported. |
#### Embed Options
Optionally, CodeOcean can be embedded in an another page, i.e., through an `iframe`. In this scenario, the following parameters are used to configure the behavior of the embedded CodeOcean environment. Those parameters are optional and each **must be prefixed by `custom_embed_options_`** to be recognized by CodeOcean. If an embed option should be configured, the value **must be `true`**. For example, only the configuration `custom_embed_options_hide_navbar=true` will effectively hide the top navigation bar, other combinations won't alter the behavior.
Embed options are stored in the user's (encrypted) session cookie and cannot be altered by them. The embed options can only be removed by logging out completely or by launching another exercise (without the respective embed options).
| Custom Parameter | Description |
|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `hide_navbar` | The navigation bar displayed at the top of CodeOcean is hidden. Usually, it shows the application name CodeOcean together with an option to select the UI language and provides access to *Request for Comments* posted by the user. |
| `hide_exercise_description` | The exercise description when working on a programming exercise is hidden. The teacher might use another editor, such as edtr.io or the dBildungscloud, to introduce to code. |
| `collapse_exercise_description` | The exercise description when working on a programming exercise is collapsed after launch and can be shown by the user. |
| `disable_run` | Users are disallowed to compile and execute their source code. |
| `disable_score` | Independent of the option to execute the source code, this option disables running the test cases. Thus, no score is available for display. |
| `disable_rfc` | CodeOcean prevents the user from creating new *Request for Comments* to seek for help. |
| `disable_redirect_to_rfcs` | After finalizing an exercise, the user is not redirected automatically to any suitable *Request for Comments*. Other redirect targets might still work if not disabled. If all redirect targets are disabled, a simple summary screen showing the score is displayed. |
| `disable_redirect_to_feedback` | After finalizing an exercise, the user is not redirected automatically to provide feedback for the exercise just finished. Other redirect targets might still work if not disabled. If all redirect targets are disabled, a simple summary screen showing the score is displayed. |
| `disable_interventions` | Usually, users get an intervention while working on an exercise in CodeOcean. The upcoming dialogue suggests to ask for help using *Request for Comments* or to take a short break. By setting this option, no intervention of learners occurs. |
| `hide_sidebar` | The left sidebar within CodeOcean providing a file tree to an exercise is hidden. As a result, learners are unable to switch, download or add files. |
| `read_only` | All source code files available in this exercise are read-only and cannot be altered. |
| `hide_test_results` | Detailed test results from score runs are hidden but the score itself is calculated and shown to the learner. |
| `disable_hints` | Automated hints are not provided to learners. These hints usually rephrase an error message that occurred during program execution and are intended to help learners to find their mistakes more quickly. |
| `disable_download` | Users are not allowed to download an archive with their current progress of all visible source code files. |