Overview
Terracotta provides a flexible LTI (Learning Tools Interoperability) integration that allows custom web activities to be embedded within learning management system (LMS) assignments. This guide explains how to create a custom webpage that can be seamlessly integrated with Terracotta into the LMS.
Configuration in Terracotta
To configure a custom web activity in Terracotta, begin by creating a new experiment. Add a new assignment. For the treatment that will integrate with the custom web activity, select External Integrations > Custom Web Activity, then you'll see the interface below:
In Box 1 (Launch to Custom Web Activity), provide the URL to the custom web activity, and indicate the maximum score that students can receive on the activity. Once you provide the URL, the Connection status should turn green and display “Connected”; then you can preview your activity in a new tab. Check the checkbox if the custom web activity is configured to allow students to view past submissions (advanced When Terracotta launches to your activity, it will append a set of launch parameters onto the URL.
In Box 2 (Return to Terracotta), you are provided with a return URL. Your custom web activity should redirect users to this return URL, and Terracotta expects that your custom web activity will append two URL parameters: (1) launch_token, and (2) score. If “score” is omitted, Terracotta will assume that the submission will receive the maximum score.
Configuration in the Custom Web Activity
When a custom web activity is integrated in Terracotta as a LMS assignment, your activity is responsible for supporting student learning, honoring the assignment settings set by the teacher, and reliably returning students’ outcome scores back the LMS.
Launch Parameters
The following variables are automatically provided to the custom web activity as URL parameters:
launch_token: A single-use token for launch validation and score return
anonymous_id: Anonymized student identifier. This ID matches Terracotta’s participant_id, however, depending on the configuration in Terracotta, students who access an custom web activity may not be consenting participants. Thus, we use the label anonymous_id to refer to students accessing custom web activities.
assignment_id: Unique identifier for the Canvas assignment
condition_name: Experimental condition name
due_at: Assignment due date and time
experiment_id: Unique identifier for the experiment (specific to the course)
remaining_attempts: Number of remaining submission attempts
submission_id: Unique identifier for the current submission attempt
Return to Terracotta
Terracotta expects that when a student completes the activity, they will be redirected to the URL:
https://app.terracotta.education/integrations
with two parameters appended to the URL: (1) launch_token, and (2) score. If “score” is omitted, Terracotta will assume that the submission will receive the maximum score.
Terracotta will not accept a score for a launch token that has already been used, nor will Terracotta accept a score for an activity that has 0 remaining attempts.
Best Practices
Record Granular Data: Your custom web activity will be responsible for a legitimate academic exercise, and it should keep records of users’ interactions, responses, and submissions. By doing so, your custom web activity will help ensure the integrity of students’ coursework.
Check if the Launch Token has Previously Been Used: If the external webpage receives a launch token that has previously been used, this indicates that a student is attempting to review their responses from a past submission. Check if the launch token has previously been used and that the anonymous_id and assignment_id of the current launch matches the anonymous_id and assignment_id of the past submission associated with the launch_token. If so, the external page should display the data from the past submission associated with the provided launch token, with no interactivity. Confirm that the anonymous_id and assignment_id in the URL parameters match those in the past submission before displaying the past submission.
NOTE: There is one reserved launch_token: 99999-99999-99999-99999-99999. This launch token is issued by Terracotta when previewing external integrations.
Communicate When There are No Available Attempts: When remaining_attempts is 0, the external webpage should still display the activity, but Terracotta will accept no submissions. In this situation, to avoid misleading students about whether they can make another submission, the external webpage should disable submission functionality.
Respect Due Dates: Consider warning users when they are accessing the webpage after the due date. Submissions made after the due date will be flagged in Canvas.
Score Calculation: The custom web activity is responsible for determining the student’s score on the activity, which should be returned to Terracotta as a URL parameter value with the name “score.”
A Minimal Example
Here is a minimal example of a custom web activity that will integrate with Terracotta:
https://github.com/terracotta-education/terracotta-external-integrations/blob/main/minimal_example.html
In the HTML body of this activity (contained within <body>…</body> tags), there is a single math question: Solve for x: 2x + 3 = 7. The student is instructed to type their answer in a text input field labeled “answer.” Note that this activity also includes a <p> tag for presenting feedback, and a hidden button to submit the activity.
<div id="activity-container">
<p>Solve for x: 2x + 3 = 7</p>
<label for="answer">Your answer for x:</label>
<input type="text" id="answer" name="answer">
<button id="answer-btn" onclick="checkAnswer()">Answer</button>
<p id="feedback"></p>
<button id="submit-btn" onclick="submit()" style="display:none">Submit</button>
</div>
Following this code (but still within the HTML body of the activity), there is a script that handles user input, records responses, and redirects back to Terracotta upon submission:
<script>
// Get URL parameters
const queryString = window.location.search;
const urlParams = new URLSearchParams(queryString);
const url_launch_token = urlParams.get('launch_token'); // Single-use launch token
const url_pid = urlParams.get('anonymous_id') // Participant ID
// Variable for the student's score
let score = 0;
// Container for responses
let responses = [];
function checkAnswer() {
// Get timestamp
var timestamp = Date.now();
// Correct answer
const correctAnswer = 2; // (2x + 3 = 7, x = 2)
// Get the user's answer from the input field
const userAnswer = document.getElementById("answer").value;
// Evaluate answer correctness
var correctness = parseFloat(userAnswer) === correctAnswer;
if (correctness) score += 1;
// Push the response
responses.push({
pid: url_pid,
question: "2x + 3 = 7",
correctAnswer: correctAnswer,
response: userAnswer,
correctness: correctness,
datetime: timestamp
});
// Display feedback and enable submit button
const feedback = document.getElementById("feedback");
feedback.textContent = JSON.stringify(responses); // save this
document.getElementById("answer-btn").disabled = true;
document.getElementById("submit-btn").style.display = 'inline-block';
}
function submit() {
window.location.href = `https://app.terracotta.education/integrations?launch_token=${url_launch_token}&score=${score}`
}
</script>
To summarize, the script receives the launch_token and the anonymous_id from URL parameters. It then initializes the user’s score (0), and a container to record the user’s responses ([]). Then a function is defined, checkAnswer(), which is called when the answer button (answer-btn) is pressed. The checkAnswer() function records a timestamp of the user’s response (in Unix timestamp format, the number of milliseconds since January 1, 1970), establishes the correct answer, evaluates the correctness of the user’s response, updates the user’s score, pushes the user’s response into the response container, and then displays the contents of the response container and enables a final submit button. The function submit() is called when the user presses the submit button, which redirects the user back to Terracotta with the provided launch_token and calculated score.
0 Comments