codeocean/docs/lti_parameters.md

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