Terracotta Qualtrics Integration Guide

Owned by Harmony Jankowski
Last updated: about 12 hours ago by Benjamin Motz
6 min read

Overview

Terracotta makes it possible for Qualtrics surveys to be embedded within learning management system (LMS) assignments. This guide explains how to create a Qualtrics survey that can be seamlessly integrated with Terracotta into the LMS. 

Terracotta was designed as a tool for experimental education research. To integrate a Qualtrics survey in Terracotta, you will first need to create an experiment in Terracotta. When creating an experiment, you will be able to create different experimental conditions and to set up an informed consent process. However, if you are not interested in these options, it’s possible to set up an experiment with only one treatment condition, where all students are assumed to be participants. 

⚠️ Terracotta does not share students’ names or identities with your Qualtrics survey. Instead, Terracotta assumes that your Qualtrics survey is anonymous, and sends an anonymous identifier to Qualtrics that can be used to connect Qualtrics responses to additional details about the student in Terracotta. If students will be asked to provide their name or any other personally identifiable information in your Qualtrics survey, make sure you have permission from your school. 

Configuration in Terracotta

To configure a custom web activity in Terracotta, you will first need to create a new experiment. Once the experiment is created, you will add a new assignment. For the treatment that will integrate with the custom web activity, select External Integrations > Qualtrics. Then you will see the interface below. 

image-20241219-175836.png

In Box 1 (Launch to Qualtrics), provide the URL to the Qualtrics survey, and indicate the maximum score that students can receive for their responses to the survey. Once you provide the URL, the Connection status should turn green and display “Connected”; then you will be able to preview your survey in a new tab. When Terracotta launches students to your survey, it will append a set of launch parameters onto the URL (listed below). 

In Box 2 (Return to Terracotta) you are being provided with a return URL. Your custom web activity should redirect users to this return URL. Terracotta expects that your Qualtrics survey will have two embedded data fields: (1) launch_token, and (2) score. If “score” is omitted, Terracotta will assume that the survey submission will receive the maximum score on the assignment.  

Note: Instructions on how to obtain the URL to your Qualtrics survey, and how to embed data fields are in A Minimal Example, below.

Launch Parameters

The following variables are automatically provided to the Qualtrics survey as URL parameters: 

  • launch_token: A single-use token for launch validation and score return. The launch token is in UUIDv4 format.  Note: There is a reserved launch token (00000000-0000-4000-A000-000000000000) that is used by Terracotta when the user is previewing a Qualtrics activity.

  • 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 

  • submission_id: Unique identifier for the current submission attempt 

  • condition_name: Experimental condition name  

  • experiment_id: Unique identifier for the experiment (specific to the course) 

  • due_at: Assignment due date and time 

  • remaining_attempts: Number of remaining submission attempts. If there are unlimited attempts available to the student, remaining_attempts = u.

Return to Terracotta

Terracotta expects that when a student completes the survey, they will be redirected to the URL:
     https://app.terracotta.education/integrations?launch_token=${e://Field/launch_token}&score=${e://Field/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.  

Best practices

  • Communicate When There are Limited Remaining Attempts: When the teacher has placed restrictions on the number of attempts that a student may submit in response to an assignment, it may be helpful for the Qualtrics survey to communicate this to the student (e.g., if there is only 1 attempt remaining). If there are unlimited attempts available to the student, remaining_attempts = u. A Qualtrics survey will never need to handle a situation where remaining_attempts = 0, because in this situation, Terracotta will not generate a launch_token and will not launch the student into the survey. 

  • Respect Due Dates: Consider warning users when they are accessing the webpage after the due date. Submissions made after the due date will be delivered into Canvas, but will be flagged as late. 

  • Score Calculation: The Qualtrics survey is responsible for determining the student’s score on the activity, which should be returned to Terracotta as an embedded data field with the name “score.” 

A Minimal Example

Here is a minimal example of a custom web activity that will integrate with Terracotta:

Create a new survey in Qualtrics. In this example, there is a single multiple choice question:

Solve for x: 2x + 3 = 7.  

image-20241217-194339.png

If you want students to receive scores based on the correctness of their responses, you need to set up scoring in Qualtrics. Click Survey Options, and then click Scoring, highlighted in yellow: 

Mark the correct answer. In the example shown below, the student will receive 1 point for selecting the option “2.” 

Go back the survey builder, and click Survey Flow. Add a new element to the survey flow, and select Embedded Data. You should enter two fields: launch_token and anonymous_id. The launch_token will be used when returning a student’s score to Terracotta. The anonymous_id refers to individual students, and can be used to connect survey responses to data in Terracotta. Once you have added these two fields, move the Embedded Data element to the top of the flow, as shown below: 

Now add another embedded data element at the bottom of the flow. The purpose of this element is to assign the student’s score to an embedded data field called “score.” Click “Set a value now” and navigate through the options to find the score: Insert Piped Text > Scoring > Score > Score. 

When complete, this is what your survey flow should look like. Click Apply to save the changes. 

Go back to the survey builder. At the bottom of the survey, select the End of Survey block. Change the End of Survey Message to “Redirect to URL” and paste the following URL into the website URL: 

https://app.terracotta.education/integrations?launch_token=${e://Field/launch_token}&score=${e://Field/score} 

Now publish your survey, and input the survey’s URL into Terracotta.